diff --git a/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json b/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json index d6deb4420..e3855a4ad 100644 --- a/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -1,10 +1,10 @@ { "_": { - "postman_id": "ea548ab7-0a34-4b85-aca6-fb65075655da" + "postman_id": "02752372-e668-4f32-9b9a-56bb96f5f9aa" }, "item": [ { - "id": "be99d402-44bd-40c0-9e6f-7c816a15dd42", + "id": "5e388ec1-2a8f-4f7a-b9e5-2852edc05cca", "name": "External Seller", "description": { "content": "", @@ -12,12 +12,12 @@ }, "item": [ { - "id": "1e6669be-8e49-4cc0-a4c6-1be9c333e4ec", + "id": "5d6bbd73-f16e-429e-93b8-2f580ee7ae28", "name": "Send invoice", "request": { "name": "Send invoice", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.", + "content": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.3\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "type": "text/plain" }, "url": { @@ -35,22 +35,22 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "(Required) Identifies the order in the marketplace.", "type": "text/plain" }, "type": "any", - "value": "{{marketplaceServicesEndpoint}}", - "key": "marketplaceServicesEndpoint" + "value": "1138342255777-01", + "key": "marketplaceOrderId" }, { "disabled": false, "description": { - "content": "(Required) Identifies the order in the marketplace.", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", - "value": "1138342255777-01", - "key": "marketplaceOrderId" + "value": "{{marketplaceServicesEndpoint}}", + "key": "marketplaceServicesEndpoint" } ] }, @@ -80,7 +80,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "ac7ed4d4-39df-455a-ae86-790e77ba6320", + "id": "ebef224c-46ce-4b48-91ba-d15c41e17962", "name": "OK", "originalRequest": { "url": { @@ -98,22 +98,22 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "(Required) Identifies the order in the marketplace.", "type": "text/plain" }, "type": "any", - "value": "{{marketplaceServicesEndpoint}}", - "key": "marketplaceServicesEndpoint" + "value": "1138342255777-01", + "key": "marketplaceOrderId" }, { "disabled": false, "description": { - "content": "(Required) Identifies the order in the marketplace.", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", - "value": "1138342255777-01", - "key": "marketplaceOrderId" + "value": "{{marketplaceServicesEndpoint}}", + "key": "marketplaceServicesEndpoint" } ] }, @@ -138,7 +138,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -176,12 +176,13 @@ { "listen": "test", "script": { - "id": "d59f8909-6625-43d9-98e9-f9c9e2d676e2", + "id": "061d23b4-1b84-44b1-a732-cf1c2c221bdd", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -191,12 +192,12 @@ } }, { - "id": "f262b16c-7f72-47d7-ba99-413cc51cec64", + "id": "5766c16c-bf90-4d6a-b398-7156c3767b33", "name": "Send tracking information", "request": { "name": "Send tracking information", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.", + "content": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| OMS | OMS access | **Notify invoice** |\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| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys 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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "type": "text/plain" }, "url": { @@ -215,7 +216,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -270,7 +271,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "9050e56d-ecbd-4967-9ebb-bd07f39ae3c7", + "id": "c8d10502-5fb3-4a13-a0e5-fa733088b042", "name": "OK", "originalRequest": { "url": { @@ -289,7 +290,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -339,7 +340,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -377,12 +378,13 @@ { "listen": "test", "script": { - "id": "d7cfb4d1-cf45-4d64-a776-94be874c1f11", + "id": "11c5b244-9ff6-4e61-ab36-c467070a3f8a", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -392,12 +394,12 @@ } }, { - "id": "8bd276ca-a62d-43e5-89d7-a4589104138f", + "id": "d31827ff-f38d-45f7-9bd0-bd761fa1e226", "name": "Update tracking status", "request": { "name": "Update tracking status", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.", + "content": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| OMS | OMS access | **Notify invoice** |\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| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys 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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "type": "text/plain" }, "url": { @@ -417,7 +419,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -459,7 +461,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{\n \"isDelivered\": true,\n \"events\": [\n {\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"description\": \"Order delivered.\",\n \"date\": \"2021-03-16\"\n },\n {\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"description\": \"Order delivered.\",\n \"date\": \"2021-03-16\"\n }\n ]\n}", + "raw": "{\n \"isDelivered\": true,\n \"events\": [\n {\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"description\": \"Order delivered.\",\n \"date\": \"2021-03-16\"\n }\n ]\n}", "options": { "raw": { "language": "json" @@ -472,7 +474,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "1c9d50fb-a23d-41ce-8f5e-057e5027ea41", + "id": "6a48d3a3-7149-4a2f-9c9d-cd7dbae6e42f", "name": "OK", "originalRequest": { "url": { @@ -492,7 +494,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -542,7 +544,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -580,12 +582,13 @@ { "listen": "test", "script": { - "id": "2860bcaa-37fe-4940-8f44-52a160a32c1c", + "id": "657c2698-2b1d-4308-bf0e-5132ee61beb9", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -595,12 +598,12 @@ } }, { - "id": "577e1a3c-6995-4c91-ae1d-247fc0ac7960", + "id": "4f95492d-5366-4f41-af47-e37f6cda051c", "name": "Cancel order in marketplace", "request": { "name": "Cancel order in marketplace", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to cancel an order.", + "content": "This request is sent by the external seller to the VTEX marketplace to cancel an order.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| Checkout | CheckoutResources | **Order Cancellation** |\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| Cancel Orders | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys 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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "type": "text/plain" }, "url": { @@ -618,7 +621,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -650,7 +653,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{\n \"reason\": \"Product is unavailable\"\n}", + "raw": "{\n \"reason\": \"Product is unavailable.\"\n}", "options": { "raw": { "language": "json" @@ -663,7 +666,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "52019e41-0396-437b-9d66-72d7ef913a8c", + "id": "7a7784a8-832d-4c08-aa41-1c7214fc1303", "name": "OK", "originalRequest": { "url": { @@ -681,7 +684,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -721,7 +724,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -735,7 +738,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{\n \"reason\": \"Product is unavailable\"\n}", + "raw": "{\n \"reason\": \"Product is unavailable.\"\n}", "options": { "raw": { "language": "json" @@ -759,12 +762,13 @@ { "listen": "test", "script": { - "id": "3532bd96-4ce9-4a16-ae07-28e84b49e989", + "id": "d2c7f745-189a-4e17-8873-48cc2b176e20", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -815,7 +819,7 @@ } ], "info": { - "_postman_id": "ea548ab7-0a34-4b85-aca6-fb65075655da", + "_postman_id": "02752372-e668-4f32-9b9a-56bb96f5f9aa", "name": "Marketplace Protocol", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index f9b940e25..fc2247cf4 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -2,8 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Marketplace Protocol", - "description": "\r\nThe _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", - "contact": {}, + "description": "The _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", "version": "1.0" }, "servers": [ @@ -25,132 +24,27 @@ "External Seller" ], "summary": "Send invoice", - "description": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.", + "description": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.3\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "send-invoice", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/Content-Type" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "required": [ - "type", - "invoiceNumber", - "items" - ], - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.", - "example": "Output" - }, - "invoiceNumber": { - "type": "string", - "description": "Invoice number", - "example": "NFe-00002" - }, - "courier": { - "type": "string", - "description": "Courier, if available on invoice.", - "example": "courier-example" - }, - "trackingNumber": { - "type": "string", - "description": "Tracking number.", - "example": "12345678abc" - }, - "trackingUrl": { - "type": "string", - "description": "Tracking URL.", - "example": "https://courier-example.com/tracking" - }, - "items": { - "type": "array", - "description": "Array containing the order items.", - "items": { - "type": "object", - "description": "", - "required": [ - "id", - "quantity", - "price" - ], - "properties": { - "id": { - "type": "string", - "description": "SKU ID.", - "example": "6" - }, - "quantity": { - "type": "integer", - "description": "Quantity of items of the SKU in the cart.", - "example": 1 - }, - "price": { - "type": "integer", - "description": "Price of the item.", - "example": 5500 - } - } - } - }, - "issuanceDate": { - "type": "string", - "description": "Issuance date.", - "example": "2021-05-21T10:00:00" - }, - "invoiceValue": { - "type": "integer", - "description": "Invoice value.", - "example": 6000 - } - } + "$ref": "#/components/schemas/requestSendInvoice" } } }, @@ -159,17 +53,15 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } @@ -184,93 +76,36 @@ "External Seller" ], "summary": "Send tracking information", - "description": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.", + "description": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| OMS | OMS access | **Notify invoice** |\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| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys 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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "send-tracking-information", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "invoiceNumber", - "in": "path", - "description": "Invoice number.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "NFe-00002" - } + "$ref": "#/components/parameters/invoiceNumber" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "courier": { - "type": "string", - "description": "Courier.", - "example": "courier-example" - }, - "trackingNumber": { - "type": "string", - "description": "Tracking number.", - "example": "12345678abc" - }, - "trackingUrl": { - "type": "string", - "description": "Tracking URL.", - "example": "https://courier-example.com/tracking" - }, - "dispatchedDate": { - "type": "string", - "description": "Date of order dispatch.", - "example": "2021-06-09" - } - } + "$ref": "#/components/schemas/requestSendTracking" + }, + "example": { + "courier": "courier-example", + "trackingNumber": "12345678abc", + "trackingUrl": "https://courier-example.com/tracking", + "dispatchedDate": "2021-06-09" } } }, @@ -279,23 +114,21 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } } }, - "deprecated": false + "deprecated": false } }, "/pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}/tracking": { @@ -304,110 +137,30 @@ "External Seller" ], "summary": "Update tracking status", - "description": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.", + "description": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| OMS | OMS access | **Notify invoice** |\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| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys 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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "update-tracking-status", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "invoiceNumber", - "in": "path", - "description": "Invoice number.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "NFe-00002" - } + "$ref": "#/components/parameters/invoiceNumber" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "type": "object", - "required": [ - "isDelivered" - ], - "properties": { - "isDelivered": { - "type": "boolean", - "description": "Indicates if order has been delivered. `false` if it is in transit.", - "example": true - }, - "events": { - "type": "array", - "description": "Array containing information on each tracking event received.", - "items": { - "type": "object", - "properties": { - "city": { - "type": "string", - "description": "City where the event ocurred.", - "example": "Rio de Janeiro" - }, - "state": { - "type": "string", - "description": "State where the event ocurred.", - "example": "Rio de Janeiro" - }, - "description": { - "type": "string", - "description": "Description of the event.", - "example": "Order delivered." - }, - "date": { - "type": "string", - "description": "Date when event ocurred.", - "example": "2021-03-16" - } - } - } - } - } + "$ref": "#/components/schemas/requestUpdateTrackingStatus" } } }, @@ -416,17 +169,15 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } @@ -441,70 +192,27 @@ "External Seller" ], "summary": "Cancel order in marketplace", - "description": "This request is sent by the external seller to the VTEX marketplace to cancel an order.", + "description": "This request is sent by the external seller to the VTEX marketplace to cancel an order.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| Checkout | CheckoutResources | **Order Cancellation** |\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| Cancel Orders | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys 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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "cancel-order-in-marketplace", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "type": "object", - "required": [ - "reason" - ], - "properties": { - "reason": { - "type": "string", - "description": "Insert here the reason for the order's cancellation.", - "example": "Product is unavailable" - } - } + "$ref": "#/components/schemas/requestCancelOrderMarketplace" } } }, @@ -513,17 +221,15 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } @@ -537,6 +243,9 @@ { "appKey": [], "appToken": [] + }, + { + "VtexIdclientAutCookie": [] } ], "components": { @@ -544,12 +253,259 @@ "appKey": { "type": "apiKey", "in": "header", - "name": "X-VTEX-API-AppKey" + "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" + "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." + } + }, + "parameters": { + "Content-Type": { + "name": "Content-Type", + "in": "header", + "description": "Type of the content being sent.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "default": "application/json" + } + }, + "Accept": { + "name": "Accept", + "in": "header", + "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "default": "application/json" + } + }, + "marketplaceServicesEndpoint": { + "name": "marketplaceServicesEndpoint", + "in": "path", + "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "marketplaceservicesendpoint.myvtex.com" + } + }, + "marketplaceOrderId": { + "name": "marketplaceOrderId", + "in": "path", + "description": "Identifies the order in the marketplace.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "1138342255777-01" + } + }, + "invoiceNumber": { + "name": "invoiceNumber", + "in": "path", + "description": "Invoice number.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "NFe-00002" + } + } + }, + "schemas": { + "requestSendInvoice": { + "required": [ + "type", + "invoiceNumber", + "items" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.", + "example":"Output" + }, + "invoiceNumber": { + "type": "string", + "description": "Invoice number.", + "example":"NFe-00002" + }, + "courier": { + "type": "string", + "description": "Courier, if available on invoice.", + "example":"courier-example" + }, + "trackingNumber": { + "type": "string", + "description": "Tracking number.", + "example":"12345678abc" + }, + "trackingUrl": { + "type": "string", + "description": "Tracking URL.", + "example": "https://courier-example.com/tracking" + }, + "items": { + "type": "array", + "description": "Array containing the order items.", + "items": { + "type": "object", + "description": "Specification data for each order item.", + "required": [ + "id", + "quantity", + "price" + ], + "properties": { + "id": { + "type": "string", + "description": "SKU ID.", + "example": "6" + }, + "quantity": { + "type": "integer", + "description": "Quantity of items of the SKU in the cart.", + "example": 1 + }, + "price": { + "type": "integer", + "description": "Price of the item.", + "example": 5500 + } + } + } + }, + "issuanceDate": { + "type": "string", + "description": "Issuance date.", + "example": "2021-05-21T10:00:00" + }, + "invoiceValue": { + "type": "integer", + "description": "Invoice value.", + "example": 6000 + } + } + }, + "responseFulfill": { + "properties": { + "date": { + "type": "string", + "description": "Request processing date and time.", + "example":"2021-06-09T15:22:56.7612218-02:00" + }, + "orderId": { + "type": "string", + "description": "Order ID referring to the Invoice number sent.", + "example": "1138342255777-01" + }, + "receipt": { + "type": "string", + "description": "Requisition receipt code.", + "example": "527b1ae251264ef1b7a9b597cd8f16b9" + } + } + }, + "requestSendTracking": { + "required": [ + "courier", + "trackingNumber", + "trackingUrl", + "dispatchedDate" + ], + "properties": { + "courier": { + "type": "string", + "description": "Courier.", + "example":"courier-example" + }, + "trackingNumber": { + "type": "string", + "description": "Tracking number.", + "example": "12345678abc" + }, + "trackingUrl": { + "type": "string", + "description": "Tracking URL.", + "example": "https://courier-example.com/tracking" + }, + "dispatchedDate": { + "type": "string", + "description": "Date of order dispatch.", + "example":"2021-06-09" + } + } + }, + "requestUpdateTrackingStatus": { + "type": "object", + "required": [ + "isDelivered" + ], + "properties": { + "isDelivered": { + "type": "boolean", + "description": "Indicates if order has been delivered. `false` if it is in transit.", + "example": true + }, + "events": { + "type": "array", + "description": "Array containing information on each tracking event received.", + "items": { + "type": "object", + "description": "Description of tracking event fields.", + "properties": { + "city": { + "type": "string", + "description": "City where the event ocurred.", + "example": "Rio de Janeiro" + }, + "state": { + "type": "string", + "description": "State where the event ocurred.", + "example": "Rio de Janeiro" + }, + "description": { + "type": "string", + "description": "Description of the event.", + "example": "Order delivered." + }, + "date": { + "type": "string", + "description": "Date when event ocurred.", + "example": "2021-03-16" + } + } + } + } + } + }, + "requestCancelOrderMarketplace": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "reason": { + "type": "string", + "description": "Insert here the reason for the order's cancellation.", + "example": "Product is unavailable." + } + } } } }, @@ -558,4 +514,4 @@ "name": "External Seller" } ] -} +} \ No newline at end of file