The initial load of products only occurs after the user installs and configures the connector to use the VTEX Catalog and communicate with the marketplace. All products active on the main account and associated to a sales channel must be sent to the marketplace.
Send initial load of products
Follow the steps below, to send the initial load of products in the integration’s flow:
- Connector validates the VTEX <> Marketplace authentication. In case it has expired, perform the update routine defined in the marketplace’s documentation. Otherwise, connectors should log the error AND put the VTEX notification in a contingency queue.
- VTEX Seller informs connector the sales channel’s ID for the integration.
- Connector collects the list of SKUs through the Get SKU by sales channel
- For each SKU retrieved, the connector must:
a. Collect details of each SKU through the Get SKU and Context endpoint.
b. Validate if the SKU is active through the
isActiveproperty. c. Validate if the SKU is associated to the sales channel used in the intgration through the
salesChannelproperty. d. Validate if the product is active through the Get Product by ID endpoint, through the
isActiveproperty. This step is optional, since the Get SKU and Context endpoint already delivers the attribute
IsProductActivefor this purpose. e. Identify whether the SKU conforms to the marketplace’s product registration rules. f. Validate if the product’s category is mapped in the marketplace. In case it is not mapped, the marketplace should put the SKU in the approval queue, until the mapping is complete. g. For SKUs sent with price and inventory levels set up, the connector should validate whether the SKU has price and inventory levels with the sales channel configured for the integration. This should be done through the Fulfillment Simulation endpoint, without the Postal Code. h. Collect:
- Inventory level on all available warehouses, through the
- Sales price value with applied promotions and discounts, through the
pricefield. It is also possible to retrieve the original price through the
- Inventory level on all available warehouses, through the
If all validations pass, the product or SKU is sent to the marketplace and the operation is logged according to information described in the Logs made available for users.
If the IDs between VTEX and the marketplace differ, the connector should store both values. This information will be used for SKU update operations.
️ Be mindful to make all validations at once, and before the SKU’s publication in the marketplace’s catalog. In case there’s an error detected, the connector presents the seller a list of actions to correct. This way we can avoid the correct - publish - correct cycle.
If products do not apply to steps a, b and c, an error log must be filed, and the connector should collect the next items on the list obtained by step 2.
To avoid processing gaps due to the big volume of information of the initial load of products, we recommend:
- Using an async messaging architecture, using individual queues by context and store.
- Creating mechanisms that respect the marketplace API limit rates. We suggest the standard use of the Circuit Breaker integration.
- In case any of the steps listed above presents failures in communication, we suggest using the contingency mechanism of deadLetters.
- Being TotalReader: whenever possible, in the data transformation process, using standard values accepted by the marketplace, in case the information is not filled or sent by VTEX.
- In case the marketplace’s processing is in lots - meaning that the connector assembles a group of SKUs, guaranteeing the the limit of records per lot is respected, according to marketplace riles, and sending them to the marketplace at once - it is fundamental to control the lot’s processing, to avoid sending SKU updates without making sure that the product exists in the marketplace.
- Keeping a states table to know which SKUs have not been integrated with success, attempt date and the response received. This allows the system to use the contingency flow effectively, avoiding infinite loops, and avoiding reaching the request limit.
Use the endpoints described below to get SKU, price and inventory details. It is important to note that when consuming this API, the connector must have a valid VTEX App Key and App Token. You can also download our Postman collection to access the API. The diagram illustrates the endpoints used in the integration:
Scenario 1: First load of products after integration’s activation
After configuring the communication with the marketplace, connectors must send the first load of products. For every product retrieved from the SKU list associated with the sales channel, the connector must:
- Validate category mapping.
- Collect skuId ‘s available in the sales channel associated with the marketplace.
- Get SKU information, like weight and dimensions.
- Use the Orderform simulation to get price and inventory level, if needed.
In case there’s any failures in an item, connectors should log the error, and move on to the next item on the list, until all SKUs are processed.
Scenario 2: Deactivate products if the integration is deactivated
If the integration’s deactivation is confirmed with the marketplace, connectors must deactivate products published in the marketplace.
- Get SKU information.
- Send SKU block or deactivation request.
- Exclude SKUs and clean state control of the integration’s SKUs.
️ Make sure that all steps are logged as either success or failure, to offer the operation’s full traceability. Check out the Logs made available for users page to learn more.
What VTEX needs to validate the integration flow
To consider the integration validated by VTEX, the connector should:
- Follow the step by step of the catalog integration flow.
- Create a table with VTEX and marketplace field mapping. It should include limitations, transformations, and required fields.
- Create a table that explicits which data is mandatory and which is recommended when registering products or SKUs and to improve the offer’s positioning in the marketplace’s storefront.
- Create a table with known error logs and actions that the user can do to solve the problem.
Template table for field mapping
|VTEX field||How to fill it in VTEX||VTEX API||Marketplace field|
|Image||Catalog page (SKU)||Images|