Catalog logs

Integration Guides

Catalog logs

Status	Description
Success	Occurs when the exchange of messages between VTEX, connector and marketplace flow successfully.
Error	Occurs when the exchange of messages between VTEX, connector and marketplace present errors due to communication (500) or business errors (400). Recommendations: for 500 errors, it is highly recommended to use the contingency flow through the reprocessing queue with at least 10 attempts. After the attempt number is exceeded, we recommend using a DEADLETTER queue for infinite retrials.
Alert	Occurs when the exchange of messages between VTEX, connector and marketplace are able to process, but with a needed action from one of the systems involved.
Pending	Occurs when the exchange of messages between VTEX, connector and marketplace are in progress. Ex. SKUs are still in the connector’s processing queue, or waiting an async response from the marketplace.

Log endpoints

Connectors must offer an endpoint that allows the integration app to collect and present logs in the standard report screen. The endpoint should follow the format:

{urlBase}/{vtexaccount}/logs/

For this endpoint the parameters date and status should be included, following the status described in the Log messages table:


_10https://{urlBase}/logs/?DateAt=aaaa-mm-dd&status=all https://{urlBase}/logs/?DateAt=aaaa-mm-dd&status=sucess,error

The endpoint should return the payload described below, so the list of error messages can be assembled:


_14{ 
_14"Messages":[ 
_14   { 
_14"id": "13", 
_14"Operation": "", 
_14"Direction": "", 
_14"ContentSource": "", 
_14"ContentTransalted": "", 
_14"ContentDestination": "", 
_14"BusinessMessage": "", 
_14"Status": "", 
_14       }
_14    ]
_14 }

Content of the messages

The messages contained in logs should follow the standard defined below, allowing the user who operates VTEX platform and catalog to understand the situation:

Operation ID (id): allows to identify the unique log in any sort of operation.
Operation: identifies if an operation is a Catalog change, Offer creation, Price update, Inventory update, Order status update, Invoice sending, Tracking code sending.
Direction: allows to identify the origin and destination of the information. Ex. VTEX to Marketplace.
Content Source: payload sent by the origin solution. Ex. Order’s json, connected from the marketplace, allowing to identify the original message sent by the origin app.
Content Translated: message generated by the connector with transformations, filers and enrichments needed, allowing sellers to understand the actions executed.
Content destination: original payload sent by the destination software after processing trial.
Business message: in case of errors, message explaining the error under the business contexto, with guidance on how to solve the problem.
Status: should include the statuses of success, error, warning and pending.

Log messages

Each step of the catalog integration requires a specific set of Log messages. The list below points out which messages to use for each step, and the table describes all messages.

Get product list for an initial load: S1, A1, A2, A3, E1, E2, E3, E4, E5
How to get a new product to offer in the marketplace: S1, A1, A2, A3, E1, E2, E3, E4, E5
How to get product updates: S1, A1, A2, A3, E1, E2, E3, E4, E5
How to keep prices updated: S1, A1, A2, E1, E2, E3
How to keep stock updated: S1, A1, A2, A3, E1, E2, E3, E4, E5

Code	Event	User message	Error status	Response
S1	When sending the SKU registration to the marketplace	The SKU (VTEXId + name) was created in the marketplace with the code (marketplace ID). Link for the SKU within the marketplace.	Success	201
A1	When using the shopping cart simulation through the fulfillment API, the SKU is not retrieved in the items object	Oops, we couldn’t obtain the SKU price of (SKU_Id). Please check if the items below are configured correctly in the VTEX platform. On product registration, check if it is associated with the trade policy. On inventory simulation, check if the carrier attending the SKU exists. On price configuration, check if there’s a price associated with the trade policy.	Warning	400
A2	When checking if the SKU is inactive	Oops, the SKU is inactive in VTEX. We recommend that you check: In Catalog, identify the SKU and check if the field “Activate SKU” is checked. In Catalog, check if the image is uploaded. In inventory simulation, check if the carrier attending the SKU exists. On price configuration, check if there’s a price associated with the trade policy.	Warning	400
A3	When transforming the SKU’s registration data AND having to insert a standard value since VTEX doesn’t possess it.	Oops, we couldn’t find the values needed for product registration, with standard values accepted by the marketplace. {list containing FIELD and VALUE attributed}	Warning	200
E1	When transforming SKU registration data to the format demanded by the marketplace.	Oops, we couldn't prepare the SKU registration in the marketplace due to {list all errors occurred during data transformation, and in case any data infringes marketplace rules}. (Connectors should list all errors at once, so the user knows all actions needed to send the SKU).	Error	400
E2	When trying to communicate with the marketplace API used to register the product	Oops, the product registration in the {name} marketplace is unavailable right now. Don’t worry - we’ll try again in a few minutes. In case the problem persists, get in touch with the marketplace.	Error	500
E3	When sending the product registration to the marketplace, and obtaining failure for sending incorrect data.	Oops, we couldn't prepare the SKU registration in the marketplace due to {list all errors occurred during data transformation, and in case any data infringes marketplace rules}. (Connectors should list all errors at once, so the user knows all actions needed to send the SKU).	Error	400
E4	When trying to collect the category or attribute mapping from the mapper.	Oops, we couldn’t find the category {name of the category} mapping of the {SKU name + ID} SKU in the marketplace. Please access the link below to perform this mapping. {Link indicating the store’s mapper}.	Error	400
E5	When trying to communicate with the mapping API from the mapper.	OOps, the VTEX category mapping is unavailable right now. Don’t worry - we’ll try again in a few minutes. In case the problem persists, get in touch with the marketplace.	Error	500

The table above should be a part of the connector’s documentation. During the development and testing of the integration, if any other error scenarios are identified, and are not already mapped in this table, connectors should add it in their own documentation.