{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "VTEX Shopee Integration API", "description": "The VTEX Shopee Integration API provides endpoints for handling Shopee order webhooks, reprocessing order synchronization workflows, querying Shopee order data, and receiving VTEX marketplace order callbacks." }, "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.", "example": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "example": "vtexcommercestable" } } } ], "paths": { "/api/shopeeintegration/order/shipping/label": { "get": { "tags": [ "Shopee orders" ], "summary": "Download shipping label", "description": "Returns shipping label data for a Shopee order as JSON. On success the label file is included Base64-encoded (typically a ZIP archive). The credential must be valid for the account indicated by query parameter `an`.\r\n\r\n## Authentication\r\n\r\nThis endpoint requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) in the `VtexIdclientAutCookie` header (for example from Admin VTEX login). [API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) are not used for this operation.\r\n\r\n## Permissions\r\n\r\nThe authenticated store user must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **View order** |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| OMS - Full access | View order |\r\n| Checkout Admin | View order |\r\n| IntegrationProfile - Fulfillment Oms | View order |\r\n| OMS - Full access | Orders Full Access |\r\n| Checkout Admin | Orders Full Access |\r\n| IntegrationProfile - Fulfillment Oms | Orders Full Access |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "security": [ { "VtexIdclientAutCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/AccountNameQuery" }, { "$ref": "#/components/parameters/ShopeeOrderIdQuery" } ], "responses": { "200": { "description": "200 OK\n\nResponse body with Shopee order status details and a Base64 encoded label file plus content disposition hints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLabelDownloadResponse" }, "example": { "message": "Label retrieved successfully", "details": { "statusMessage": "success", "orderStatusInShopee": [ "READY_TO_SHIP" ], "file": { "base64Encoded": "UEsDBBQAAAAIA...", "type": "application/force-download", "disposition": "attachment; filename=\"OpenApi_Shipping_label_Zip.Entrega%20Padr%C3%A3o%2A1.zip\"" } } } } } } } } }, "/api/shopeeintegration/{accountName}/pub/orders/{mktplaceOrderId}/cancelDelivery": { "post": { "tags": [ "VTEX order callbacks" ], "summary": "Cancel marketplace delivery", "description": "Cancels delivery for a marketplace order received through VTEX callback.\r\n\r\n## Authentication\r\n\r\nThis endpoint requires the store admin [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) in the `VtexIdclientAutCookie` header (session from Admin VTEX login). API keys (`X-VTEX-API-AppKey` / `X-VTEX-API-AppToken`) are not used for this operation.\r\n\r\n## Permissions\r\n\r\nThe authenticated store user must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **View order** |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| OMS - Full access | View order |\r\n| Checkout Admin | View order |\r\n| IntegrationProfile - Fulfillment Oms | View order |\r\n| OMS - Full access | Orders Full Access |\r\n| Checkout Admin | Orders Full Access |\r\n| IntegrationProfile - Fulfillment Oms | Orders Full Access |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "security": [ { "VtexIdclientAutCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/AccountNamePath" }, { "$ref": "#/components/parameters/MarketplaceOrderIdPath" } ], "responses": { "200": { "description": "200 OK\n\nDelivery cancellation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancelSuccessResponse" }, "example": { "message": "Delivery cancellation completed successfully." } } } } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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." } }, "parameters": { "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "schema": { "type": "string", "example": "application/json" } }, "AccountNameQuery": { "name": "an", "in": "query", "description": "VTEX account name for the Shopee integration. Must match the account for which the authentication credential is valid.", "required": true, "schema": { "type": "string", "example": "store01" } }, "ShopeeOrderIdQuery": { "name": "shopeeOrderId", "in": "query", "description": "Shopee order identifier.", "required": true, "schema": { "type": "string", "example": "240101ABC123" } }, "AccountNamePath": { "name": "accountName", "in": "path", "description": "VTEX account name.", "required": true, "schema": { "type": "string", "example": "store01" } }, "MarketplaceOrderIdPath": { "name": "mktplaceOrderId", "in": "path", "description": "Marketplace order identifier.", "required": true, "schema": { "type": "string", "example": "MKT-123456" } } }, "schemas": { "cancelSuccessResponse": { "type": "object", "description": "Generic success response payload.", "properties": { "message": { "type": "string", "description": "Result message." } } }, "ShopeeOrderHookRequest": { "type": "object", "description": "Webhook payload sent by Shopee.", "required": [ "code", "shopId", "data" ], "properties": { "code": { "type": "integer", "description": "Shopee webhook event code." }, "shopId": { "type": "integer", "description": "Shopee shop identifier." }, "data": { "type": "object", "description": "Order payload details.", "required": [ "orderSn", "status" ], "properties": { "orderSn": { "type": "string", "description": "Shopee order serial number." }, "status": { "type": "string", "description": "Shopee order status." } } } } }, "ShippingLabelDownloadResponse": { "type": "object", "description": "Shipping label download payload returned by the API.", "required": [ "message", "details" ], "properties": { "message": { "type": "string", "description": "Summary message for the operation." }, "details": { "type": "object", "description": "Label metadata and encoded file returned for the Shopee order.", "properties": { "statusMessage": { "type": "string", "description": "Status message from the integration or Shopee flow." }, "orderStatusInShopee": { "type": "array", "description": "Shopee order status values applicable to the label request.", "items": { "type": "string", "description": "Shopee order status code or label." } }, "file": { "type": "object", "description": "Label file encoded in Base64 and HTTP content hints.", "required": [ "base64Encoded", "type", "disposition" ], "properties": { "base64Encoded": { "type": "string", "description": "File content (for example a ZIP archive) encoded in Base64." }, "type": { "type": "string", "description": "Suggested media type for the file, often application/force-download." }, "disposition": { "type": "string", "description": "Suggested Content-Disposition header value for download." } } } } } } } } }, "tags": [ { "name": "Shopee orders" }, { "name": "VTEX order callbacks" } ] }