{"id":21835875,"url":"https://github.com/vtex/openapi-schemas","last_synced_at":"2025-03-21T14:26:46.154Z","repository":{"id":37077799,"uuid":"228885864","full_name":"vtex/openapi-schemas","owner":"vtex","description":"OpenAPI 3.0 JSON schemas. Files are automatically synced to the VTEX Developer Portal.","archived":false,"fork":false,"pushed_at":"2024-04-12T20:12:02.000Z","size":59316,"stargazers_count":103,"open_issues_count":15,"forks_count":132,"subscribers_count":104,"default_branch":"master","last_synced_at":"2024-04-14T13:20:09.851Z","etag":null,"topics":["openapi-schemas","vtex","vtex-apis"],"latest_commit_sha":null,"homepage":"https://developers.vtex.com/docs/api-reference","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vtex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-12-18T17:03:16.000Z","updated_at":"2024-04-15T17:13:47.632Z","dependencies_parsed_at":"2023-12-21T15:36:34.667Z","dependency_job_id":"d5b00690-b9f7-41ae-942d-e88da205c526","html_url":"https://github.com/vtex/openapi-schemas","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fopenapi-schemas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fopenapi-schemas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fopenapi-schemas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fopenapi-schemas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vtex","download_url":"https://codeload.github.com/vtex/openapi-schemas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244813309,"owners_count":20514592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi-schemas","vtex","vtex-apis"],"created_at":"2024-11-27T20:25:43.437Z","updated_at":"2025-03-21T14:26:46.133Z","avatar_url":"https://github.com/vtex.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# openapi-schemas\n\nThis documentation comprises VTEX's public APIs as OpenAPI 3.0 JSON schemas. Files are automatically synced with VTEX's Developer Portal [API Reference page](https://developers.vtex.com/docs/api-reference) and can be imported to Postman following [these instructions](https://learning.postman.com/docs/postman/collections/working-with-openAPI/).\n\n## Contributing with the documentation\n\nPlease check our [Contributing Guide](CONTRIBUTING.md) for more information about how to contribute with this repository.\n\n## Code of Conduct\n\nPlease read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\n## API Slug Mapping\n\nThe 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.\n\nRead the [Centralized API Slug Mapping](docs/centralized-api-slug-mapping.md) documentation to learn how API names are mapped to URL slugs and how to follow the naming conventions when adding new API schemas.\n\n## VTEX APIs\n\n- Antifraud Provider API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https://raw.githubusercontent.com/vtex/openapi-schemas/master/VTEX%2520-%2520Antifraud%2520Provider%2520API.json\u0026label=OpenAPI)\n- Catalog API Seller Portal ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Catalog%2520API%2520Seller%2520Portal.json\u0026label=OpenAPI)\n- Catalog API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Catalog%2520API.json\u0026label=OpenAPI)\n- Checkout API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Checkout%2520API.json\u0026label=OpenAPI)\n- Customer Credit API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Customer%2520Credit%2520API.json\u0026label=OpenAPI)\n- Data Subject Rights API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Data%2520Subject%2520Rights.json)\n- GiftCard Hub API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520GiftCard%2520Hub%2520API.json\u0026label=OpenAPI)\n- GiftCard API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Giftcard%2520API.json\u0026label=OpenAPI)\n- GiftCard Provider Protocol ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Giftcard%2520Provider%2520Protocol.json\u0026label=OpenAPI)\n- Headless CMS API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Headless%2520CMS%2520API.json\u0026label=OpenAPI)\n- Intelligent Search API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Intelligent%2520Search%2520API.json)\n- Intelligent Search Events API - Headless ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Intelligent%2520Search%2520Events%2520API%2520-%2520Headless.json)\n- Legacy CMS Portal API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Legacy%2520CMS%2520Portal%2520API.json)\n- License Manager API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520License%2520Manager%2520API.json\u0026label=OpenAPI)\n- Logistics API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Logistics%2520API.json\u0026label=OpenAPI)\n- Marketplace APIs - Sent Offers ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Marketplace%2520APIs%2520-%2520Sent%2520Offers.json\u0026label=OpenAPI)\n- Marketplace APIs - Suggestions ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Marketplace%2520APIs%2520-%2520Suggestions.json\u0026label=OpenAPI)\n- Marketplace Protocol - External Marketplace Mapper ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Marketplace%2520Protocol%2520-%2520External%2520Marketplace%2520Mapper.json\u0026label=OpenAPI)\n- Marketplace Protocol - External Marketplace Orders ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Marketplace%2520Protocol%2520-%2520External%2520Marketplace%2520Orders.json\u0026label=OpenAPI)\n- Marketplace Protocol - External Seller Fulfillment ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Marketplace%2520Protocol%2520-%2520External%2520Seller%2520Fulfillment.json\u0026label=OpenAPI)\n- Marketplace Protocol - External Seller Marketplace ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Marketplace%2520Protocol%2520-%2520External%2520Seller%2520Marketplace.json\u0026label=OpenAPI)\n- Master Data API - v1 ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520MasterData%2520API%2520-%2520v10.2.json\u0026label=OpenAPI)\n- Master Data API - v2 ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Master%2520Data%2520API%2520-%2520v2.json\u0026label=OpenAPI)\n- Message Center API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Message%2520Center%2520API.json\u0026label=OpenAPI)\n- Orders API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Orders%2520API.json\u0026label=OpenAPI)\n- Orders API - PII data architecture ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Frefs%2Fheads%2Fmaster%2FVTEX%2520-%2520Orders%2520API%2520PII%2520version.json)\n- Payment Provider Protocol ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Payment%2520Provider%2520Protocol.json)\n- Payments Gateway API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Payments%2520Gateway%2520API.json)\n- Policies System API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Policies%2520System%2520API.json)\n- Pricing API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Pricing%2520API.json)\n- Pricing Hub ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Pricing%2520Hub.json)\n- Profile System API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Profile%2520System.json)\n- Promotions \u0026 Taxes API - v2 ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Promotions%2520%2526%2520Taxes%2520API%2520-%2520v2.json)\n- Promotions \u0026 Taxes API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https://raw.githubusercontent.com/vtex/openapi-schemas/master/VTEX%2520-%2520Promotions%2520%26%2520Taxes%2520API.json)\n- Reviews and Ratings API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Reviews%2520and%2520Ratings%2520API.json)\n- SKU Bindings API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520SKU%2520Bindings%2520API.json)\n- Search API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Search%2520API.json)\n- Session Manager API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Session%2520Manager%2520API.json)\n- Subscriptions API (v3) ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Frefs%2Fheads%2Fmaster%2FVTEX%2520-%2520Subscriptions%2520API%2520v3.json)\n- VTEX Tracking API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520Tracking.json)\n- VTEX DO API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520VTEX%2520Do%2520API.json)\n- VTEX ID API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520VTEX%2520ID%2520API.json)\n- VTEX Shipping Network API ![Swagger Validator](https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fvtex%2Fopenapi-schemas%2Fmaster%2FVTEX%2520-%2520VTEX%2520Shipping%2520Network%2520API.json)\n\n## Requisites\n\nBefore contributing to this repository, read the following requisites.\n\n- The files should follow the JSON [OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).\n- Check our internal [OpenAPI Specification guidelines](https://www.notion.so/vtexhandbook/OpenAPI-Specification-guidelines-e3a681454798496292d6648e184a156e#344d2fc637c146ffa2ed61a119aa39ee) to make sure you meet the required file structure.\n- Schema files should have a self-explanatory name that specifies the described API.\n- Check [`templates/VTEX - Template openAPI.jsonc`](https://github.com/vtex/openapi-schemas/blob/master/templates/VTEX%20-%20Template%20openAPI.jsonc) to see an example of an API schema file. It shows how to represent endpoints and parameters and includes VTEX's default [`servers`](#servers) and [authorization](#authorization) information.\n\n### Servers\n\nOpenAPI describes the full endpoint for accessing the API as `{server URL}` + `{endpoint path}` + `{path parameters}`.\n\nExample: 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.\n\nExample - `servers` object:\n\n```json\n\"servers\": [\n    {\n        \"url\": \"https://{accountName}.{environment}.com.br\",\n        \"description\": \"VTEX server URL.\",\n        \"variables\": {\n            \"accountName\": {\n                \"description\": \"Name of the VTEX account. Used as part of the URL.\",\n                \"default\": \"apiexamples\"\n            },\n            \"environment\": {\n                \"description\": \"Environment to use. Used as part of the URL.\",\n                \"enum\": [\n                    \"vtexcommercestable\"\n                ],\n                \"default\": \"vtexcommercestable\"\n            }\n        }\n    }\n],\n```\n\nThe `servers` key contains an array of objects.\n\n### Authentication\n\n#### Security schemes\n\nSecurity schemes describe autentication types that are available in the API. You can check the all the available options in the [Security Scheme Specification](http://spec.openapis.org/oas/v3.0.0#security-scheme-object).\n\nThey should be added inside the `components` object.\n\nThe security schemes we use are:\n\n```json\n\"securitySchemes\": {\n    \"appKey\": {\n        \"type\": \"apiKey\",\n        \"in\": \"header\",\n        \"name\": \"X-VTEX-API-AppKey\",\n        \"description\": \"Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).\"\n    },\n    \"appToken\": {\n        \"type\": \"apiKey\",\n        \"in\": \"header\",\n        \"name\": \"X-VTEX-API-AppToken\",\n        \"description\": \"Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).\"\n    },\n    \"VtexIdclientAutCookie\": {\n        \"type\": \"apiKey\",\n        \"in\": \"header\",\n        \"name\": \"VtexIdclientAutCookie\",\n        \"description\": \"[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.\"\n    }\n}\n```\n\n#### Security requirement\n\nIf 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.\n\nIf defined inside an endpoint object, the `security` object will define the security scheme for that specific endpoint.\n\nThe `security` object we use at VTEX is:\n\n```json\n\"security\": [\n        {\n            \"appKey\": [],\n            \"appToken\": []\n        },\n        {\n            \"VtexIdclientAutCookie\": []\n        }\n    ]\n```\n\n### Adding a new file\n\nAfter creating a file for a new API reference in this repository, read [this step-by-step](https://github.com/vtexdocs/dev-portal-content#how-to-publish-a-new-api-reference-and-add-it-to-navigation) to publish it on our Developer Portal.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtex%2Fopenapi-schemas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtex%2Fopenapi-schemas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtex%2Fopenapi-schemas/lists"}