{ "openapi": "3.0.0", "info": { "title": "Marketplace Protocol", "description": "The **Marketplace Protocol** is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", "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/channel-manager/channel/all": { "get": { "tags": [ "External Marketplace" ], "summary": "List all channels", "description": "This request returns a list of channels available channels with their respective IDs for partners external to VTEX.\n\r\n\r## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "list-all-channels", "parameters": [ { "name": "an", "in": "query", "description": "VTEX's account name owned by the connector/partner.", "required": true, "style": "form", "schema": { "type": "string", "example": "accountName" } }, { "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": "Content-type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "title": "Id ", "description": "The channel id.", "type": "integer" }, "name": { "title": "Name", "description": "The channel name.", "type": "string" } } }, "example": { "id": 1, "name": "Mercado Livre" } } } } }, "deprecated": false } }, "/api/channel-manager/channel/:channelId": { "get": { "tags": [ "External Marketplace" ], "summary": "Retrieve channel", "description": "Retrieves a specific channel that already exists in Channel Manager.\n\r\n\r## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "retrieve-channel", "parameters": [ { "name": "an", "in": "query", "description": "VTEX's account name owned by the connector/partner.", "required": true, "style": "form", "schema": { "type": "string", "example": "accountName" } }, { "name": "channelId", "in": "path", "description": "Channel's ID in Channel Manager, available through the List All Channels endpoint.", "required": true, "style": "simple", "schema": { "type": "number", "example": 1 } }, { "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": "Content-type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } ], "responses": { "200": { "description": "OK", "content":{ "application/json":{ "schema":{ "type": "object", "properties": { "id": { "description": "Channel id.", "type": "integer" }, "name": { "description": "Channel name.", "type": "string" } } }, "example": { "id": 1, "name": "Mercado Livre" } } } } } } }, "/api/mkp-category-mapper/connector/register": { "post": { "tags": [ "External Marketplace" ], "summary": "VTEX mapper registration", "description": "Mapped categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree.\n\nTo perform this association, VTEX made VTEX Mapper available. It is a tool integrated into the VTEX platform that allows the user to relate categories created in VTEX to categories from the marketplace. \n\nThis endpoint allows connectors to register the external marketplace integration in VTEX Mapper. \n\nIn case VTEX Mapper detects an error and the call fails, the connector should check if mandatory information was sent correctly. Ex. Are URLs correctly registered in the properties `categoryTreeEndPoint` and `mappingEndPoint`? \n\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-guide).\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "vtex-mapper-registration", "parameters": [ { "name": "an", "in": "query", "description": "Name of the VTEX account. Used as part of the URL.", "required": true, "style": "form", "schema": { "type": "string", "example": "accountName" } }, { "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" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "displayName", "categoryTreeEndPoint", "mappingEndPoint", "properties" ], "type": "object", "properties": { "displayName": { "type": "string", "description": "Marketplace name, that will be displayed in VTEX Mapper.", "example": "Marketplace A" }, "categoryTreeEndPoint": { "type": "string", "description": "Endpoint that returns categories and attributes according to VTEX Mapper specifications.", "example": "http://api.vtexinternal.com.br/api/{marketplaceName}/mapper/categories" }, "mappingEndPoint": { "type": "string", "description": "Secure endpoint that will receive the category mapping sent by VTEX Mapper.", "example": "http://api.vtexinternal.com.br/api/{marketplaceName}/mapper/mapping" }, "properties": { "type": "object", "required": [ "allowsRemap" ], "description": "Refers to the `allowsRemap` property.", "properties": { "allowsRemap": { "type": "boolean", "description": "Allows remaping categories in case the marketplace or seller tree is altered. If marked as `true`, all trees will be remapped.", "example": false } } }, "CategoryTreeProcessingNotificationEndpoint": { "description": "The `CategoryTreeProcessingNotificationEndpoint` is optional, and should be an endpoint from the external marketplace, that will be notified after the marketplace's category tree is successfully processed or not.", "type": "string", "example": "https://CategoryTreeProcessingNotificationEndpoint.com/api" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/mkp-category-mapper/categories/marketplace/{id}": { "post": { "tags": [ "External Marketplace" ], "summary": "Send category mapping to VTEX Mapper", "description": "Mapping categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree. \n\nTo perform this association, VTEX made VTEX Mapper available. It is a tool integrated into the VTEX platform that allows the user to relate categories created in VTEX to categories from the marketplace. \n\nThis endpoint allows connectors to send the marketplace's category tree mapped in the integration. \n\nConnectors should send the payload compacted in `.gzip` format. \n\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-guide).", "operationId": "send-category-mapping-vtex-mapper", "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": "id", "in": "path", "description": "Code identifying returned in the *VTEX Mapper Registration* endpoint.", "required": true, "style": "simple", "schema": { "type": "string", "default": "123456789" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "categories", "id", "name" ], "type": "object", "properties": { "categories": { "type": "array", "description": "Array with Marketplace parent categories and their information.", "items": { "type": "object", "description": "Category information.", "required": [ "id", "name", "children" ], "properties": { "id": { "type": "string", "description": "ID of the parent category in the marketplace.", "example": "1" }, "name": { "type": "string", "title": "name", "description": "Name of the parent category in the marketplace.", "example": "Appliances" }, "children": { "type": "array", "description": "Array with children categories in the marketplace, and their information.", "items": { "type": "object", "description": "Children category information.", "required": [ "id", "name", "children", "specifications" ], "properties": { "id": { "type": "string", "description": "ID of the child category in the marketplace.", "example": "1a" }, "name": { "type": "string", "description": "Name of the child category in the marketplace.", "example": "Kitchen" }, "children": { "type": "array", "description": "Grandchildren categories in the marketplace. Send as array of `id`, `name` and `specifications`.", "items": { "type": "object", "description": "Grandchildren category information.", "required": [ "id", "name", "specifications" ], "properties": { "id": { "type": "string", "description": "Grandchild category ID.", "example": "123421345sadf" }, "name": { "type": "string", "description": "Grandchild category name.", "example": "Silverware" }, "specifications": { "type": "array", "description": "List of specifications of the granchild category.", "items": { "type": "object", "description": "Specifications of the grandchild category.", "required": [ "attributeName", "required", "attributeValues" ], "properties": { "attributeName": { "type": "string", "description": "Name of the attribute sent as a specification.", "example": "Size" }, "required": { "type": "boolean", "description": "If the specification is required, mark this flag as `true`. If not, mark it as `false`.", "example": true }, "attributeValues": { "type": "array", "description": "Values for the specified attribute.", "items": { "type": "object", "description": "Array of the multiple `valueNames` for the specificied attribute.", "required": [ "valueName" ], "properties": { "valueName": { "type": "string", "description": "Name of the value.", "example": "Small" } } } } } } } } }, "nullable": true }, "specifications": { "type": "array", "description": "Specifications for the product or SKU.", "items": { "type": "object", "description": "Specifications of children categories.", "required": [ "attributeName", "required", "attributeValues" ], "properties": { "attributeName": { "type": "string", "description": "Name of the attribute sent as a specification.", "example": "Color" }, "required": { "type": "boolean", "description": "If the specification is required, mark this flag as `true`. If not, mark it as `false`.", "example": false }, "attributeValues": { "type": "array", "description": "Values for the specified attribute.", "items": { "type": "object", "description": "Array of the multiple `valueNames` for the attribute specificied.", "required": [ "valueName" ], "properties": { "valueName": { "type": "string", "description": "Name of the value.", "example": "Red" } } } } } } } } } } } } } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/channel-manager/connector": { "post": { "tags": [ "External Marketplace" ], "summary": "Register connector", "description": "Registers a new connector in our platform. The account name informed in the request should be the one owned by the partner since it is the only account that will have permission to update or delete the connector.\r\n\r\nPossible values for field `type`:\r\n\r\n- `APP`, if using our App Template.\r\n- `EXTERNAL`, if not using App Template.\r\n\r\nPossible values for field `segment`:\r\n\r\n- `ADS`\r\n- `APPAREL_ACCESSORIES`\r\n- `BEAUTY_HEALTH`\r\n- `BOOKS_EDUCATION`\r\n- `CARS_AUTOPARTS`\r\n- `DEPARTMENT_STORES`\r\n- `ELETRONICS`\r\n- `FINANCIAL_INSURANCES`\r\n- `FOOD_BEVERAGES`\r\n- `GROCERY`\r\n- `HOME_APPLIANCES`\r\n- `HOME_FURNITURE_DECOR`\r\n- `JEWELRY`\r\n- `PET_SHOP`\r\n- `SPORTS_FITNESS`\r\n- `TOURISM`\r\n- `TOYS_HOBBIES`\r\n- `OTHERS`", "operationId": "register-connector", "parameters": [ { "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": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "VTEX's account name owned by the connector/partner, ex. `apiexemple`", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } } ], "requestBody": { "description": "Body of the request to execute the Resgister connector.", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "description": "Connector name.", "example": "Mercado Livre Classic" }, "website": { "type": "string", "description": "Connector website.", "example": "mercadolivre.com.br" }, "logo": { "type": "string", "description": "Connector logo URL.", "example": "https://g.foolcdn.com/art/companylogos/square/meli.png" }, "description": { "type": "string", "description": "Connector description.", "example": "MercadoLibre operates online commerce platforms in Latin America. It operates Mercado Libre Marketplace, an automated online commerce platform that enables businesses, merchants, and individuals to list merchandise and conduct sales and purchases online." }, "segment": { "type": "string", "description": "Market segment.", "example": "OTHERS" }, "availableCountries": { "description": "List of countries where connector is available for integration.", "type": "array", "items": { "description": "Country code.", "type": "string", "example": "BRA" } }, "type": { "description": "What type of connector, if it is native, VTEX or partner.", "type": "string", "example": "VTEX" }, "isActive": { "description": "Indicates whether connector is active (`true`) or not (`false`).", "type": "boolean", "example": true }, "helpUrl": { "type": "string", "description": "URL of connector integration documentation page.", "example": "help.vtex.com/helpurl" }, "connectorVtexAdminPath": { "description": "Admin VTEX URL, where the merchant will be redirected to manage and view his connections after integration.", "type": "string", "example": "/bridge/#/settings?openConfig=mercadolivre" }, "connectorPageUrl": { "description": "URL where the merchant will be redirected to start the onboarding process.", "type": "string", "example": "https://apps.vtex.com/vtexbr-tiktok-tbp/p" }, "connectorApiEndpoint": { "description": "Partner connector API base URL.", "type": "string", "example": "portal.vtexcommercestable.com/api/meliintegration/notifications" }, "channelId": { "description": "ID of the channel that a connector joins to.", "type": "string", "example": "1" } } }, "example": [ { "name": "Mercado Livre Classic", "website": "mercadolivre.com.br", "logo": "https://g.foolcdn.com/art/companylogos/square/meli.png", "description": "Mercado Libre operates online commerce platforms in Latin America. It operates Mercado Libre Marketplace, an automated online commerce platform that enables businesses, merchants, and individuals to list merchandise and conduct sales and purchases online.", "segment": "OTHERS", "availableCountries": [ "BRA", "ARG" ], "type": "EXTERNAL", "isActive": true, "helpUrl": "https://help.vtex.com/pt/tracks/configurar-integracao-do-mercado-livre--2YfvI3Jxe0CGIKoWIGQEIq", "connectorVtexAdminPath": "/bridge/#/settings?openConfig=mercadolivre", "connectorPageUrl": "https://apps.vtex.com/vtexbr-tiktok-tbp/p", "connectorApiEndpoint": "portal.vtexcommercestable.com/api/meliintegration/notifications", "channelId": 1 } ] } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Connector ID." }, "name": { "type": "string", "description": "Connector name." }, "website": { "type": "string", "description": "Connector website." }, "logo": { "type": "string", "description": "Connector logo URL." }, "description": { "type": "string", "description": "Connector description." }, "helpUrl": { "type": "string", "description": "URL of connector integration documentation page." }, "segment": { "type": "string", "description": "Market segment." }, "availableCountries": { "description": "List of countries where connector is available for integration.", "type": "array", "items": { "description": "Country code.", "type": "string" } }, "availableStates": { "description": "States in which the connector operates, valid only for connectors that have area restriction.", "type": "array", "items": { "type": "string", "description": "State code." } }, "type": { "description": "What type of connector, if it is native, VTEX or partner.", "type": "string" }, "connectorPageUrl": { "description": "URL where the merchant will be redirected to start the onboarding process.", "type": "string" }, "connectorVtexAdminPath": { "description": "Admin VTEX URL, where the merchant will be redirected to manage and view his connections after integration.", "type": "string" }, "connectorApiEndpoint": { "description": "Partner connector API base URL.", "type": "string" }, "channelId": { "description": "ID of the channel that a connector joins to.", "type": "string" }, "isGloballyAvailable": { "description": "Indicates whether connector is globally available (`true`) or not (`false`).", "type": "boolean" }, "ownerVtexAccount": { "description": "Connector account name in VTEX.", "type": "string" }, "isActive": { "description": "Indicates whether connector is active (`true`) or not (`false`).", "type": "boolean" }, "isCertified": { "description": "Indicates whether the connector is certified (`true`) or not (`false`).", "type": "boolean" }, "contactInfo": { "description": "Seller contact information.", "type": "object", "properties": { "name": { "description": "Name of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "email": { "description": "Email address of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "phone": { "description": "Phone of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "defaultMessage": { "description": "Introduction message and information of interest in the partnership with the merchant.", "type": "string" } } }, "isConnectionActive": { "description": "Indicates whether connection is active (`true`) or not (`false`).", "type": "boolean" }, "affiliateId": { "description": "Affiliate ID corresponding to the connector.", "type": "string" } } }, "example": { "id": 584, "name": "Mercado Livre Classic", "website": "mercadolivre.com.br", "logo": "https://g.foolcdn.com/art/companylogos/square/meli.png", "description": "Mercado Libre operates online commerce platforms in Latin America. It operates Mercado Libre Marketplace, an automated online commerce platform that enables businesses, merchants, and individuals to list merchandise and conduct sales and purchases online.", "helpUrl": "https://help.vtex.com/pt/tracks/configurar-integracao-do-mercado-livre--2YfvI3Jxe0CGIKoWIGQEIq", "segment": "OTHERS", "availableCountries": [ "BRA", "ARG" ], "availableStates": [], "type": "EXTERNAL", "connectorPageUrl": "https://apps.vtex.com/vtexbr-tiktok-tbp/p", "connectorVtexAdminPath": "/bridge/#/settings?openConfig=mercadolivre", "connectorApiEndpoint": "portal.vtexcommercestable.com/api/meliintegration/notifications", "channelId": "1", "isGloballyAvailable": false, "ownerVtexAccount": "vtex", "isActive": true, "isCertified": false, "contactInfo": { "name": "Jhon", "email": "jhon@marketplace.com", "phone": "(77) 7777-7777", "defaultMessage": "" }, "isConnectionActive": false, "affiliateId": "AFT" } } } } }, "deprecated": false } }, "/api/channel-manager/connector/all": { "get": { "tags": [ "External Marketplace" ], "summary": "List all connectors", "description": "Returns a paginated list of all connectors' registered in Channel Manager, taking into consideration the filters informed in the query string of the request.\n\r\n\r## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "list-all-connectors", "parameters": [ { "name": "an", "in": "query", "description": "Merchant's account name in VTEX, ex. `apiexemple`.", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } }, { "name": "segment", "in": "query", "description": "Filter data by connector's segment.", "required": false, "style": "form", "schema": { "type": "string", "example": "department_stores" } }, { "name": "orderByConnectorType", "in": "query", "description": "Order data using a custom logic by connector's' type, and not alphabetically.", "required": false, "style": "form", "schema": { "type": "string", "example": "true" } }, { "name": "active", "in": "query", "description": "Filter data by the connector's status.", "required": false, "style": "form", "schema": { "type": "string", "example": "true" } }, { "name": "name", "in": "query", "description": "Filter data by the connector's name.", "required": false, "style": "form", "schema": { "type": "string", "example": "Dafiti" } }, { "name": "page", "in": "query", "description": "Current page to load data from.", "required": false, "style": "form", "schema": { "type": "integer", "example": 1 } }, { "name": "pageSize", "in": "query", "description": "Page size to define number of results returned.", "required": true, "style": "form", "schema": { "type": "integer", "example": 15 } }, { "name": "country", "in": "query", "description": "Filter by connector's country.", "required": false, "style": "form", "schema": { "type": "string", "example": "bra" } }, { "name": "type", "in": "query", "description": "Filter by connector's type.", "required": false, "style": "form", "schema": { "type": "string", "example": "vtex" } }, { "name": "account", "in": "query", "description": "Filter by connector's owner account.", "required": false, "style": "form", "schema": { "type": "string", "example": "cea" } }, { "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": "content-type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Expected success response from List all connector API.", "type": "object", "properties": { "metadata": { "title": "metadata", "description": "Summary of data returned by the query.", "type": "object", "properties": { "totalCount": { "description": "Total data returned.", "type": "number" }, "currentPage": { "description": "Current result page.", "type": "number" }, "pageSize": { "description": "How many results will be displayed per page.", "type": "number" }, "totalPages": { "description": "Total pages the query returned.", "type": "number" } } }, "results": { "description": "Query result with information for each connector.", "type": "array", "items": { "description": "Connector information.", "type": "object", "properties": { "id": { "description": "Connector Id.", "type": "number" }, "name": { "description": "Connector name.", "type": "string" }, "website": { "description": "Connector website.", "type": "string" }, "logo": { "description": "URL of the logo used by the connector.", "type": "string" }, "description": { "description": "Connector presentation.", "type": "string" }, "helpUrl": { "description": "URL of connector integration documentation page.", "type": "string" }, "segment": { "description": "Market segment.", "type": "string" }, "availableCountries": { "description": "List of countries where connector is available for integration.", "type": "array", "items": { "description": "Country code.", "type": "string" } }, "availableStates": { "description": "States in which the connector operates, valid only for connectors that have area restriction.", "type": "array", "items": { "type": "string", "description": "State code." } }, "type": { "description": "What type of connector, if it is native, VTEX or partner.", "type": "string" }, "connectorPageUrl": { "description": "URL where the merchant will be redirected to start the onboarding process.", "type": "string" }, "connectorVtexAdminPath": { "description": "Admin VTEX URL, where the merchant will be redirected to manage and view his connections after integration.", "type": "string" }, "connectorApiEndpoint": { "description": "Partner Connector API base URL.", "type": "string" }, "channelId": { "description": "ID of the channel that a connector joins to.", "type": "string" }, "isGloballyAvailable": { "description": "In which version the connector is available.", "type": "boolean" }, "ownerVtexAccount": { "description": "Connector account name in VTEX.", "type": "string" }, "isActive": { "description": "Indicates whether the connector is active (`true`) or not (`false`).", "type": "boolean" }, "isCertified": { "description": "Indicates whether the connector is certified (`true`) or not (`false`).", "type": "boolean" }, "contactInfo": { "description": "Seller contact information.", "type": "object", "properties": { "name": { "description": "Name of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "email": { "description": "Email address of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "phone": { "description": "Phone of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "defaultMessage": { "description": "Introduction message and information of interest in the partnership with the merchant.", "type": "string" } } }, "isConnectionActive": { "description": "Indicates whether the connection is active (`true`) or not (`false`).", "type": "boolean" }, "affiliateId": { "description": "Affiliate ID corresponding to the connector.", "type": "string" } } } } } }, "example": { "metadata": { "totalCount": 513, "currentPage": 1, "pageSize": 15, "totalPages": 35 }, "results": [ { "id": 59, "name": "4R Comercial Sao Paulo", "website": "www.comercialsaopaulo.com", "logo": "https://comercialsaopaulo.vtexassets.com/assets/vtex.file-manager-graphql/logo/619f6f7f-bf67-4ed1-a15a-282b51f81e06___cd0426736f2550559c8688de3378681f.jpg", "description": "Somos uma empresa sedeada em Barreiras - BA, decidimos entrar no mundo do E Commerce e marketplace há alguns anos, pois já estávamos estabelecidos e sólidos com a nossa loja física em nossa cidade.\nHoje trabalhamos com um portfólio bem diversificado de produtos, que são eles:\n- Linha à bateria\n- Lazer e esporte\n- Camping\n- Ferramentas elétricas\n- Maquinários leves e pesados\n- Ferramentas manuais\n- E muitos outros segmentos\nSua ", "helpUrl": "help.vtex.com/helpurl", "segment": "DEPARTMENT_STORES", "availableCountries": [ "BRA" ], "availableStates": [ "SP", "PR", "BA", "ES", "AC" ], "type": "VTEX", "connectorPageUrl": "connector.vtex.com/connectorPageUrl", "connectorVtexAdminPath": "connector.vtex.com/connectorVtexAdminPath", "connectorApiEndpoint": "connector.vtex.com/connectorApiEndpoint", "channelId": "1234", "isGloballyAvailable": false, "ownerVtexAccount": "comercialsaopaulo", "isActive": false, "isCertified": true, "contactInfo": { "name": "Jhon Jones", "email": "comercialsp@comercialsaopaulo.com", "phone": "(77) 7777-7777", "defaultMessage": "Olá, aqui é (...) da (...). Adoraríamos incluir sua loja em nossa vitrine, pois acreditamos que (...). Seguem algumas informações importantes para darmos seguimento à nossa parceria:\n\n1) Nosso marketplace conta as categorias\n- A\n- B\n- C\n\n2) Nossa política de cobrança inclui uma taxa de (...) para cada compra, mais assinatura fixa de (...) por mês. \n\n3) Saiba mais sobre nossa política de devoluções e envio neste link (...)." }, "isConnectionActive": false, "affiliateId": "AFT" } ] } } } } }, "deprecated": false } }, "/api/channel-manager/connector/:connectorId": { "get": { "tags": [ "External Marketplace" ], "summary": "Retrieve connector", "description": "Retrieve a specific connector registered in VTEX platform.", "operationId": "retrieve-connector", "parameters": [ { "name": "connectorId", "in": "path", "description": "Connector's ID in Channel Manager, available through the List all connectors, or in the response of the registration.", "required": true, "style": "simple", "schema": { "type": "integer", "example": 46 } }, { "name": "an", "in": "query", "description": "VTEX's account name owned by the connector/partner.", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } }, { "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": "content-type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Expected response body of Retrieve connector", "type": "object", "properties": { "id": { "description": "The connector Id.", "type": "number" }, "name": { "description": "Connector name.", "type": "string" }, "website": { "description": "Website connector.", "type": "string" }, "logo": { "description": "Connector logo URL.", "type": "string" }, "description": { "description": "Description about the connector.", "type": "string" }, "helpUrl": { "description": "Link to User Documentation on Connector Setup.", "type": "string" }, "segment": { "description": "Connector segment.", "type": "string" }, "availableCountries": { "description": "Countries where the marketplace is available.", "type": "array", "items": { "description": "Country code.", "type": "string" } }, "availableStates": { "description": "Array of states where the marketplace is available.", "type": "array", "items": { "type": "string", "description": "State code." } }, "type": { "description": "Connector integration type.", "type": "string" }, "connectorPageUrl": { "description": "In the `connectorPageUrl` field, the partner fills in a complete URL where the merchant will be redirected to start the integration process.", "type": "string" }, "connectorVtexAdminPath": { "description": "It's the URL path inside our admin where the merchant can be redirected to manage and view his connection after it's already integrated.", "type": "string" }, "connectorApiEndpoint": { "description": "The field refers to the base URL of the partner connector's API.", "type": "string" }, "channelId": { "description": "Channel Id that can be queried through the List all channels.", "type": "number" }, "isGloballyAvailable": { "description": "In which version the connector is available.", "type": "boolean" }, "ownerVtexAccount": { "description": " Owner account VTEX.", "type": "string" }, "isActive": { "description": "Indicates the status of integration with the connector, whether it is active or not (`true`) or not (`false`).", "type": "boolean" }, "isCertified": { "description": "Indicates whether the connector is certified (`true`) or not (`false`).", "type": "boolean" }, "contactInfo": { "description": "Seller contact information.", "type": "object", "properties": { "name": { "description": "Name of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "email": { "description": "Email of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "phone": { "description": "Phone of the person responsible for the marketplace account interested in connecting to the merchant.", "type": "string" }, "defaultMessage": { "description": "Introduction message and information of interest in the partnership with the merchant.", "type": "string" } } }, "isConnectionActive": { "description": "Indicates whether connection is active (`true`) or not (`false`).", "type": "boolean" }, "affiliateId": { "description": "Affiliate ID corresponding to the connector.", "type": "string" } } }, "example": { "id": 46, "name": "B2W", "website": "https://venda.americanasmarketplace.com.br/cadastre-sua-loja/", "logo": "https://s3.amazonaws.com/Marketplace-Integration/Bridge/logos/skyhub.png", "description": "A B2W e as Lojas Americanas fizeram uma fusão, dando origem ao Americanas Marketplace. Através do conector nativo da VTEX, é possível integrar com a B2W e aumentar seus canais de venda.", "helpUrl": "https://help.vtex.com/pt/tracks/configurar-integracao-da-b2w--6w07SJBVqE020KIOOS8ygk", "segment": "DEPARTMENT_STORES", "availableCountries": [ "BRA" ], "availableStates": [ "SP", "PB", "AM" ], "type": "NATIVE", "connectorPageUrl": "https://example.com/start-integration", "connectorVtexAdminPath": "/admin/marketplace-network/configuration/skyhub/", "connectorApiEndpoint": "https://portal.vtexcommercestable.com.br/api/skyhubintegration", "channelId": 7, "isGloballyAvailable": false, "ownerVtexAccount": "vtex", "isActive": true, "isCertified": false, "contactInfo": { "name": "Jhon", "email": "jhon@marketplace.com", "phone": "(77) 7777-7777", "defaultMessage": "Olá, aqui é Jhon da B2W. Adoraríamos incluir sua loja em nossa vitrine, pois acreditamos que seria benéfico para ambos. Seguem algumas informações importantes para darmos seguimento à nossa parceria:\n\n1) Nosso marketplace conta com as categorias A, B, C\n\n2) Nossa política de cobrança inclui uma taxa de 10% para cada compra, mais assinatura fixa de R$ 100 por mês. \n\n3) Saiba mais sobre nossa política de devoluções e envio neste link." }, "isConnectionActive": true, "affiliateId": "BTW" } } } } }, "deprecated": false }, "post": { "tags": [ "External Marketplace" ], "summary": "Upsert merchant connection", "description": "Receives an event describing a connection update between the connector with the specified ID and the merchant specified in the query string./n/rThis information is used in the list all connectors route: the account name will be used to return the `isConnectionActive` and `affiliateId` fields.", "operationId": "upsert-merchant-connection", "parameters": [ { "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": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "connectorId", "in": "path", "description": "Connector's ID in Channel Manager, available through the list all connectors route, or in the response of the registration.", "required": true, "style": "simple", "schema": { "type": "integer", "example": 46 } }, { "name": "an", "in": "query", "description": "Merchant's account name in VTEX, ex. `apiexemple`.", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "isActive", "affiliateId" ], "type": "object", "properties": { "isActive": { "type": "boolean", "description": "Indicates whether connection is active (`true`) or not (`false`).", "example": false }, "affiliateId": { "type": "string", "description": "Affiliate ID corresponding to the connector.", "example": "AFT" } } } } } }, "responses": { "200": { "description": "OK" } }, "deprecated": false }, "delete": { "tags": [ "External Marketplace" ], "summary": "Remove connector", "description": "Removes a connector from VTEX platform. This action can only be executed by the account name that owns the connector's registration.", "operationId": "remove-connector", "parameters": [ { "name": "connectorId", "in": "path", "description": "Connector's ID in Channel Manager, available through the List all connectors route, or in the response of the registration.", "required": true, "style": "simple", "schema": { "type": "number", "example": 46 } }, { "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": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Merchant's account name in VTEX, ex. `apiexemple`.", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "put": { "tags": [ "External Marketplace" ], "summary": "Full update connector", "description": "Fully updates the connector's information. All required fields must be sent in the body of the request./n/nThis action can only be executed by the account name that owns the connector's registration.", "operationId": "full-update-connector", "parameters": [ { "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": "connectorId", "in": "path", "description": "Connector's ID in Channel Manager, available through the list all connectors route, or in the response of the registration.", "required": true, "style": "simple", "schema": { "type": "number", "example": 46 } }, { "name": "an", "in": "query", "description": "VTEX's account name owned by the connector or partner, ex. `apiexemple`.", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "description": "Body of the request to execute the Full update connector.", "content": { "application/json": { "schema": { "required": [ "name", "website", "logo", "description", "segment", "availableCountries", "connectorVtexAdminPath", "connectorApiEndpoint" ], "type": "object", "properties": { "name": { "type": "string", "example": "Mercado Livre Classic", "description": "Connector name." }, "website": { "type": "string", "example": "mercadolivre.com.br", "description": "Connector website." }, "logo": { "type": "string", "example": "https://g.foolcdn.com/art/companylogos/square/meli.png", "description": "Connector logo URL." }, "description": { "type": "string", "example": "Mercado Libre operates online commerce platforms in Latin America. It operates Mercado Libre Marketplace, an automated online commerce platform that enables businesses, merchants, and individuals to list merchandise and conduct sales and purchases online.", "description": "Marketplace presentation description." }, "segment": { "type": "string", "example": "OTHERS", "description": "Marketplace segment." }, "availableCountries": { "type": "array", "description": "Countries where integration is available.", "items": { "type": "string", "description": "Country code.", "example": "BRA" } }, "connectorVtexAdminPath": { "type": "string", "example": "/bridge/#/settings?openConfig=mercadolivre", "description": "Link to Admin VTEX page where the merchant can configure integration with connector." }, "connectorApiEndpoint": { "type": "string", "description": "Partner connector API base URL.", "example": "portal.vtexcommercestable.com/api/meliintegration/notifications" } }, "example": { "name": "Mercado Livre Classic", "website": "mercadolivre.com.br", "logo": "https://g.foolcdn.com/art/companylogos/square/meli.png", "description": "Mercado Libre operates online commerce platforms in Latin America. It operates Mercado Libre Marketplace, an automated online commerce platform that enables businesses, merchants, and individuals to list merchandise and conduct sales and purchases online.", "segment": "OTHERS", "availableCountries": [ "BRA", "ARG" ], "connectorVtexAdminPath": "/bridge/#/settings?openConfig=mercadolivre", "connectorApiEndpoint": "portal.vtexcommercestable.com/api/meliintegration/notifications" } } } } }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "patch": { "tags": [ "External Marketplace" ], "summary": "Partial update connector", "description": "Partially updates the connector's information. The payload follows the format defined by RFC 6902, where a list of operations is informed, including the path of the field inside the object and its value./n/nThis action can only be executed by the account name that owns the connector's registration.", "operationId": "partial-update-connector", "parameters": [ { "name": "connectorId", "in": "path", "description": "Connector's ID in Channel Manager, available through the list all connectors route, or in the response of the registration.", "required": true, "style": "simple", "schema": { "type": "number", "example": 46 } }, { "name": "an", "in": "query", "description": "VTEX's account name owned by the connector/partner, ex. `apiexemple`.", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexemple" } }, { "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": "Content-type", "in": "header", "description": "Required header to indicate the request is a PATCH.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json-patch+json" } } ], "requestBody": { "description": "Body of the request to execute the Partial update connector call.", "content": { "application/json": { "schema": { "required": [ "path", "op", "value" ], "type": "object", "properties": { "path": { "type": "string", "example": "/segment", "description": "What part of the configuration do you want to change." }, "op": { "type": "string", "example": "replace", "description": "Type of operation to be performed." }, "value": { "type": "string", "example": "DEPARTMENT_STORES", "description": "New value which will appear in the changed field." } } } } } }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } } }, "security": [ { "appKey": [], "appToken": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" } } }, "tags": [ { "name": "External Marketplace" } ] }