{ "openapi": "3.0.0", "info": { "title": "Sent Offers", "description": "\r\nThe **Marketplace API** enables marketplaces and sellers hosted on VTEX to perform their collaborative operations. \r\n\r\n>⚠️ The marketplace must [create an appKey and appToken](https://developers.vtex.com/docs/guides/getting-started-authentication) for each non-VTEX seller that will use this API.", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.vtexcommercestable.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" } } } ], "paths": { "/api/sent-offers/channels": { "post": { "tags": [ "Offer Management" ], "summary": "Create Channel", "description": "❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\nThe first step for connectors to integrate with [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors) is to create a channel, that represents the marketplace to where sellers will send their offers. \n\nThis endpoint creates a channel and the integration developers should call it once for each marketplace. The information about the marketplace sent in the request will be shown to sellers in their [Offer Management UI](https://help.vtex.com/en/tutorial/offers-listing--7MRb9S78aBdZjFGpbuffpE). \n\nThe `feedId` created by this call will apply to all sellers connected to the given channel, and will be necessary for the next step of the integration flow, which is to [activate feed](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds). \n\n>\u2139\r\n> Offer Management is available for integrations with [Mercado Livre (Classic and Premium)](https://help.vtex.com/en/tracks/configurar-integracao-do-mercado-livre--2YfvI3Jxe0CGIKoWIGQEIq), [Netshoes](https://help.vtex.com/en/tracks/configurar-integracao-da-netshoes--5Ua87lhFg4m0kEcuyqmcCm), and VTEX marketplaces. For more information, see [Offer Management Integration Guide](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors).", "operationId": "CreateChannel", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the seller's VTEX account. Used as query param.", "required": true, "schema": { "type": "string", "default": "accountName" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannel" }, "example": { "vendor": "vtex", "name": "Amazon", "logo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/madeiramadeira.png" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The `feedId` attribute created by the connector that will identify sellers’ feeds with a channel. The `feedId` is always the same for the relation between sellers and channels, but connectors can create more than one `feedId` with a single marketplace, depending on their business rules. The `feedId` follows the standardized pattern `vendor.channel`.", "default": "vtex.amazon" }, "vendor": { "type": "string", "description": "Name of the connector making the integration.", "default": "vtex" }, "name": { "type": "string", "description": "Name of the channel with which the integration is being established.", "default": "Amazon" }, "logo": { "type": "string", "description": "URL redirecting to the image file of the graphic symbol that identifies the marketplace. The file must in PNG format, and the image's dimension should be 300x300 pixels.", "default": "https://marketplace.com/logos/logo.png" } }, "title": "CreateChannel", "example": { "id": "vtex.amazon", "vendor": "vtex", "name": "Amazon", "logo": "https://marketplace.com/logos/logo.png" } } } } } }, "deprecated": false } }, "/api/sent-offers/feeds": { "post": { "tags": [ "Offer Management" ], "summary": "Activate Feed", "operationId": "CreateFeed", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\nIn [Offer Management](https://developers.vtex.com/docs/guides/sent-offers-integration-guide-connectors), after [creating the channel](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/channels), the next step is to create a feed, which is a list updated nearly in real time with information about the seller's offers sent to the marketplace. \n\nThis endpoint allows the creation of a feed so that the seller's sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) is connected to the marketplace. Feeds are nearly real time updated with content provided by the marketplace and VTEX modules. \n\nThis endpoint should only be used once, to activate the channel and establish the connection. However, after a [feed is deactivated](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#delete-/api/sent-offers/feeds/-feedId-), in order to activate it again it will be necessary another call to this endpoint.The integration starts with the creation of the Feed. This endpoint is used to establish the connection between connector and seller through the Sent Offers. \n\nThe `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when calling this endpoint. It follows the pattern `vendor.channel`.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeedRequest" }, "example": { "id": "{{feedId}}", "affiliateId": "MKP", "salesChannels": "5" } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "title": "CreateFeed", "example": { "account": "grocery1", "id": "vtex.meli-classic", "affiliateId": "MDC", "salesChannel": "4" }, "properties": { "account": { "type": "string", "description": "Seller's account name." }, "id": { "type": "string", "description": "Channel's ID." }, "affiliateId": { "type": "string", "description": "Corresponds to the 3-digit [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) identification code created by the seller.", "default": "MKP" }, "salesChannel": { "type": "string", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created." } } }, "example": { "account": "grocery1", "id": "vtex.meli-classic", "affiliateId": "MDC", "salesChannel": "4" } } } } }, "deprecated": false }, "get": { "tags": [ "Offer Management" ], "summary": "List Feeds", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), a feed is a list of information about seller's offers sent to a marketplace, and it is updated in real-time with content provided by the marketplace and VTEX modules. \n\nSince a seller can have integrations with multiple marketplaces, numerous feeds can be associated with an account. This endpoint retrieves a list with all the feeds related to an account.", "operationId": "ListFeeds", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the Seller's VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "example": { "account": "grocery1", "id": "digibee.shopee", "affiliateId": "SHP", "salesChannel": "1", "channelName": "shopee", "channelLogo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/shopee.png" }, "properties": { "account": { "type": "string", "description": "Seller's account name." }, "id": { "type": "string", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when calling this endpoint. It follows the pattern `vendor.channel`." }, "affiliateId": { "type": "string", "description": "Corresponds to the 3-digit [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) identification code created by the seller." }, "salesChannel": { "type": "string", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMVa)) used in the integration." }, "channelName": { "type": "string", "description": "Name of the marketplace, or channel, present in the feed." }, "channelLogo": { "type": "string", "description": "URL redirecting to the image file of the graphic symbol that identifies the marketplace." } } }, "example": [ { "account": "grocery1", "id": "digibee.shopee", "affiliateId": "SHP", "salesChannel": "1", "channelName": "shopee", "channelLogo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/shopee.png" }, { "account": "grocery1", "id": "v2v.saggin", "affiliateId": "SGN", "salesChannel": "1", "channelName": "Saggin", "channelLogo": "https://saggin.myvtex.com/api/license-manager/site/pub/accounts/a44ab387-ab95-439e-81aa-7c1a56b45374/logos/show" }, { "account": "grocery1", "id": "vtex.amazon", "affiliateId": "MSM", "salesChannel": "1", "channelName": "Amazon", "channelLogo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/amazon.png" } ] }, "example": [ { "account": "grocery1", "id": "digibee.shopee", "affiliateId": "SHP", "salesChannel": "1", "channelName": "shopee", "channelLogo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/shopee.png" }, { "account": "grocery1", "id": "v2v.saggin", "affiliateId": "SGN", "salesChannel": "1", "channelName": "Saggin", "channelLogo": "https://saggin.myvtex.com/api/license-manager/site/pub/accounts/a44ab387-ab95-439e-81aa-7c1a56b45374/logos/show" }, { "account": "grocery1", "id": "vtex.amazon", "affiliateId": "MSM", "salesChannel": "1", "channelName": "Amazon", "channelLogo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/amazon.png" } ] } } } }, "deprecated": false } }, "/api/sent-offers/feeds/{feedId}": { "put": { "tags": [ "Offer Management" ], "summary": "Update Feed", "operationId": "UpdateFeed", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), a feed is a list of information about seller's offers sent to a marketplace. \n\nOnce you have [created a feed](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/channels), this endpoint allows the seller to update the sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) and [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) ID used in the integration with the marketplace.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeedRequest" }, "example": { "affiliateId": "MKP", "salesChannels": "5" } } }, "required": true }, "responses": { "204": { "description": "No Content", "headers": {} } }, "deprecated": false }, "get": { "tags": [ "Offer Management" ], "summary": "Get Feed by feedId", "operationId": "RetrieveFeed", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), after you have [created the channel](https://developers.vtex.com/vtex-rest-api/reference/createchannel), the next step is to create a feed, which is a list of information about the seller's offers sent to the marketplace. \n\nThis endpoint retrieves information about a specific feed by searching through its `feedId`.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "title": "RetrieveFeed", "type": "object", "example": { "account": "grocery1", "id": "vtex.meli-classic", "affiliateId": "vtex.meli-classic", "salesChannel": "5", "channelName": "Mercadolivre Classic", "channelLogo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/mercadolivre.png" }, "properties": { "account": { "type": "string", "description": "Seller's account name." }, "id": { "type": "string", "description": "Channel's ID." }, "affiliateId": { "type": "string", "description": "This attribute is created by the seller, in their VTEX store configuration." }, "salesChannel": { "type": "string", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created." }, "channelName": { "type": "string", "description": "Name of the channel where the offer was sent." }, "channelLogo": { "type": "string", "description": "Logo of the channel where the offer was sent." } } } } } } }, "deprecated": false }, "delete": { "tags": [ "Offer Management" ], "summary": "Deactivate Feed", "operationId": "DeleteFeed", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), a feed is a list of information about seller's offers sent to a marketplace. After [creating a feed](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds), it will be activated; and through this endpoint the seller can deactivate the feed. \n\nWhen a feed is deactivated, all data related to the marketplace is removed from Offer Management UI. That includes the channels, offers, interactions, and errors. \n\nDeactivating a feed does not mean deleting information, and the seller can restore the data by [activating the feed](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds) again.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } } ], "responses": { "204": { "description": "No Content", "headers": {} } }, "deprecated": false } }, "/api/sent-offers/feeds/{feedId}/skus/{skuId}/interactions": { "post": { "tags": [ "Offer Management" ], "summary": "Open Interaction", "operationId": "CreateInteraction", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), VTEX platform and marketplaces interact with offers through a medium called Interaction. For every action that happens to an offer, whether it is a status notification or a price update, the connector creates an Interaction about it. \n\nThis endpoint creates a new interaction for an SKU so that changes can be applied to an offer. The changes informed by interactions are related to: price, inventory, catalog and status. \n\nUsually, interactions process a single type of change at a time, but it is possible to add data about catalog, price, and inventory simultaneously in the same interaction.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } }, { "name": "skuId", "in": "path", "description": "This attribute is the SKU ID in the seller's perspective, registered in their VTEX Catalog.", "required": true, "style": "simple", "schema": { "type": "string", "default": "1234" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInteractionRequest" }, "example": { "startDate": "2020-10-29", "source": "seller", "origin": "catalog", "context": "setup" } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": {}, "content": { "application/json": { "schema": { "title": "CreateInteraction", "type": "object", "example": { "account": "grocery1", "feedId": "vtex.madeiramadeira", "skuId": "1", "id": "3D585672B15A418EBDFC4BC0E85120A5", "startDate": "2022-03-07T09:15:00Z", "result": "processing", "state": "open", "source": "seller", "origin": "inventory", "context": "setup", "logs": [] }, "properties": { "account": { "type": "string", "description": "Seller's account name." }, "feedId": { "type": "string", "description": "Attribute that identifies a feed between a seller and a channel. It follows a standardized pattern that will be used by connectors when establishing the connection between the two." }, "skuId": { "type": "string", "description": "SKU's unique identifier number." }, "id": { "type": "string", "description": "Connectors must extend the Sent Offers' codes by adding their own code IDs for mapping specific scenarios that apply to their own system. They can send those codes through a suffix ID added in an existing code." }, "startDate": { "type": "string", "description": "The day the interaction was created." }, "result": { "type": "string", "description": "Search interactions, filtering by result. Results can have the following values: \n\nSuccess: When events close their lifecycle successfully, and generate updates on an offer in terms of price, inventory, or catalog. \n\nFailure: When the connector has detected processes that have failed to be made due to an error. \n\nNotification: When there are processes with the connector that are worth mentioning, but there are no actual updates. Ex: discarded updates or sendings of an offer. \n\nProcessing: When an open interaction has not been concluded, and should still receive more steps." }, "state": { "type": "string", "description": "State, from the seller's address." }, "source": { "type": "string", "description": "This attribute defines the entity responsible for the interaction." }, "origin": { "type": "string", "description": "where the interaction originated from. Possible values include `catalog`, `price` or `inventory`." }, "context": { "type": "string", "description": "This field informs Sent Offers about an offer's lifecycle." }, "logs": { "type": "array", "description": "History of events related to interactions.", "items": { "type": "string" }, "properties": { "type": { "type": "string", "title": "type", "description": "Type of logs." } } } } } } } } }, "deprecated": false } }, "/api/sent-offers/feeds/{feedId}/skus/{skuId}/interactions/{interactionId}": { "get": { "tags": [ "Offer Management" ], "summary": "Get Interaction Data by interactionId", "operationId": "RetrieveInteraction", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), VTEX platform and marketplaces interact with offers through a medium called [interaction](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions). \n\nA unique code called `interactionId` is used to identify each interaction. This endpoint retrieves information about an interaction, searching by its `interactionId`. \n\nIt also retrieves existing logs through the `log` field.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } }, { "name": "skuId", "in": "path", "description": "This attribute is the SKU ID in the seller's perspective, registered in their VTEX Catalog.", "required": true, "style": "simple", "schema": { "type": "string", "default": "1234" } }, { "name": "interactionId", "in": "path", "description": "This attribute is the code used to identify an existing interaction.", "required": true, "style": "simple", "schema": { "type": "string", "default": "d3rdjjf094ma0do" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "title": "RetrieveInteraction", "type": "object", "example": { "account": "grocery1", "feedId": "vtex.madeiramadeira", "skuId": "1", "id": "7FC112C52F8F43E6A096E29B04AC63F6", "startDate": "2022-03-07T09:15:00Z", "result": "processing", "state": "open", "source": "seller", "origin": "inventory", "context": "setup", "logs": [] }, "properties": { "account": { "type": "string", "description": "Seller's account name." }, "feedId": { "type": "string", "description": "Attribute that identifies a feed between a seller and a channel. It follows a standardized pattern that will be used by connectors when establishing the connection between the two." }, "skuId": { "type": "string", "description": "SKU's unique identifier number." }, "id": { "type": "string", "description": "Connectors must extend the Sent Offers' codes by adding their own code IDs for mapping specific scenarios that apply to their own system. They can send those codes through a suffix ID added in an existing code." }, "startDate": { "type": "string", "description": "The day the interaction was created." }, "result": { "type": "string", "description": "Search interactions, filtering by result. Results can have the following values: \n\nSuccess: When events close their lifecycle successfully, and generate updates on an offer in terms of price, inventory, or catalog. \n\nFailure: When the connector has detected processes that have failed to be made due to an error. \n\nNotification: When there are processes with the connector that are worth mentioning, but there are no actual updates. Ex: discarded updates or sendings of an offer. \n\nProcessing: When an open interaction has not been concluded, and should still receive more steps." }, "state": { "type": "string", "description": "State, from the seller's address." }, "source": { "type": "string", "description": "This attribute defines the entity responsible for the interaction." }, "origin": { "type": "string", "description": "where the interaction originated from. Possible values include `catalog`, `price` or `inventory`." }, "context": { "type": "string", "description": "This field informs Sent Offers about an offer's lifecycle." }, "logs": { "type": "array", "description": "History of events related to interactions.", "items": { "type": "string" }, "properties": { "type": { "type": "string", "title": "type", "description": "Type of logs." } } } } } } } } }, "deprecated": false } }, "/api/sent-offers/feeds/{feedId}/skus/{skuId}/interactions/{interactionId}/close": { "post": { "tags": [ "Offer Management" ], "summary": "Close Interaction", "operationId": "CloseInteraction", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), VTEX platform and marketplaces interact with offers through a medium called [interaction](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions). \n\nOnce an interaction has fulfilled its initial goal and there are no more actions (or [logs](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions/-interactionId-/logs)) taking place within it, this endpoint closes an interaction.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } }, { "name": "skuId", "in": "path", "description": "This attribute is the SKU ID in the seller's perspective, registered in their VTEX Catalog.", "required": true, "style": "simple", "schema": { "type": "string", "default": "1234" } }, { "name": "interactionId", "in": "path", "description": "This attribute is the code used to identify an existing interaction.", "required": true, "style": "simple", "schema": { "type": "string", "default": "d3rdjjf094ma0do" } } ], "responses": { "204": { "description": "No Content", "headers": {} } }, "deprecated": false } }, "/api/sent-offers/feeds/{feedId}/skus/{skuId}/interactions/{interactionId}/logs": { "post": { "tags": [ "Offer Management" ], "summary": "Create Log", "operationId": "CreateLog", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), logs are the granular details of actions that happen within an [interaction](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions), and they are organized in a timeline. All of the micro-steps of an interaction are represented through logs; they are how interactions become visible in Offer Management UI. \n\nThis endpoint adds logs that take place within an interaction, which can be done after [creating an interaction](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions) so that there will be an `interactionId`. \n\n`Errors`: When Offer Management, or the connectors, find an error that prevents sending or updating an offer to a channel, they should open a type failure log, and fill in its details through the `errors` attribute. The information provided should enable sellers to identify and fix errors on their offers. \n\nThe connectors should go through every possible validation, identify all errors, and only after that create the failure log, with the information in a single request.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } }, { "name": "skuId", "in": "path", "description": "This attribute is the SKU ID in the seller's perspective, registered in their VTEX Catalog.", "required": true, "style": "simple", "schema": { "type": "string", "default": "1234" } }, { "name": "interactionId", "in": "path", "description": "This attribute is the code used to identify an existing interaction.", "required": true, "style": "simple", "schema": { "type": "string", "default": "d3rdjjf094ma0do" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLogRequest" }, "example": { "description": "Another log message with some information that is going to be relevant to our users", "date": "2020-03-22", "type": "information", "agent": "broadcaster", "evidence": { "request": "Explanation 1", "response": "Explanation 2" }, "data": { "externalOfferId": "123456", "inventory": "33", "salesPrice": "79.99", "currency": "BRL", "status": "disabled" }, "errors": { "code": "CTLG-001", "externalCode": "284692", "title": "Description includes HTML", "description": "Netshoes does not allow HTML tags in an offer's description. Access the product in your Catalog to remove the HTML tag.", "closableOrigins": [ "catalog", "price" ] } } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": {}, "content": { "application/json; charset=utf-8": { "schema": { "title": "CreateLog", "type": "object", "example": { "id": "438B39EF43A24425B6BF35343095DE04", "description": "Log description", "date": "2022-05-16T09:16:00Z", "agent": "MARKETPLACE", "evidence": {}, "type": "info" }, "properties": { "id": { "type": "string", "description": "Connectors must extend the Sent Offers' codes by adding their own code IDs for mapping specific scenarios that apply to their own system. They can send those codes through a suffix ID added in an existing code." }, "description": { "type": "string", "description": "Log's description." }, "date": { "type": "string", "description": "Date when the log was created." }, "agent": { "type": "string", "description": "Entity responsible for creating the entry." }, "evidence": { "type": "object", "description": "cURL with the call that the connector has made for a VTEX system.", "properties": { "request": { "type": "string", "description": "cURL with the request call that the connector has made for a VTEX system. It will provide the evidence needed to contextualize the entry, if the user needs to fully understand the process ocurred, or solve any errors." }, "response": { "type": "string", "description": "cURL with the response of the call that the connector has made for a VTEX system. It will provide the evidence needed to contextualize the entry, if the user needs to fully understand the process occurred, or solve any errors." } } }, "type": { "type": "string", "description": "Type of log." } } } } } } }, "deprecated": false } }, "/api/sent-offers/feeds/{feedId}/skus/{skuId}/interactions/{interactionId}/logs/{logId}": { "get": { "tags": [ "Offer Management" ], "summary": "Get Log Data by logId", "operationId": "RetrieveLog", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), logs are the granular details of actions that happen within an [interaction](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions), organized in a timeline. All interaction's micro-steps will be represented through logs; they are how interactions become visible in Offer Management UI. \n\nA unique code called `logId` is used to identify every log created. This endpoint enables the retrieval of information about a log by searching through its `logId`.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "feedId", "in": "path", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when establishing the connection between the two. It follows the pattern `vendor.channel`.", "required": true, "style": "simple", "schema": { "type": "string", "default": "vtex.amazon" } }, { "name": "skuId", "in": "path", "description": "This attribute is the SKU ID in the seller's perspective, registered in their VTEX Catalog.", "required": true, "style": "simple", "schema": { "type": "string", "default": "1234" } }, { "name": "interactionId", "in": "path", "description": "This attribute is the code used to identify an existing interaction.", "required": true, "style": "simple", "schema": { "type": "string", "default": "d3rdjjf094ma0do" } }, { "name": "logId", "in": "path", "description": "A log's identifying code. This attribute is obtained from the Open Log API, or from the response of a Search Interactions API.", "required": true, "style": "simple", "schema": { "type": "string", "default": "123456" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "title": "GetLog", "type": "object", "example": { "id": "91957CA041E343D8B921CECFBF9D8443", "description": "Log description", "date": "2022-05-16T09:16:00Z", "agent": "MARKETPLACE", "evidence": {}, "errors": [ { "code": "AUTH-001", "externalCode": "MYCODE-01", "title": "Error ao autenticar no marketplace", "description": "Token inválido", "closableOrigins": [ "inventory" ] } ], "type": "failure" }, "properties": { "id": { "type": "string", "description": "Connectors must extend the Sent Offers' codes by adding their own code IDs for mapping specific scenarios that apply to their own system. They can send those codes through a suffix ID added in an existing code." }, "description": { "type": "string", "description": "Log description" }, "date": { "type": "string", "description": "Date when the log was created." }, "agent": { "type": "string", "description": "Entity responsible for creating the entry." }, "evidence": { "type": "object", "description": "cURL with the call that the connector has made for a VTEX system." }, "errors": { "type": "array", "items": { "title": "Error", "type": "object", "properties": { "code": { "type": "string" }, "externalCode": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "closableOrigins": { "type": "array", "items": { "type": "string" } } }, "description": "A description about errors." } }, "type": { "type": "string", "description": "Type of log." } } } } } } }, "deprecated": false } }, "/api/sent-offers/search/interactions": { "get": { "tags": [ "Offer Management" ], "summary": "Search Interactions and their Logs", "operationId": "SearchInteractions", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n In [Offer Management](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors), VTEX platform and marketplaces interact with offers through a medium called [interaction](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions). The granular details of actions and micro-steps that happen within an interaction's are called [logs](https://developers.vtex.com/docs/api-reference/marketplace-apis-offer-management#post-/api/sent-offers/feeds/-feedId-/skus/-skuId-/interactions/-interactionId-/logs). \n\nThis endpoint retrieves information about interactions and all logs within it. It allows filtering interactions by using the following query params: `channel`, `brand`, `category`, `scope`, `result`, `fromDate`, `toDate`. This endpoint also counts with the following pagination query params: `sort`, `from`, `to`.", "parameters": [ { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as a query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "q", "in": "query", "description": "Customizable field for searching interactions.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{query}}" } }, { "name": "channels", "in": "query", "description": "Search interactions, filtering by channel.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{channelName}}" } }, { "name": "brand", "in": "query", "description": "Search interactions, filtering by brand.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{brand}}" } }, { "name": "category", "in": "query", "description": "Search interactions, filtering by category.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{category}}" } }, { "name": "scope", "in": "query", "description": "Search interactions, filtering by scope.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{scope}}" } }, { "name": "result", "in": "query", "description": "Search interactions, filtering by result. Results can have the following values: \n\nSuccess: When events close their lifecycle successfully, and generate updates on an offer in terms of price, inventory, or catalog. \n\nFailure: When the connector has detected processes that have failed to be made due to an error. \n\nNotification: When there are processes with the connector that are worth mentioning, but there are no actual updates. Ex: discarded updates or sendings of an offer. \n\nProcessing: When an open interaction has not been concluded, and should still receive more steps. This is a transitory state, considering that when an interaction is closed, it can only end with `success`, `failure` or `notification` as its result.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{result}}" } }, { "name": "sort", "in": "query", "description": "Search interactions filtering by sort.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{sort}}" } }, { "name": "from", "in": "query", "description": "Search interactions from a given point.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{from}}" } }, { "name": "to", "in": "query", "description": "Search interactions until a given point.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{to}}" } }, { "name": "fromDate", "in": "query", "description": "Search interactions from a specific date.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{fromDate}}" } }, { "name": "toDate", "in": "query", "description": "Search interactions until a given date.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{{toDate}}" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/api/sent-offers/search/errors": { "get": { "tags": [ "Offer Management" ], "summary": "Search Errors", "operationId": "SearchErrors", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n This endpoint provides the single source of truth of updated error codes in [Offer Management's](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors) configuration. It retrieves a list of all the error codes available at that moment. \n\nThe connector will retrieve all the error codes available directly on this API and use the codes that apply the most to their error scenarios. Then, the connector will implement these codes into every validation error inside their system. \n\nThis endpoint allows filtering errors by using the following query params: `channel`, `brand`, `category`, `errorCategory`. It also counts with the following pagination query params: `sort`, `from`, `to`, `q`.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as query param.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{accountName}}" } }, { "name": "q", "in": "query", "description": "Customizable field for searching error codes.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{query}}" } }, { "name": "channels", "in": "query", "description": "Search errors filtering by channels.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{channels}}" } }, { "name": "brand", "in": "query", "description": "Search errors filtering by brand.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{brand}}" } }, { "name": "category", "in": "query", "description": "Search errors filtering by category.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{category}}" } }, { "name": "errorCategory", "in": "query", "description": "Search errors filtering by error category.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{errorCategory}}" } }, { "name": "sort", "in": "query", "description": "Pagination that returns a range of ordered error codes.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{sort}}" } }, { "name": "from", "in": "query", "description": "Pagination that returns error codes from a given point.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{from}}" } }, { "name": "to", "in": "query", "description": "Pagination that returns error codes until a given point.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "{{to}}" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/api/sent-offers/error-codes/{errorCodeId}": { "get": { "tags": [ "Offer Management" ], "summary": "Get Error Code data by errorCodeId", "operationId": "RetrieveErrorCode", "description": ">❗The Offer Management module has been discontinued and is no longer supported. The module has been replaced by Offer Status.\r\nTo learn more, visit the [announcement](https://help.vtex.com/en/announcements/modulo-status-dos-anuncios-para-integracoes-com-marketplaces-vtex--1EeGgit1Brq3mmm8qhv2m3).\r\n\r\n This endpoint retrieves specific information about an error code in [Offer Management's](https://developers.vtex.com/vtex-rest-api/docs/sent-offers-integration-guide-connectors) configuration. It provides the single source of truth of updated information about an error code through the `errorCodeId`. \n\nThe connector will retrieve all the error codes available directly on this API and use the codes that apply the most to their error scenarios. Then, the connector will implement these codes into every validation error inside their system.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "errorCodeId", "in": "path", "description": "Id for the error code chosen.", "required": true, "style": "simple", "schema": { "type": "string", "default": "errorId" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "title": "Listallerrorcode", "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "solutionText": { "type": "string" }, "solutionLink": { "type": "string" } } }, "description": "Error description.", "example": [ { "id": "AUTH-001", "type": "Authorization", "description": "Authorization errors where the user can solve by himself just fixing something on the settings. For example, when the user/password is invalid, or a register field is missing...", "solutionText": "Check connector settings", "solutionLink": "http://{accountName}.myvtex.com/admin/bridge/#/settings" }, { "id": "AUTH-002", "type": "Authorization", "description": "Authorization errors where the user can't solve by himself and depends on someone else to solve. For example, when the user has no access to a specific resource" }, { "id": "CTLG-001", "type": "Generic mapping", "description": "Catalog mapping errors different from variation, attribute or category errors. For example, brand mapping or a specific field of that channel.", "solutionText": "Check mapping spreadsheet", "solutionLink": "http://{accountName}.myvtex.com/admin/bridge/#/settings" }, { "id": "CTLG-002", "type": "Variation mapping", "description": "Errors of variation mapping (SKU specifications). For example, when a color field/value is not mapped correctly.", "solutionText": "Check mapping spreadsheet", "solutionLink": "http://{accountName}.myvtex.com/admin/bridge/#/settings" }, { "id": "CTLG-003", "type": "Attribute mapping", "description": "Errors of attribute mapping (product specifications). For example, when product specifications are not mapped correctly.", "solutionText": "Check mapping spreadsheet", "solutionLink": "http://{accountName}.myvtex.com/admin/bridge/#/settings" }, { "id": "CTLG-004", "type": "Category mapping", "description": "Errors of category mapping. For example, when a category ID is not correct; when the user has mapped the parent-category instead of the child-category.", "solutionText": "Check mapping spreadsheet", "solutionLink": "http://{accountName}.myvtex.com/admin/bridge/#/settings" }, { "id": "CTLG-005", "type": "Product info", "description": "Generic errors of product information sending. For any case different that the other product information error codes don't support", "solutionText": "Check item on catalog", "solutionLink": "http://{accountName}.myvtex.com/admin/Site/ProdutoForm.aspx" }, { "id": "CTLG-006", "type": "Description", "description": "Description is not according as expected by the channel. For example, when the description is too long; when has HTML; when there is no description and is a mandatory field...", "solutionText": "Fix description", "solutionLink": "http://{accountName}.myvtex.com/admin/Site/ProdutoForm.aspx?id={productId}" }, { "id": "CTLG-007", "type": "Images", "description": "Images are not according as expected by the channel. For example, when the image must have white background; when has no images and is mandatory to have at least one...", "solutionText": "Fix images", "solutionLink": "http://{accountName}.myvtex.com/admin/Site/SkuForm.aspx?idSku={skuId}" }, { "id": "CTLG-008", "type": "Dimensions", "description": "Dimensions are not according as expected by the channel. For example, when the weight is below the minimum required; when the dimensions are not filled and is a mandatory field...", "solutionText": "Check dimensions", "solutionLink": "http://{accountName}.myvtex.com/admin/Site/SkuForm.aspx?idSku={skuId}" }, { "id": "CTLG-009", "type": "Title", "description": "Title is not according as expected by the channel. For example, when the title is too long; when the title doesn't meet the channel taxonomy...", "solutionText": "Check title", "solutionLink": "http://{accountName}.myvtex.com/admin/Site/ProdutoForm.aspx?id={productId}" }, { "id": "CTLG-010", "type": "Identifiers", "description": "Identifier is not according as expected by the channel. For example, when a EAN, ISBN or UPC is invalid; when a identifier is required but is not filled...", "solutionText": "Fix item's identifier", "solutionLink": "http://{accountName}.myvtex.com/admin/Site/SkuForm.aspx?idSku={skuId}" }, { "id": "CTLG-011", "type": "Channels' rules", "description": "Errors due channel's business rules that cannot be solved by the user. For example, when the product category is not supported by the channel; when a currency is not supported by the channel..." }, { "id": "CTLG-012", "type": "Moderation", "description": "Ad moderated, it does not comply with Mercado Livre policies", "solutionText": "Apply the actions in the moderation section" }, { "id": "CTLG-XXX", "type": "Variation mapping", "description": "Errors of variation mapping (SKU specifications)", "solutionText": "Download mapping spreadsheet", "solutionLink": "http://{accountName}.myvtex.com/admin/dummy-invalid-link/catalog/skus/{skuId}" }, { "id": "CTLG-YYY", "type": "Variation mapping YYY", "description": "Errors of variation mapping (SKU specifications) YYY", "solutionText": "Download mapping spreadsheet YYY", "solutionLink": "http://{accountName}.myvtex.com/admin/dummyyy-invalid-link/catalog/skus/{skuId}" }, { "id": "INVNT-001", "type": "Inventory", "description": "Errors directly related to all inventory scenarios. This scenarios are for every issue that blocks an inventory from being updated. For example, when the channel has a rule of minimum quantity of inventory for all SKUs of a product.", "solutionText": "Check inventory levels", "solutionLink": "http://{accountName}.myvtex.com/admin/inventory/?skuId={skuId}" }, { "id": "NTMAP-001", "type": "Not mapped", "description": "Errors not mapped by the connector. Commonly, it occurs when the channel's API starts to validate new things without communicating to the connector." }, { "id": "PRICE-001", "type": "Price", "description": "Errors directly related to all price scenarios. This scenarios are for every issue that blocks a price from being updated. For example, when a price changes on rate that is not allowed by the marketplace.", "solutionText": "Fix price", "solutionLink": "http://{accountName}.myvtex.com/admin/pricing/#/prices/?page=1&qtd=10&productId={productId}&productName=%22%22" } ] } } } } }, "deprecated": false } } }, "security": [ { "appKey": [], "appToken": [] } ], "components": { "schemas": { "CreateChannel": { "title": "CreateChannel", "required": [ "vendor", "name", "logo" ], "type": "object", "properties": { "vendor": { "type": "string", "description": "Name of the connector making the integration.", "default": "vtex" }, "name": { "type": "string", "description": "Name of the channel with which the integration is being established.", "default": "Amazon" }, "logo": { "type": "string", "description": "URL redirecting to the image file of the graphic symbol that identifies the marketplace. The file must in PNG format, and the image's dimension should be 300x300 pixels.", "default": "https://marketplace.com/logos/logo.png" } }, "example": { "vendor": "vtex", "name": "Amazon", "logo": "https://marketplace.com/logos/logo.png" } }, "CreateFeedRequest": { "title": "CreateFeedRequest", "required": [ "id", "affiliateId", "salesChannels" ], "type": "object", "properties": { "id": { "type": "string", "description": "The `feedId` attribute that identifies a feed between a seller and a channel, follows a standardized pattern that will be used by connectors when calling this endpoint. It follows the pattern `vendor.channel`.", "default": "vtex.amazon" }, "affiliateId": { "type": "string", "description": "This attribute is created by the seller, in their VTEX store configuration.", "default": "MKP" }, "SalesChannels": { "type": "string", "description": "This attribute is created by the seller, in their VTEX store configuration.", "default": "1" } } }, "UpdateFeedRequest": { "title": "UpdateFeedRequest", "required": [ "affiliateId", "salesChannels" ], "type": "object", "properties": { "affiliateId": { "type": "string", "description": "Corresponds to the 3-digit [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) identification code created by the seller.", "default": "MKP" }, "salesChannels": { "type": "string", "description": "This attribute is created by the seller, in their VTEX store configuration.", "default": "1" } } }, "CreateInteractionRequest": { "title": "CreateInteractionRequest", "required": [ "startDate", "source", "origin", "context" ], "type": "object", "properties": { "startDate": { "type": "string", "default": "2020-10-29" }, "source": { "type": "string", "description": "This attribute defines the entity responsible for the interaction. Possible values include `seller` or `channel`.", "default": "seller" }, "origin": { "type": "string", "description": "This attribute defines where the interaction originated from. Possible values include `catalog`, `price` or `inventory`. Interactions are usually used to deal with a single type of process at a time. However, there are situations in which data about catalog, price and inventory are added in the same interaction.", "default": "catalog" }, "context": { "type": "string", "description": "This field informs Sent Offers about an offer's lifecycle. When the integration has been recently installed, and producst are being sent for the first time, the value should be `setup`. If it's an update log, when the interaction is already up and running, the value should be `ongoing`.", "default": "setup" } } }, "CreateLogRequest": { "title": "CreateLogRequest", "required": [ "description", "date", "type", "agent", "evidence", "data", "errors" ], "type": "object", "properties": { "description": { "type": "string", "description": "In this field, connectors should describe relevant information about the log, so Sent Offers users can better understand the action taking place.", "default": "Insert your message" }, "date": { "type": "string", "description": "Logs follow a chronological timeline, so make sure the date included corresponds to the correct order of logs.", "default": "2020-03-22" }, "type": { "type": "string", "description": "Connectors are responsible for attributing the correct type for each log. Therefore, be mindful of their correct usage. \n\n`success`: only logs that conclude an interaction’s goal should be `“type”=”success”`. \n\n`information`: logs that expose the actions of an update process, to provide visibility and contribute with more technical investigations. Information logs may include internal processes of a system (`agent` attribute), or calls between two systems. \n\n`warning`: logs used in cases where the communication between two systems fails, and there are no actions that the user can take to fix it. They are usually cases where the connector should perform a retry, and provide visibility of what is being attempted again. \n\n`failure`: logs noticed by the connector as errors that prevent an offer from being correctly sent and synced to a channel.", "default": "information" }, "agent": { "type": "string", "description": "Entity responsible for creating the entry.", "default": "broadcaster" }, "evidence": { "$ref": "#/components/schemas/Evidence" }, "data": { "$ref": "#/components/schemas/Data" }, "errors": { "$ref": "#/components/schemas/Errors" } } }, "Evidence": { "title": "Evidence", "description": "cURL with the call that the connector has made for a VTEX system. It will provide the evidence needed to contextualize the entry, if the user needs to fully understand the process ocurred, or solve any errors.", "required": [ "request", "response" ], "type": "object", "properties": { "request": { "type": "string", "description": "cURL with the request call that the connector has made for a VTEX system. It will provide the evidence needed to contextualize the entry, if the user needs to fully understand the process ocurred, or solve any errors.", "default": "GET https://www.vtex.com" }, "response": { "type": "string", "description": "cURL with the response of the call that the connector has made for a VTEX system. It will provide the evidence needed to contextualize the entry, if the user needs to fully understand the process occurred, or solve any errors.", "default": "200 Ok" } } }, "Data": { "title": "Data", "description": "Data related to an offer, that will be updated or sent for the first time during setup.", "required": [ "externalOfferId", "inventory", "salesPrice", "currency", "status" ], "type": "object", "properties": { "externalOfferId": { "type": "string", "description": "The ID used by the channel to identify this offer. Fill in this field if there are any updates in that ID.", "default": "123456" }, "inventory": { "type": "string", "description": "Updated inventory level of that offer. Fill in this field if there are any updates in inventory.", "default": "33" }, "salesPrice": { "type": "string", "description": "The value the offer is being sold for, on the channel. Fill in this field if there are any updates in price.", "default": "79.99" }, "currency": { "type": "string", "description": "The currency applied to the offer's `salesPrice`. The international currency code should be used as value for this field. Fill in this field if there are any updates in price.", "default": "BRL" }, "status": { "type": "string", "description": "The offer status can have the following values: \n\n`Synced`: when offers are successfully sent to a channel and are currently being synced between both entities.\n\n`Sending`: intermediate state, when offers are still in the process of being sent to a channel. This status involves offers that are either sent for the first time to the marketplace, migrated to a new marketplace, or resent offers that were once deleted from a channel. \n\n`Error`: when Sent Offers finds an error that prevents sending or updating an offer to a channel. Therefore this status requires manual correction. \n\n`Disabled`: when the offer is discarded by the connector, by being inactive or not included in the trade policy,", "default": "disabled" } } }, "Errors": { "title": "Errors", "description": "When Sent Offers, or the connectors, find an error that prevents sending or updating an offer to a channel, they should open a `failure` log, and fill in its details through this `errors` attribute. From the information sent through this attribute, sellers can identify and fix errors on their offers. Connectors must identify all errors, and send them all in a single request. This means that connectors should go through every possible validation, and only after all errors are identified, create the failure log.", "required": [ "code", "externalCode", "title", "description", "closableOrigins" ], "type": "object", "properties": { "code": { "type": "string", "description": "The Search Errors endpoint returns the updated list of error codes. It is the only source of truth about the codes and where they will be always updated. Fill in this field with the code corresponding to the error identified.", "default": "CTLG-001" }, "externalCode": { "type": "string", "description": "Connectors must extend the Sent Offers' codes by adding their own code IDs for mapping specific scenarios that apply to their own system. They can send those codes through a suffix ID added in an existing code. This way the Sent Offers knows which errors must be archived and which errors must be kept, being able to classify that given error and improve its solving action. These suffix IDs are totally managed by the connectors, which will require them a way to map each error inside their own code.", "default": "284692" }, "title": { "type": "string", "description": "Short text summarizing the error identified. It will be the title that appears in the Sent Offers' UI.", "default": "Description includes HTML" }, "description": { "type": "string", "description": "Short text giving more context about the error identified. It will be the description of the error mentioned in the title, also appearing in the Sent Offers' UI.", "default": "Netshoes does not allow HTML tags in an offer's description. Access the product in your Catalog to remove the HTML tag." }, "closableOrigins": { "type": "array", "description": "Values allowed in this field are `catalog`, `price` and `inventory`.", "default": [ "catalog", "price" ] } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" } } }, "tags": [ { "name": "Offer Management" } ] }