vtex / openapi-schemas

OpenAPI 3.0 JSON schemas. Files are automatically synced to the VTEX Developer Portal.

openapi-schemas

This documentation comprises VTEX's public APIs as OpenAPI 3.0 JSON schemas. Files are automatically synced with VTEX's Developer Portal API Reference page and can be imported to Postman following these instructions.

Contributing with the documentation

Please check our Contributing Guide for more information about how to contribute with this repository.

Code of Conduct

Please read our Code of Conduct before contributing.

VTEX APIs

• Antifraud Provider API
• Catalog API Seller Portal
• Catalog API
• Checkout API
• Customer Credit API
• Data Subject Rights API
• GiftCard Hub API
• GiftCard API
• GiftCard Provider Protocol
• Headless CMS API
• Intelligent Search API
• Intelligent Search Events API - Headless
• Legacy CMS Portal API
• License Manager API
• Logistics API
• Marketplace APIs - Sent Offers
• Marketplace APIs - Suggestions
• Marketplace Protocol - External Marketplace Mapper
• Marketplace Protocol - External Marketplace Orders
• Marketplace Protocol - External Seller Fulfillment
• Marketplace Protocol - External Seller Marketplace
• Master Data API - v1
• Master Data API - v2
• Message Center API
• Orders API
• Orders API (PII compliant)
• Payment Provider Protocol
• Payments Gateway API
• Policies System API
• Pricing API
• Pricing Hub
• Profile System API
• Promotions & Taxes API - v2
• Promotions & Taxes API
• Reviews and Ratings API
• SKU Bindings API
• Search API
• Session Manager API
• Subscriptions API (v3)
• VTEX Tracking API
• VTEX DO API
• VTEX ID API
• VTEX Shipping Network API

Requisites

Before contributing to this repository, read the following requisites.

• The files should follow the JSON OpenAPI 3.0 Specification.
• Check our internal OpenAPI Specification guidelines to make sure you meet the required file structure.
• Schema files should have a self-explanatory name that specifies the described API.
• Check templates/VTEX - Template openAPI.jsonc to see an example of an API schema file. It shows how to represent endpoints and parameters and includes VTEX's default servers and authorization information.

Servers

OpenAPI describes the full endpoint for accessing the API as {server URL} + {endpoint path} + {path parameters}.

Example: an endpoint with /api/getResults as the path, https://example.com as the URL in the server object and no parameters will send requests to the https://example.com/api/getResults URL.

Example - servers object:

"servers": [
    {
        "url": "https://{accountName}.{environment}.com.br",
        "description": "VTEX server URL.",
        "variables": {
            "accountName": {
                "description": "Name of the VTEX account. Used as part of the URL.",
                "default": "apiexamples"
            },
            "environment": {
                "description": "Environment to use. Used as part of the URL.",
                "enum": [
                    "vtexcommercestable"
                ],
                "default": "vtexcommercestable"
            }
        }
    }
],

The servers key contains an array of objects.

Authentication

Security schemes

Security schemes describe autentication types that are available in the API. You can check the all the available options in the Security Scheme Specification.

They should be added inside the components object.

The security schemes we use are:

"securitySchemes": {
    "appKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppKey",
        "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)."
    },
    "appToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppToken",
        "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)."
    },
    "VtexIdclientAutCookie": {
        "type": "apiKey",
        "in": "header",
        "name": "VtexIdclientAutCookie",
        "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours."
    }
}

Security requirement

If defined inside the Open API schema, the security object will define the required security schemes for all endpoints. This specifies that requests should have the X-VTEX-API-AppKey and X-VTEX-API-AppToken pair or VtexIdClientAutCookie as part of the request header.

If defined inside an endpoint object, the security object will define the security scheme for that specific endpoint.

The security object we use at VTEX is:

"security": [
        {
            "appKey": [],
            "appToken": []
        },
        {
            "VtexIdclientAutCookie": []
        }
    ]

Adding a new file

After creating a file for a new API reference in this repository, read this step-by-step to publish it on our Developer Portal.

openapi-schemas's Issues

Missing Catalog Seller Portal Get Products List API documentation

Previous version named CatalogV2 had the Get Products List method which returned all the products from the seller account with pagination - old URL https://developers.vtex.com/vtex-rest-api/reference/list

This method allowed for scenarios of quickly indexing the Seller Portal CatalogV2 products for the purpose of mapping the products to the Marketplace CatalogV1 - see project https://github.com/vtex-apps/seller-send-offers and specifically:

• https://github.com/vtex-apps/seller-send-offers/blob/master/node/clients/catalogv2.ts#L16
• https://github.com/ElefantOnlineSA/seller-send-offers/blob/MKTP-547/node/clients/catalogv2.ts#L27

Reference: #637

OPENAPI 3.0 Schema errors on multiple arrays found on logistics

Describe the bug
According to the OpenAPI schema 3.0 each type of array needs a sibling with the name "items".
At least in the logistics, this is not the case in some cases. Postman does NOT have a problem with this, but swagger (defining the spec) does!

The specification should more or less look like this, but is forgotten in some of the definitions in the logistics section. i did not cross check the others.

{
  "type": "array",
  "items": {
    "type": "string" | "object"
  }
}

Expected behavior
The specification should be followed and the code should be importable in swagger without any issues..

Screenshots
If applicable, add screenshots to help explain your problem.

Esquema Swagger inválido

Tentei gerar um cliente java usando o esquema swagger do Catalog API porém ele é inválido, segundo o Swagger Editor. Mesmo gerando o cliente com o ignore-spec ele fica com vários objetos de retorno e envio com nomes de Example e Request, criando um código muito porco. Se é o esquema oficial das APIs da Vtex poderia pelo menos seguir de verdade o padrão OpenAPI 3. @karenkrieger @brunoamui @JulianaMeyerArruda @brenobarreto @georgebrindeiro @garrucho

Autenticação appkey/token automática na coleção

Pessoal,

Eu não entendi direito o manual. Então não sei se está descrito como resolver.
Mas, estou com dificuldade no postman para por o 'X-VTEX-API-AppKey' e '{{X-VTEX-API-AppToken}}'.
Em todas as coleções, eles não vem preenchidos. Antigamente, vinham direto no header do request quando pvt. Agora eu preciso ficar preenchendo-os em cada request.
Para contornar isso, eu criei as 2 linhas abaixo no "Pré-request Script" de cada coleção. Mas, são muitas coleções.

pm.request.headers.add ({key: 'X-VTEX-API-AppKey', value: '{{X-VTEX-API-AppKey}}'})
pm.request.headers.upsert ({key: 'X-VTEX-API-AppToken', value: '{{X-VTEX-API-AppToken}}'} )

Existe outra forma de configurar 1 única vez o key/token e funcionar para todas as coleções?

SKU Create File não funciona

Estou tentando utilizar o exemplo disponível em https://developers.vtex.com/reference/catalog-api-sku-file#catalog-api-post-sku-file para criar uma nova imagem para um produto mas esse endpoint parece não estar funcionando. Poderiam corrigir ou me dizer o que estou fazendo de errado nesse caso?

Eu já confirmei que minhas credenciais estão OK (consigo fazer um GET nessa mesma API para listar as imagens desse SKU) e tentei fazer tanto através da URL quanto no meu postman recriando passo-a-passo, mas o resultado é sempre o mesmo (400 Bad Request - Parameter is not valid):

Request body:
{ IsMain: false, Label: 'label', Name: 'prod-bottle', Url: 'https://intellihub.s3.us-east-2.amazonaws.com/testobjs/07891150060883.jpg', Text: 'product-bottle' }

Response body:
{ "Message": "Parameter is not valid." }

Response header:
access-control-allow-origin: *
cache-control: no-cache
connection: keep-alive
content-length: 37
content-type: application/json; charset=utf-8
date: Fri, 09 Oct 2020 00:08:40 GMT
expires: -1
pragma: no-cache
server: Microsoft-IIS/10.0
x-aspnet-version: 4.0.30319
x-powered-by: ASP.NET
x-vtex-janus-router-backend-app: ctgapi-vv1.16.42+263

VTEX BUG

Cara eu não to conseguindo duplicar um site por cms vtex 8596144336

catalog api errors on schema

When I validate the schema with openapi tool generator on catalog api, I get these errors:

Errors:
        - attribute
          paths.'/api/catalog-seller-portal/products/{param}={value}'(get).responses.200.content.'application/json'.schema.items
          is missing
        - attribute
          paths.'/api/catalog-seller-portal/products/{productId}'(get).responses.200.content.'application/json'.schema.items
          is missing
        - attribute
          paths.'/api/catalog-seller-portal/products'(post).requestBody.content.'application/json'.schema.items
          is missing
        - attribute
          paths.'/api/catalog-seller-portal/products'(post).responses.200.content.'application/json'.schema.items
          is missing
        - attribute
          paths.'/api/catalog-seller-portal/products/{productId}'(put).requestBody.content.'application/json'.schema.items
          is missing

How to fix that?

Broken Catalog Seller Portal Get Product by external ID, SKU ID, SKU external ID or slug link

On the Catalog Seller Portal API reference page the link to the Get Product by external ID, SKU ID, SKU external ID or slug method is broken.

However, the documentation is present in the VTEX - Catalog API Seller Portal.json file https://github.com/vtex/openapi-schemas/blob/master/VTEX%20-%20Catalog%20API%20Seller%20Portal.json#L1352

Reference: #637

Existe algum curso para especializar-se em desenvolvimento VTEX?

Existe algum curso para especializar-se em desenvolvimento VTEX?

Procurei no Google e na plataforma VTEX, mas achei muito confuso e não consegui entender. Alguém pode me ajudar?