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.
Please check our Contributing Guide for more information about how to contribute with this repository.
Please read our Code of Conduct before contributing.
- Antifraud Provider API
- CMS API
- Catalog API Seller Portal
- Catalog API
- Checkout API
- Customer Credit API
- GiftCard Hub API
- GiftCard API
- GiftCard Provider Protocol
- Headless CMS API
- Intelligent Search 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
- Price Simulations API
- Pricing API
- Pricing Hub
- Profile System API
- Promotions & Taxes API
- Recurrence (v1 - deprecated)
- Reviews and Ratings API
- SKU Bindings API
- Search API
- Session Manager API
- Subscriptions (v2 - deprecated)
- Subscriptions (v3)
- VTEX Tracking API
- VTEX Do API
- VTEX ID API
- VTEX Shipping Network API
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 defaultservers
and authorization information.
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.
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.
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": []
}
]
โ ๏ธ 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.