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
• Checkout API
• CMS - Change URI Schema
• Customer Credit API
• GiftCard Hub API
• GiftCard API
• GiftCard Provider Protocol
• Intelligent Search API
• License Manager API
• Logistics API
• Marketplace APIs
• Marketplace Protocol
• Master Data API - v1
• Master Data API - v2
• Orders API
• Orders API (PII compliant)
• Payment Provider Protocol
• Payments Gateway API
• Policies System API
• Price Simulations API
• Pricing API
• Pricing Hub
• Profile System API
• Promotions & Taxes API
• Recurrence (v1 - deprecated)
• Reviews and Ratings API
• Search API
• Session Manager API
• Subscriptions (v2 - deprecated)
• Subscriptions (v3)
• Tracking API
• VTEX Do 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 Checklist to make sure you meet the required file structure.
• Schema files should have a self-explanatory name that specifies the described API.
• Check VTEX_TEMPLATE.json 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": {
                "default": "apiexamples",
                "description": "Your VTEX account name"
            },
            "environment": {
                "enum": [
                    "vtexcommercestable",
                    "myvtex"
                ],
                "default": "vtexcommercestable"
            }
        }
    }
],

The servers key contains an array of objects. Readme.io, our documentation system, will select the first one and use the declared default values for the variables.

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 for VTEX's appKey and appToken are:

"securitySchemes": {
    "appKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppKey"
    },
    "appToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppToken"
    }
}

This specifies that the request should have X-VTEX-API-AppKey and X-VTEX-API-AppToken as variables in the request header.

Security requirement

If defined inside the Open API schema, the security object will define the required security schemes for all endpoints.

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": []
        }
    ]

Sync Automation

⚠️ To sync schema files with our Developer Portal, you should first contact @brunoamui and ask for assistance.

To sync a new file, open .github\workflows\readme-github-sync.yml and add a new step to the Sync job description, as exemplified below.

- name: Sync Template API #Replace "Template" with the API name
  uses: readmeio/[email protected]
  with:
    repo-token: '${{ secrets.GITHUB_TOKEN }}' # DON'T MODIFY -- Allows us to get the contents of your spec file
    readme-api-id: '123456' # ID of the API on Readme.io. You can find it on the API Definitions tab on Readme.io's dashboard
    api-file-path: 'VTEX_TEMPLATE.json' # Name of the API specification JSON file. The file must be on the root folder of the repository
    readme-api-key: ${{ secrets.README_API_KEY }} # DON'T MODIFY -- Readme.io API key 
    readme-api-version: '2.1' # ReadMe version to sync to

Alternatively, you can add a new step to the Sync_CLI job description, as shown below.

- name: Sync Template API  # Replace "Template" with the API name
  run: rdme swagger 'VTEX_TEMPLATE.json' --key=${{ secrets.README_API_KEY }} --version=v2.1 --id=123456
# Replace 'VTEX_Template.json' with the name of the API specification JSON file between ' '. The file must be on the root folder of the repository.
# DON'T MODIFY the 'key' value, it is the Readme.io API key.
# The 'version' is the Readme.io version to sync to.
# Replace the 'id' value with the ID of the API on Readme.io. You can find it on the API Definitions tab on Readme.io's dashboard.