Home

Awesome

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

Requisites

Before contributing to this repository, read the following requisites.

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.