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.

Table of Contents

• External contributions
• Code of Conduct
• API Slug Mapping
• VTEX APIs
• Requisites

• AI-Powered Documentation
• GitHub Actions

External contributions

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.

API Slug Mapping

The OpenAPI schema files in this repository follow a naming convention that integrates with the Developer Portal's centralized API slug mapping system. This ensures consistent URLs and naming across documentation.

Read the Centralized API Slug Mapping documentation to learn how API names are mapped to URL slugs and how to follow the naming conventions when adding new API schemas.

VTEX APIs

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

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 API key."
    },
    "appToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppToken",
        "description": "Secret token of the API key."
    },
    "VtexIdclientAutCookie": {
        "type": "apiKey",
        "in": "header",
        "name": "VtexIdclientAutCookie",
        "description": "User token, 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": []
        }
    ]

AI-Powered Documentation

⚠️ These tools are available exclusively for VTEX technical writers working in Cursor IDE. External contributors should follow the Contributing Guide for manual contributions.

This repository includes Cursor IDE commands for automated OpenAPI generation and maintenance:

Available Commands

• /generate-openapi - Generate OpenAPI schemas from source code
• /review-openapi - Review and update existing OpenAPI schemas
• /rate-openapi - Evaluate schema quality with automated scoring
• /analyze-pr-changes - Analyze PR changes for API impacts
• /spectral - Run Spectral linting and validate schemas

Documentation

Complete guides are available in the docs/openapi-gen/ directory:

• OpenAPI Generation Introduction - Overview of all commands
• Generating OpenAPI - Generate schemas from code
• Reviewing OpenAPI - Update existing schemas
• Rating Generated OpenAPI - Quality evaluation
• Analyzing PR Changes - PR impact analysis
• Spectral Linting - Schema validation

GitHub Actions

This repository uses GitHub Actions for automated workflows that help maintain code quality and generate necessary artifacts. Below are the details of each action:

Spectral Linter

Source File: .github/workflows/linter.yml

Summary: This action runs Spectral to lint OpenAPI specification files when pull requests are created or updated. It helps maintain consistency and quality in API specifications.

Trigger Conditions:

• On pull request creation or update

• actions/checkout@v4: Checks out the repository code
• mshick/add-pr-comment@v2: Adds automated comments to pull requests
• stoplightio/[email protected]: Runs the Spectral linter on OpenAPI files

Postman Collection Converter

Source File: .github/workflows/portman.yml

Summary: This action automatically converts OpenAPI specifications to Postman Collections when changes are made to JSON files in pull requests targeting the master branch.

Trigger Conditions:

• On pull request to master branch

• actions/checkout@v2: Checks out the repository code
• actions/setup-node@v2: Sets up Node.js environment
• @apideck/portman: NPM package for converting OpenAPI specs to Postman collections
• ad-m/[email protected]: Pushes generated files back to the repository

OpenAPI Preview

Source File: .github/workflows/openapi-preview.yml

Summary: This action automatically posts a preview comment on pull requests with direct links to visualize changed OpenAPI specs. The comment is created on PR open and updated on each new push.

Trigger Conditions:

• On pull request creation or update targeting any *.json file

• actions/checkout@v4: Checks out the repository code
• actions/github-script@v7: Posts and updates PR comments with preview links