{ "openapi": "3.0.0", "info": { "title": "VTEX Shipping Network API", "contact": {}, "description": "[VTEX Shipping Network](https://vtex.com/br-pt/shipping-network/) is a solution that connects carriers and merchants for deliveries at better freight costs and smarter logistics operations.\r\n\r\n>ℹ️ **VTEX Shipping Network** is available exclusively in Brazil.\r\n\r\nThe tracking process has two main parts:\r\n- **Notification:** The [carrier](https://help.vtex.com/en/tutorial/carriers-on-vtex--7u9duMD5UQa2QQwukAWMcE) is notified that a package is being dispatched.\r\n- **Tracking:** The package being delivered by the carrier is tracked from the start of its journey to its final destination.\r\n\r\nTo integrate with the VTEX Shipping Network hub, carriers must develop [VTEX IO](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io) apps and associate them with specific endpoints. Once integrated with the hub, these carrier apps will be connected to other VTEX systems, ensuring seamless execution of the necessary steps for the tracking process.\r\n\r\n>ℹ️ For detailed instructions, see the [VTEX Shipping Network integration guide](https://developers.vtex.com/docs/guides/vtex-shipping-network).\r\n\r\n## Common parameters\r\n\r\n| **Parameter name** | **Description** | **Type** |\r\n| --- | --- | --- |\r\n| `{{accountName}}` | Name of the VTEX account. Used as part of the URL. | Server variable. |\r\n| `{{environment}}` | Environment to use. Used as part of the URL. The default value is `vtexcommercestable`. | Server variable. |\r\n| `X-VTEX-API-AppKey` | Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys). | Authentication header. Must be used together with `X-VTEX-API-AppToken`. Not necessary when using `VtexIdclientAutCookie`. |\r\n| `X-VTEX-API-AppToken` | Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys). | Authentication header. Must be used together with X-VTEX-API-AppKey. Not necessary when using `VtexIdclientAutCookie`. |\r\n| `VtexIdclientAutCookie` | [User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours. | Authentication header. Not necessary when using `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken`. |", "version": "1.0" }, "servers": [ { "url": "https://app.io.vtex.com", "description": "VTEX server URL.", "variables": {} } ], "paths": { "/{app_name}/v{app_version}/{account}/{workspace}/notify": { "post": { "tags": [ "Notification" ], "summary": "Notify carrier with app", "description": "Notifies the carrier about a dispatch order by calling the `vtex.carrier-notifier app`. When the call is made, the following data is sent: \n\n- Dispatched packages information. \n\n- Fiscal information about the carrier notified. \n\n- Carrier's contact email. \n\nThe call's response includes all tracking data and each package's ID generated by the notification made to the carrier. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) 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| Logistics | Logistics access | **Transportation read only** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "NotifyCarrierwithApp", "parameters": [ { "name": "app_name", "in": "path", "description": "Name of the app developed by the carrier's integration.", "required": true, "style": "simple", "schema": { "type": "string", "default": "{{app name}}" } }, { "name": "app_version", "in": "path", "description": "Version of the app developed by the carrier's integration.", "required": true, "style": "simple", "schema": { "type": "string", "default": "{{version}}" } }, { "name": "account", "in": "path", "description": "VTEX account dispatching the package.", "required": true, "style": "simple", "schema": { "type": "string", "default": "VTEX Store example" } }, { "name": "workspace", "in": "path", "description": "Workspace used in VTEX IO. ", "required": true, "style": "simple", "schema": { "type": "string", "default": "master" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifyCarrierwithAppRequest" }, "example": { "account": { "name": "Ltda", "accountName": "{{account}}", "isOperating": true, "defaultUrl": null, "district": null, "country": "Brasil", "complement": null, "companyName": "LTDA", "cnpj": "00000000000000", "city": null, "address": null, "number": null, "postalCode": null, "state": null, "telephone": null, "tradingName": "tradingName" }, "email": "email", "dispatchOrder": { "id": "653560c2-7965-4614-a730-8e45c89bf284", "packageIds": [ "6529cd28-6fd1-4b95-8397-5fad0a79d41c" ], "sender": { "cnpj": "00000000000000", "fantasyName": null, "stateRegistration": null, "id": null, "name": "LTDA", "address": { "postalCode": "03475015", "country": { "code": "BRA", "name": "Brasil" }, "subregion1": { "code": "SP", "name": "São Paulo" }, "subregion2": { "code": "São Paulo", "name": "São Paulo" }, "subregion3": { "code": "Vila Antonieta", "name": "Vila Antonieta" }, "street": "Rua Exemplo", "number": "01", "complement": "", "location": null }, "email": null, "phone":"999999999" }, "carrier": { "cnpj": "00000000000000", "fantasyName": "carrier", "stateRegistration": "096/3624636", "id": "vtexlog_exemplo", "name": "Carrier LTDA.", "address": { "postalCode": "90200001", "country": { "code": "BRA", "name": "Brasil" }, "subregion1": { "code": "RS", "name": "Rio Grande do Sul" }, "subregion2": { "code": "Porto_Alegre", "name": "Porto Alegre" }, "subregion3": { "code": "Anchieta", "name": "Anchieta" }, "street": "Rua Exemplo", "number": "01", "complement": "Pavilhão 6", "location": null }, "email": "email", "phone": "+5511111111111" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/{app_name}/v{app_version}/{account}/{workspace}/tracking": { "post": { "tags": [ "Tracking" ], "summary": "Tracking events with app", "description": "This endpoint is called by the hub to obtain the tracking events of a series of tracking numbers. This call's request updates the events of a list of tracking codes, for packages that are still pending delivery. The expected response is an object contaning the tracking information and the package's notification ID for every `packageID`. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) 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| Logistics | Logistics access | **Transportation read only** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "TrackingEvents", "parameters": [ { "name": "app_name", "in": "path", "description": "Name of the app developed by the carrier's integration.", "required": true, "style": "simple", "schema": { "type": "string", "default": "{{app name}}" } }, { "name": "app_version", "in": "path", "description": "Version of the app developed by the carrier's integration.", "required": true, "style": "simple", "schema": { "type": "string", "default": "{{version}}" } }, { "name": "account", "in": "path", "description": "VTEX account dispatching the package.", "required": true, "style": "simple", "schema": { "type": "string", "default": "VTEX Store example" } }, { "name": "workspace", "in": "path", "description": "Workspace used in VTEX IO. ", "required": true, "style": "simple", "schema": { "type": "string", "default": "master" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingEventsRequest" }, "description": "Array containing tracking information.", "example": [ { "trackingNumber": "BR000000000" } ] }, "example": [ { "trackingNumber": "BR000000000" } ] } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } } }, "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." } }, "schemas": { "Account": { "title": "Account", "required": [ "name", "accountName", "isOperating", "defaultUrl", "district", "country", "complement", "companyName", "cnpj", "city", "address", "number", "postalCode", "state", "telephone", "tradingName" ], "type": "object", "properties": { "name": { "type": "string", "description": "Inserted name.", "example": "Ltda" }, "accountName": { "type": "string", "description": "Name of the VTEX Account dispatching the package.", "example": "mystore" }, "isOperating": { "type": "boolean", "description": "Whether the store is operating or not.", "example": true }, "defaultUrl": { "type": "string", "nullable": true, "description": "Retrieved from VTEX's License Manager.", "example": "https://url.example.com" }, "district": { "type": "string", "nullable": true, "description": "District where the VTEX store dispatching the package is located.", "example": "District name" }, "country": { "type": "string", "description": "Country where the VTEX store, dispatching the package, is located.", "example": "Brasil" }, "complement": { "type": "string", "nullable": true, "description": "Complement for the VTEX store's address.", "example": "Second floor" }, "companyName": { "type": "string", "description": "Name of the VTEX store responsible for the package.", "example": "VTEX Store 1" }, "cnpj": { "type": "string", "description": "CNPJ code of the VTEX store responsible for the package.", "example": "00000000000000" }, "city": { "type": "string", "nullable": true, "description": "City where the VTEX store responsible for the package is located.", "example": "Rio de Janeiro" }, "address": { "type": "string", "nullable": true, "description": "Address where the VTEX store responsible for the package is located.", "example": "VTEX Street" }, "number": { "type": "string", "nullable": true, "description": "Number of the address related to the `address` field.", "example": "26" }, "postalCode": { "type": "string", "nullable": true, "description": "ZIP code of the VTEX store responsible for the package.", "example": "12345-678" }, "state": { "type": "string", "nullable": true, "description": "State of the address belonging to the VTEX store responsible for the package.", "example": "RJ" }, "telephone": { "type": "string", "nullable": true, "description": "Telephone number of the VTEX store responsible for the package.", "example": "99999999" }, "tradingName": { "type": "string", "description": "Trading name of the VTEX store responsible for the package.", "example": "Trading name" } }, "description": "Account information.", "example": { "name": "Ltda", "accountName": "{{account}}", "isOperating": true, "defaultUrl": null, "district": null, "country": "Brasil", "complement": null, "companyName": "LTDA", "cnpj": "00000000000000", "city": null, "address": null, "number": null, "postalCode": null, "state": null, "telephone": null, "tradingName": "tradingName" } }, "Address": { "title": "Address", "description": "Address of the VTEX account responsible for sending the package.", "required": [ "postalCode", "country", "subregion1", "subregion2", "subregion3", "street", "number", "complement", "location" ], "type": "object", "properties": { "postalCode": { "type": "string", "nullable": true, "description": "ZIP code of the package's recipient.", "example": "12345-678" }, "country": { "$ref": "#/components/schemas/Country" }, "subregion1": { "$ref": "#/components/schemas/Subregion1" }, "subregion2": { "$ref": "#/components/schemas/Subregion2" }, "subregion3": { "$ref": "#/components/schemas/Subregion3" }, "street": { "type": "string", "description": "Recipient's address.", "example": "Street example" }, "number": { "type": "string", "description": "Number of the recipient's address.", "example": "1" }, "complement": { "type": "string", "nullable": true, "description": "Complement for the recipient's address.", "example": "A" }, "location": { "$ref": "#/components/schemas/Location" } }, "example": { "postalCode": "00000-000", "country": { "code": "BRA", "name": "BRA" }, "subregion1": { "code": "SP", "name": "SP" }, "subregion2": { "code": "São Paulo", "name": "São Paulo" }, "subregion3": { "code": "Burgo Paulista", "name": "Burgo Paulista" }, "street": "Rua Exempo", "number": "01", "complement": null, "location": { "lat": -46.485820770263672, "lng": -23.521709442138672 } } }, "Country": { "title": "Country", "description": "Recipient's country.", "required": [ "code", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "Country's three-digit identifying code, from the recipient's address.", "example": "BRA" }, "name": { "type": "string", "description": "Country's name, from the recipient's address.", "example": "Brasil" } }, "example": { "code": "BRA", "name": "BRA" } }, "Subregion1": { "title": "State", "description": "Recipient's address state's information.", "required": [ "code", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "State's code, from the recipient's address.", "example": "SP" }, "name": { "type": "string", "description": "State's name, from the recipient's address.", "example": "Sao Paulo" } }, "example": { "code": "SP", "name": "SP" } }, "Subregion2": { "title": "City", "description": "Recipient's address city's information.", "required": [ "code", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "City's code, from the recipient's address.", "example": "SP" }, "name": { "type": "string", "description": "City's name, from the recipient's address.", "example": "Sao Paulo" } }, "example": { "code": "SP", "name": "São Paulo" } }, "Subregion3": { "title": "Neighborhood", "description": "Recipient's address neighborhood's information.", "required": [ "code", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "Neighborhood's code, from the recipient's address.", "example": "Neighborhood example" }, "name": { "type": "string", "description": "Neighborhood's name, from the recipient's address.", "example": "Neighborhood example" } }, "example": { "code": "Vila Antonieta", "name": "Vila Antonieta" } }, "Location": { "title": "Location", "description": "Recipient's address geocoordinates.", "required": [ "lat", "lng" ], "type": "object", "nullable": true, "properties": { "lat": { "type": "number", "description": "Latitude number of the address' geolocation coordinates.", "example": -46.485820770263672 }, "lng": { "type": "number", "description": "Longitude number of the address' geolocation coordinates.", "example": -23.521709442138672 } }, "example": { "lat": -46.485820770263672, "lng": -23.521709442138672 } }, "NotifyCarrierwithAppRequest": { "title": "NotifyCarrierwithAppRequest", "description": "Object containing email, account, and dispatched order information.", "required": [ "email", "dispatchOrder", "account" ], "type": "object", "properties": { "account":{ "$ref": "#/components/schemas/Account" }, "email": { "type": "string", "description": "Fill in this field if you wish to send the generated file for an email besides the ones already involved in the operation, like the carrier and VTEX account's email.", "example": "email" }, "dispatchOrder": { "$ref": "#/components/schemas/DispatchOrder" } } }, "DispatchOrder": { "title": "DispatchOrder", "description": "Information about the dispatched order.", "required": [ "id", "packageIds", "sender", "carrier" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the dispatched order.", "example":"653560c2-7965-4614-a730-8e45c89bf284" }, "packageIds": { "type": "array", "description": "Array with package IDs.", "items": { "type": "string", "description": "Identification codes of the packages.", "example": "6529cd28-6fd1-4b95-8397-5fad0a79d41c" } }, "sender": { "$ref": "#/components/schemas/Sender" }, "carrier": { "$ref": "#/components/schemas/Carrier" } } }, "Sender": { "title": "Sender", "description": "User's logged account in the VTEX store.", "required": [ "cnpj", "fantasyName", "stateRegistration", "id", "name", "address", "email", "phone" ], "type": "object", "properties": { "cnpj": { "type": "string", "description": "CNPJ code of the VTEX account responsible for sending the package.", "example": "81.316.120/0001-02" }, "fantasyName": { "type": "string", "description": "Fantasy name of the VTEX account responsible for sending the package.", "example":"Carrier 123", "nullable": true }, "stateRegistration": { "type": "string", "description": "State Registration code of the VTEX account responsible for sending the package.", "example": "9843759348", "nullable": true }, "id": { "type": "string", "description": "VTEX account's ID.", "example": "accountId", "nullable": true }, "name": { "type": "string", "description": "Name of the VTEX account responsible for sending the package.", "example": "Store LTDA" }, "address": { "$ref": "#/components/schemas/Address" }, "email": { "type": "string", "description": "Email of the VTEX account responsible for sending the package.", "example": "email@email.com", "nullable": true }, "phone": { "type": "string", "description": "Sender's contact number.", "example": "+5511111111111", "nullable": true } }, "example": { "cnpj": "00000000000000", "fantasyName": null, "stateRegistration": null, "id": null, "name": "LTDA", "address": { "postalCode": "03475015", "country": { "code": "Brasil", "name": "Brasil" }, "subregion1": { "code": "SP", "name": "SP" }, "subregion2": { "code": "São Paulo", "name": "São Paulo" }, "subregion3": { "code": "Vila Antonieta", "name": "Vila Antonieta" }, "street": "Rua Exemplo", "number": "01", "complement": "", "location": null }, "email": null, "phone": "+5511111111111" } }, "Carrier": { "title": "Carrier", "description": "Carrier responsible for delivering the dispatched order.", "required": [ "cnpj", "fantasyName", "stateRegistration", "id", "name", "address", "email", "phone" ], "type": "object", "properties": { "cnpj": { "type": "string", "description": "Carrier's CNPJ.", "example": "00000000000000" }, "fantasyName": { "type": "string", "description": "Carrier's fantasy name.", "example": "Carrier A" }, "stateRegistration": { "type": "string", "description": "Carrier's state registration number.", "example": "843904894875" }, "id": { "type": "string", "description": "Carrier's ID.", "example": "vtexShippinNetwork_example" }, "name": { "type": "string", "description": "Carrier's company name.", "example": "Carrier LTDA" }, "address": { "$ref": "#/components/schemas/Address" }, "email": { "type": "string", "description": "Carrier's email address.", "example": "email@example.com" }, "phone": { "type": "string", "description": "Carrier's contact number.", "example": "+5511111111111", "nullable": true } }, "example": { "cnpj": "00000000000000", "fantasyName": "carrier", "stateRegistration": "096/3624636", "id": "vtexlog_exemplo", "name": "Carrier LTDA.", "address": { "postalCode": "90200001", "country": { "code": "BRA", "name": "Brasil" }, "subregion1": { "code": "RS", "name": "Rio Grande do Sul" }, "subregion2": { "code": "Porto_Alegre", "name": "Porto Alegre" }, "subregion3": { "code": "Anchieta", "name": "Anchieta" }, "street": "Rua Exemplo", "number": "01", "complement": "Pavilhão 6", "location": null }, "email": "email", "phone": "+5511111111111" } }, "TrackingEventsRequest": { "title": "TrackingEventsRequest", "description": "Shipping's tracking information.", "required": [ "trackingNumber" ], "type": "object", "properties": { "trackingNumber": { "type": "string", "description":"Shipping's tracking identification code.", "example": "BR000000000" } }, "example": { "trackingNumber": "BR000000000" } } } }, "tags": [ { "name": "Notification" }, { "name": "Tracking" } ] }