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.
Before contributing to this repository, read the following requisites.
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.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.
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."
}
}
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": []
}
]
After creating a file for a new API reference in this repository, read this step-by-step to publish it on our Developer Portal.