openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account External Marketplace API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
tags:
- name: External Marketplace
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. \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)."
      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. \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:
        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: jhon@marketplace.com
                      phone:
                        type: string
                        title: phone
                        example: (77) 7777-7777
                      defaultMessage:
                        type: string
                        title: defaultMessage
                        example: ''
                    example:
                      name: Jhon
                      email: jhon@marketplace.com
                      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: jhon@marketplace.com
                    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
                      - helpUrl
                      - segment
                      - availableCountries
                      - availableStates
                      - type
                      - connectorPageUrl
                      - connectorVtexAdminPath
                      - connectorApiEndpoint
                      - channelId
                      - isGloballyAvailable
                      - ownerVtexAccount
                      - isActive
                      - isCertified
                      - contactInfo
                      - isConnectionActive
                      - affiliateId
                      properties:
                        id:
                          title: id
                          description: Connector Id.
                          type: number
                          example: 59
                        name:
                          title: name
                          description: Connecto's name.
                          type: string
                          example: 4R Comercial Sao Paulo
                        website:
                          title: website
                          description: Connector's Website.
                          type: string
                          example: www.comercialsaopaulo.com
                        logo:
                          title: logo
                          description: Logo used by the connector.
                          type: string
                          example: https://comercialsaopaulo.vtexassets.com/assets/vtex.file-manager-graphql/logo/619f6f7f-bf67-4ed1-a15a-282b51f81e06___cd0426736f2550559c8688de3378681f.jpg
                        description:
                          title: description
                          description: Connector presentation.
                          type: string
                          example: 'Somo 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.

                            Hoje trabalhamos com um portfólio bem diversificado de produtos, que são eles:

                            - Linha à bateria

                            - Lazer e esporte

                            - Camping

                            - Ferramentas elétricas

                            - Maquinários leves e pesados

                     

# --- truncated at 32 KB (201 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-external-marketplace-api-openapi.yml