The VTEX Marketplace Protocol External Mapper API defines the catalog mapping protocol for external marketplace connectors. It enables synchronization of product categories, brands, and specifications between external marketplace catalogs and the VTEX catalog.
openapi: 3.0.0
info:
title: VTex Marketplace Protocol
description: "\r\nThe _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://portal.{environment}.com.br
description: Server URL.
variables:
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/api/channel-manager/channel/all:
get:
tags:
- External Marketplace
summary: VTex List all channels
description: This request returns a list of channels available channels with their respective IDs for partners external to VTEX.
operationId: list-all-channels
parameters:
- name: enviroment
in: path
description: Environment used as part of the URL.
required: true
style: simple
schema:
type: string
example: portal.vtexcommercestable.com.br
- 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
headers: {}
content:
application/json:
schema:
title: Response body
description: Expected response body from List all channels.
type: object
required:
- id
- name
properties:
id:
title: 'Id '
description: The channel id.
type: integer
example: 1
name:
title: Name
description: The channel name.
type: string
example: Mercado Livre
example:
id: 1
name: Mercado Livre
deprecated: false
/api/channel-manager/channel/:channelId:
get:
tags:
- External Marketplace
summary: VTex Retrieve channel
description: Retrieves a specific channel that already exists in Channel Manager.
operationId: retrieve-channel
parameters:
- name: enviroment
in: path
description: Environment used as part of the URL.
required: true
style: simple
schema:
type: string
example: portal.vtexcommercestable.com.br
- 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
headers: {}
content:
application/json:
schema:
type: object
title: ''
description: Expected response body from List all channels.
required:
- id
- name
properties:
id:
title: 'Id '
description: The channel id.
type: integer
example: 1
name:
title: Name
description: The channel name.
type: string
example: Mercado Livre
example:
id: 1
name: Mercado Livre
/api/mkp-category-mapper/connector/register:
post:
tags:
- External Marketplace
summary: VTEX Mapper Registration
description: |-
Mappes categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree.
To 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.
This endpoint allows connectors to register the external marketplace integration in VTEX Mapper.
In 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`?
For 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: 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:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/VtexMapperRegistration'
required: true
responses:
'200':
description: OK
headers: {}
deprecated: false
/api/mkp-category-mapper/categories/marketplace/{id}:
post:
tags:
- External Marketplace
summary: Send Category Mapping to VTEX Mapper
description: |-
Mappes categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree.
To 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.
This endpoint allows connectors to send the marketplace's category tree mapped in the integration.
Connectors should send the payload compacted in `.gzip` format.
For 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:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/sendCategoryMappingToVtexMapper'
required: true
responses:
'200':
description: OK
headers: {}
deprecated: false
/api/channel-manager/connector:
post:
tags:
- External Marketplace
summary: VTex 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: environment
in: path
description: Environment used as part of URL.
required: true
style: simple
schema:
type: string
example: https://portal.vtexcommercestable.com.br
- 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:
required:
- name
- website
- logo
- description
- segment
- availableCountries
- type
- isActive
- helpUrl
- connectorVtexAdminPath
- connectorPageUrl
- connectorApiEndpoint
- channelId
properties:
name:
type: string
title: name
example: Mercado Livre Classic
website:
type: string
title: website
example: mercadolivre.com.br
logo:
type: string
title: logo
example: https://g.foolcdn.com/art/companylogos/square/meli.png
description:
type: string
title: 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
title: segment
example: OTHERS
availableCountries:
type: array
title: availableCountries
items:
type: string
title: Countries
example: BRA
example:
- BRA
- ARG
type:
type: string
title: type
example: EXTERNAL
isActive:
type: boolean
title: isActive
example: true
helpUrl:
type: string
title: helpUrl
example: https://help.vtex.com/pt/tracks/configurar-integracao-do-mercado-livre--2YfvI3Jxe0CGIKoWIGQEIq
connectorVtexAdminPath:
type: string
title: connectorVtexAdminPath
example: /bridge/#/settings?openConfig=mercadolivre
connectorPageUrl:
type: string
title: connectorPageUrl
example: https://apps.vtex.com/vtexbr-tiktok-tbp/p
connectorApiEndpoint:
type: string
title: connectorApiEndpoint
example: portal.vtexcommercestable.com/api/meliintegration/notifications
channelId:
type: integer
title: channelId
example: 1
example:
- name: Mercado Livre Classic
website: mercadolivre.com.br
logo: https://g.foolcdn.com/art/companylogos/square/meli.png
description: 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: 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
headers: {}
content:
application/json:
schema:
type: object
title: Response body
required:
- id
- name
- website
- logo
- description
- helpUrl
- segment
- availableCountries
- availableStates
- type
- connectorPageUrl
- connectorVtexAdminPath
- connectorApiEndpoint
- channelId
- isGloballyAvailable
- ownerVtexAccount
- isActive
- isCertified
- contactInfo
- isConnectionActive
- affiliateId
properties:
id:
type: integer
title: id
example: 584
name:
type: string
title: name
example: Mercado Livre Classic
website:
type: string
title: website
example: mercadolivre.com.br
logo:
type: string
title: logo
example: https://g.foolcdn.com/art/companylogos/square/meli.png
description:
type: string
title: 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.
helpUrl:
type: string
title: helpUrl
example: https://help.vtex.com/pt/tracks/configurar-integracao-do-mercado-livre--2YfvI3Jxe0CGIKoWIGQEIq
segment:
type: string
title: segment
example: OTHERS
availableCountries:
type: array
title: availableCountries
items:
type: string
title: A Schema
example: BRA
example:
- BRA
- ARG
availableStates:
type: array
title: availableStates
items: {}
example:
- []
type:
type: string
title: type
example: EXTERNAL
connectorPageUrl:
type: string
title: connectorPageUrl
example: https://apps.vtex.com/vtexbr-tiktok-tbp/p
connectorVtexAdminPath:
type: string
title: connectorVtexAdminPath
example: /bridge/#/settings?openConfig=mercadolivre
connectorApiEndpoint:
type: string
title: connectorApiEndpoint
example: portal.vtexcommercestable.com/api/meliintegration/notifications
channelId:
type: integer
title: channelId
example: 1
isGloballyAvailable:
type: boolean
title: isGloballyAvailable
example: false
ownerVtexAccount:
type: string
title: ownerVtexAccount
example: vtex
isActive:
type: boolean
title: isActive
example: true
isCertified:
type: boolean
title: isCertified
example: false
contactInfo:
type: object
title: contactInfo
required:
- name
- email
- phone
- defaultMessage
properties:
name:
type: string
title: name
example: Jhon
email:
type: string
title: email
example: [email protected]
phone:
type: string
title: phone
example: (77) 7777-7777
defaultMessage:
type: string
title: defaultMessage
example: ''
example:
name: Jhon
email: [email protected]
phone: (77) 7777-7777
defaultMessage: ''
isConnectionActive:
type: boolean
title: isConnectionActive
example: false
affiliateId:
type: string
title: affiliateId
example: '1234'
example:
id: 584
name: Mercado Livre Classic
website: mercadolivre.com.br
logo: https://g.foolcdn.com/art/companylogos/square/meli.png
description: 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.
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: [email protected]
phone: (77) 7777-7777
defaultMessage: ''
isConnectionActive: false
affiliateId: '1234'
deprecated: false
/api/channel-manager/connector/all:
get:
tags:
- External Marketplace
summary: VTex 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.
operationId: list-all-connectors
parameters:
- name: environment
in: path
description: Environment used as part of URL.
required: true
style: simple
schema:
type: string
example: https://portal.vtexcommercestable.com.br
- 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
headers: {}
content:
application/json:
schema:
title: Response body
description: Expected success response from List all connector API.
type: object
required:
- metadata
- results
properties:
metadata:
title: metadata
description: Summary of data returned by the query.
type: object
required:
- totalCount
- currentPage
- pageSize
- totalPages
properties:
totalCount:
title: totalCount
description: Total data returned.
type: number
example: 493
currentPage:
title: currentPage
description: Current result page.
type: number
example: 1
pageSize:
title: pageSize
description: How many results will be displayed per page.
type: number
example: 5
totalPages:
title: totalPages
description: Total pages the query returned.
type: number
example: 99
example:
totalCount: 493
currentPage: 1
pageSize: 5
totalPages: 99
results:
title: results
description: Query result with information for each connector.
type: array
items:
title: ''
description: ''
type: object
required:
- id
- name
- website
- logo
- description
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-marketplace-protocol-external-mapper-openapi-original.yml