diff --git a/PostmanCollections/VTEX - Marketplace Protocol - External Seller Fulfillment.json b/PostmanCollections/VTEX - Marketplace Protocol - External Seller Fulfillment.json index c30237353..dbaf666a8 100644 --- a/PostmanCollections/VTEX - Marketplace Protocol - External Seller Fulfillment.json +++ b/PostmanCollections/VTEX - Marketplace Protocol - External Seller Fulfillment.json @@ -1,10 +1,10 @@ { "_": { - "postman_id": "8f779dd6-97c3-4c33-936d-ecddf77aab25" + "postman_id": "f1a8a53e-8673-4f2f-9669-599fc4232eee" }, "item": [ { - "id": "102d4f30-3db7-44da-9c19-ccc5f9c4aa04", + "id": "d1063a0c-ea1a-4e00-a05b-b965c1e504ab", "name": "External Seller", "description": { "content": "", @@ -12,12 +12,12 @@ }, "item": [ { - "id": "b86c94f9-c9ba-4ebf-92c0-f8f3af3a724c", + "id": "ed339d6b-4a0f-49cd-a06d-5d4792c82566", "name": "Fulfillment simulation - External Seller", "request": { "name": "Fulfillment simulation - External Seller", "description": { - "content": "This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) notification request returns a response with status `200 OK`, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.\n\nThe seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the paramenters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request, since they are not mandatory data for this context. \n- **Making a shopping cart simulation during checkout**: address information must be sent, since this data is needed to calculate freight values. If the address information (including `postalCode` and `country`) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout. \n \n## Request body example - Indexing simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"isCheckedIn\": false,\n }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"postalCode\": \"22270-030\",\n \"country\": \"BRA\",\n }\n```", + "content": "This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) notification request returns a response with status `200 OK`, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.\n\nThe seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the paramenters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request, since they are not mandatory data for this context. \n- **Making a shopping cart simulation during checkout**: address information must be sent, since this data is needed to calculate freight values. If the address information (including `postalCode` and `country`) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout. \n \n## Request body example - Indexing simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"isCheckedIn\": false,\n }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"postalCode\": \"22270-030\",\n \"country\": \"BRA\",\n }\n```\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "type": "text/plain" }, "url": { @@ -34,7 +34,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -69,7 +69,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "5e6c56da-f2bd-489d-96ab-80867fb35474", + "id": "12f6fc4b-391c-4d31-bb3a-5eb5e17751e4", "name": "OK", "originalRequest": { "url": { @@ -86,7 +86,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -146,7 +146,7 @@ "value": "application/json" } ], - "body": "{\n \"country\": \"BRA\",\n \"items\": [\n {\n \"id\": \"2000037\",\n \"listPrice\": 67203,\n \"measurementUnit\": \"un\",\n \"merchantName\": \"mySeller1\",\n \"offerings\": [\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n },\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n }\n ],\n \"price\": 67203,\n \"priceTags\": [\n \"promotion 1\",\n \"promotion 1\"\n ],\n \"priceValidUntil\": \"2014-03-01T22:58:28.143\",\n \"quantity\": 1,\n \"requestIndex\": 0,\n \"seller\": \"1\",\n \"unitMultiplier\": 1\n },\n {\n \"id\": \"2000037\",\n \"listPrice\": 67203,\n \"measurementUnit\": \"un\",\n \"merchantName\": \"mySeller1\",\n \"offerings\": [\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n },\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n }\n ],\n \"price\": 67203,\n \"priceTags\": [\n \"promotion 1\",\n \"promotion 1\"\n ],\n \"priceValidUntil\": \"2014-03-01T22:58:28.143\",\n \"quantity\": 1,\n \"requestIndex\": 0,\n \"seller\": \"1\",\n \"unitMultiplier\": 1\n }\n ],\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"quantity\": 1,\n \"shipsTo\": [\n \"BRA\",\n \"BOL\"\n ],\n \"slas\": [\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n },\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n }\n ],\n \"stockBalance\": 199,\n \"deliveryChannels\": [\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n },\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n }\n ]\n },\n {\n \"itemIndex\": 0,\n \"quantity\": 1,\n \"shipsTo\": [\n \"BRA\",\n \"BOL\"\n ],\n \"slas\": [\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n },\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n }\n ],\n \"stockBalance\": 199,\n \"deliveryChannels\": [\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n },\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n }\n ]\n }\n ],\n \"postalCode\": \"80250000\",\n \"allowMultipleDeliveries\": true\n}", + "body": "{\n \"country\": \"BRA\",\n \"items\": [\n {\n \"id\": \"2000037\",\n \"listPrice\": 67203,\n \"measurementUnit\": \"un\",\n \"merchantName\": \"mySeller1\",\n \"offerings\": [\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n },\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n }\n ],\n \"price\": 67203,\n \"priceTags\": [\n \"promotion 1\",\n \"promotion 1\"\n ],\n \"priceValidUntil\": \"2014-03-01T22:58:28.143\",\n \"quantity\": 1,\n \"requestIndex\": 0,\n \"seller\": \"1\",\n \"unitMultiplier\": 1\n },\n {\n \"id\": \"2000037\",\n \"listPrice\": 67203,\n \"measurementUnit\": \"un\",\n \"merchantName\": \"mySeller1\",\n \"offerings\": [\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n },\n {\n \"type\": \"Warranty\",\n \"id\": \"5\",\n \"name\": \"1 year warranty\",\n \"price\": 10000\n }\n ],\n \"price\": 67203,\n \"priceTags\": [\n \"promotion 1\",\n \"promotion 1\"\n ],\n \"priceValidUntil\": \"2014-03-01T22:58:28.143\",\n \"quantity\": 1,\n \"requestIndex\": 0,\n \"seller\": \"1\",\n \"unitMultiplier\": 1\n }\n ],\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"quantity\": 1,\n \"shipsTo\": [\n \"BRA\",\n \"BOL\"\n ],\n \"slas\": [\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n },\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n }\n ],\n \"stockBalance\": 199,\n \"deliveryChannels\": [\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n },\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n }\n ]\n },\n {\n \"itemIndex\": 0,\n \"quantity\": 1,\n \"shipsTo\": [\n \"BRA\",\n \"BOL\"\n ],\n \"slas\": [\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n },\n {\n \"id\": \"Curbside pickup\",\n \"deliveryChannel\": \"pickup-in-point\",\n \"name\": \"Curbside pickup\",\n \"price\": 846,\n \"shippingEstimate\": \"19bd\",\n \"availableDeliveryWindows\": [\n {\n \"startDateUtc\": \"2013-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2013-02-04T13:00:00+00:00\",\n \"price\": 0\n },\n {\n \"startDateUtc\": \"2014-02-04T08:00:00+00:00\",\n \"endDateUtc\": \"2014-02-04T13:00:00+00:00\",\n \"price\": 100\n }\n ],\n \"pickupStoreInfo\": {\n \"isPickupStore\": true,\n \"friendlyName\": \"Santa Felicidade\",\n \"address\": {\n \"addressType\": \"pickup\",\n \"receiverName\": \"Juliana\",\n \"addressId\": \"548304ed-dd40-4416-b12b-4b32bfa7b1e0\",\n \"postalCode\": \"82320-040\",\n \"city\": \"Curitiba\",\n \"state\": \"PR\",\n \"country\": \"BRA\",\n \"street\": \"Rua Domingos Strapasson\",\n \"number\": \"100\",\n \"neighborhood\": \"Santa Felicidade\",\n \"complement\": \"Loja 10\",\n \"reference\": \"Right next to the Unicorn statue.\",\n \"geoCoordinates\": [\n 49.334934,\n 25.401705\n ]\n },\n \"additionalInfo\": \"\"\n }\n }\n ],\n \"stockBalance\": 199,\n \"deliveryChannels\": [\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n },\n {\n \"id\": \"pickup-in-point\",\n \"stockBalance\": 20\n }\n ]\n }\n ],\n \"postalCode\": \"80250000\",\n \"allowMultipleDeliveries\": false\n}", "cookie": [] } ], @@ -154,7 +154,7 @@ { "listen": "test", "script": { - "id": "61e45ea0-f534-4681-8c44-7ea3e17d0a16", + "id": "761b7923-6a8c-48b5-9078-da5f3ce32442", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orderForms/simulation - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -170,12 +170,12 @@ } }, { - "id": "b52b599f-97f7-41ee-a458-eff1fb4c4b41", + "id": "42719de3-b8a1-4616-8c1c-08ea32e03014", "name": "Order placement", "request": { "name": "Order placement", "description": { - "content": "This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their own store.", + "content": "This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their own store.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "type": "text/plain" }, "url": { @@ -191,7 +191,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -213,20 +213,20 @@ { "disabled": false, "description": { - "content": "(Required) VTEX API app key.", + "content": "", "type": "text/plain" }, - "key": "x-vtex-api-appkey", - "value": "appKey" + "key": "X-VTEX-API-AppKey", + "value": "" }, { "disabled": false, "description": { - "content": "(Required) VTEX API app token.", + "content": "", "type": "text/plain" }, - "key": "x-vtex-api-apptoken", - "value": "appToken" + "key": "X-VTEX-API-AppToken", + "value": "" }, { "disabled": false, @@ -294,7 +294,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{}", + "raw": "{\n \"marketplaceOrderId\": \"1138342255777-01\",\n \"marketplaceServicesEndpoint\": \"https://marketplaceservicesendpoint.myvtex.com/\",\n \"marketplacePaymentValue\": 2499,\n \"items\": [\n {\n \"id\": \"123456789abc\",\n \"quantity\": 1,\n \"seller\": \"seller-example\",\n \"commission\": 0,\n \"freightCommission\": 0,\n \"price\": 2499,\n \"bundleItems\": [\n {\n \"id\": \"bundle-item-1\",\n \"quantity\": 2\n },\n {\n \"id\": \"bundle-item-2\",\n \"quantity\": 1\n }\n ],\n \"itemsAttachment\": [\n {\n \"id\": \"attachment-1\",\n \"name\": \"Product Manual\",\n \"url\": \"https://example.com/manual.pdf\"\n }\n ],\n \"attachments\": [\n {\n \"id\": \"attachment-2\",\n \"name\": \"Product Image\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ],\n \"priceTags\": [\n {\n \"identifier\": \"1234abc-5678b-1234c\",\n \"isPercentual\": false,\n \"name\": \"discount@name-1234abc-5678b-1234c\",\n \"rawValue\": 12,\n \"value\": 1200\n }\n ],\n \"measurementUnit\": \"g\",\n \"unitMultiplier\": 1,\n \"isGift\": false\n }\n ],\n \"paymentData\": null,\n \"clientProfileData\": {\n \"email\": \"customer@examplemail.com\",\n \"firstName\": \"first-name\",\n \"lastName\": \"last-name\",\n \"documentType\": \"cpf\",\n \"document\": \"123456789\",\n \"phone\": \"+55110988887777\",\n \"corporateName\": null,\n \"tradeName\": null,\n \"corporateDocument\": null,\n \"stateInscription\": null,\n \"corporatePhone\": null,\n \"isCorporate\": false\n },\n \"shippingData\": {\n \"address\": {\n \"addressType\": \"residential\",\n \"receiverName\": \"receiver-name\",\n \"addressId\": \"Home\",\n \"postalCode\": \"12345-000\",\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"country\": \"BRA\",\n \"street\": \"Praia de Botafogo\",\n \"number\": \"300\",\n \"neighborhood\": \"Botafogo\",\n \"complement\": \"3rd floor\",\n \"reference\": \"Grey building\",\n \"geoCoordinates\": [\n \"00.00000\",\n \"00.00000\"\n ]\n },\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"selectedSla\": \"Express\",\n \"lockTTL\": \"8d\",\n \"shippingEstimate\": \"7d\",\n \"price\": 1099,\n \"deliveryWindow\": {\n \"startDateUtc\": \"2016-04-20T08:00:00+00:00\",\n \"endDateUtc\": \"2016-04-20T12:00:00+00:00\",\n \"listPrice\": 10\n }\n }\n ],\n \"updateStatus\": \"updated\"\n },\n \"marketingData\": {\n \"utmSource\": \"Facebook\",\n \"utmMedium\": \"CPC\",\n \"utmCampaign\": \"Black friday\",\n \"utmiPage\": \"utmi_page-example\",\n \"utmiPart\": \"utmi_part-exmaple\",\n \"utmiCampaign\": \"utmi_campaign-exmaple\"\n },\n \"openTextField\": \"open-text-example\"\n}", "options": { "raw": { "language": "json" @@ -307,7 +307,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "755ef28c-897b-4050-8b1b-0b3e7339090c", + "id": "a05d2230-cf61-4b75-a654-49614116cadd", "name": "OK", "originalRequest": { "url": { @@ -323,7 +323,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -362,29 +362,29 @@ { "disabled": false, "description": { - "content": "(Required) VTEX API app key.", + "content": "(Required) HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "type": "text/plain" }, - "key": "x-vtex-api-appkey", - "value": "appKey" + "key": "Accept", + "value": "application/json" }, { "disabled": false, "description": { - "content": "(Required) VTEX API app token.", + "content": "", "type": "text/plain" }, - "key": "x-vtex-api-apptoken", - "value": "appToken" + "key": "X-VTEX-API-AppKey", + "value": "" }, { "disabled": false, "description": { - "content": "(Required) HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", + "content": "", "type": "text/plain" }, - "key": "accept", - "value": "application/json" + "key": "X-VTEX-API-AppToken", + "value": "" }, { "disabled": false, @@ -437,7 +437,7 @@ "content": "(Required) Describes the type of the content being sent.", "type": "text/plain" }, - "key": "content-type", + "key": "Content-Type", "value": "application/json" }, { @@ -457,7 +457,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{}", + "raw": "{\n \"marketplaceOrderId\": \"1138342255777-01\",\n \"marketplaceServicesEndpoint\": \"https://marketplaceservicesendpoint.myvtex.com/\",\n \"marketplacePaymentValue\": 2499,\n \"items\": [\n {\n \"id\": \"123456789abc\",\n \"quantity\": 1,\n \"seller\": \"seller-example\",\n \"commission\": 0,\n \"freightCommission\": 0,\n \"price\": 2499,\n \"bundleItems\": [\n {\n \"id\": \"bundle-item-1\",\n \"quantity\": 2\n },\n {\n \"id\": \"bundle-item-2\",\n \"quantity\": 1\n }\n ],\n \"itemsAttachment\": [\n {\n \"id\": \"attachment-1\",\n \"name\": \"Product Manual\",\n \"url\": \"https://example.com/manual.pdf\"\n }\n ],\n \"attachments\": [\n {\n \"id\": \"attachment-2\",\n \"name\": \"Product Image\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ],\n \"priceTags\": [\n {\n \"identifier\": \"1234abc-5678b-1234c\",\n \"isPercentual\": false,\n \"name\": \"discount@name-1234abc-5678b-1234c\",\n \"rawValue\": 12,\n \"value\": 1200\n }\n ],\n \"measurementUnit\": \"g\",\n \"unitMultiplier\": 1,\n \"isGift\": false\n }\n ],\n \"paymentData\": null,\n \"clientProfileData\": {\n \"email\": \"customer@examplemail.com\",\n \"firstName\": \"first-name\",\n \"lastName\": \"last-name\",\n \"documentType\": \"cpf\",\n \"document\": \"123456789\",\n \"phone\": \"+55110988887777\",\n \"corporateName\": null,\n \"tradeName\": null,\n \"corporateDocument\": null,\n \"stateInscription\": null,\n \"corporatePhone\": null,\n \"isCorporate\": false\n },\n \"shippingData\": {\n \"address\": {\n \"addressType\": \"residential\",\n \"receiverName\": \"receiver-name\",\n \"addressId\": \"Home\",\n \"postalCode\": \"12345-000\",\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"country\": \"BRA\",\n \"street\": \"Praia de Botafogo\",\n \"number\": \"300\",\n \"neighborhood\": \"Botafogo\",\n \"complement\": \"3rd floor\",\n \"reference\": \"Grey building\",\n \"geoCoordinates\": [\n \"00.00000\",\n \"00.00000\"\n ]\n },\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"selectedSla\": \"Express\",\n \"lockTTL\": \"8d\",\n \"shippingEstimate\": \"7d\",\n \"price\": 1099,\n \"deliveryWindow\": {\n \"startDateUtc\": \"2016-04-20T08:00:00+00:00\",\n \"endDateUtc\": \"2016-04-20T12:00:00+00:00\",\n \"listPrice\": 10\n }\n }\n ],\n \"updateStatus\": \"updated\"\n },\n \"marketingData\": {\n \"utmSource\": \"Facebook\",\n \"utmMedium\": \"CPC\",\n \"utmCampaign\": \"Black friday\",\n \"utmiPage\": \"utmi_page-example\",\n \"utmiPart\": \"utmi_part-exmaple\",\n \"utmiCampaign\": \"utmi_campaign-exmaple\"\n },\n \"openTextField\": \"open-text-example\"\n}", "options": { "raw": { "language": "json" @@ -473,7 +473,7 @@ "value": "application/json" } ], - "body": "{\n \"response\": {\n \"value\": [\n {\n \"marketplaceOrderId\": \"959311095\",\n \"orderId\": \"7890\",\n \"followUpEmail\": \"seller@example.com\",\n \"items\": [\n {\n \"id\": \"2002495\",\n \"quantity\": 1,\n \"seller\": \"1\",\n \"commission\": 0,\n \"freightCommission\": 0,\n \"price\": 2499,\n \"bundleItems\": [],\n \"itemAttachment\": {\n \"name\": null,\n \"content\": {}\n },\n \"attachments\": [],\n \"priceTags\": [],\n \"measurementUnit\": \"g\",\n \"unitMultiplier\": 1,\n \"isGift\": false\n }\n ],\n \"clientProfileData\": {\n \"email\": \"customer@examplemail.com.br\",\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"documentType\": \"taxpayer registration number\",\n \"document\": \"33333333333\",\n \"phone\": \"+55110988887777\",\n \"corporateName\": null,\n \"tradeName\": null,\n \"corporateDocument\": null,\n \"stateInscription\": null,\n \"corporatePhone\": null,\n \"isCorporate\": false,\n \"userProfileId\": null\n },\n \"shippingData\": {\n \"address\": {\n \"addressType\": \"residencial\",\n \"receiverName\": \"John Smith\",\n \"addressId\": \"Home\",\n \"postalCode\": \"12345-000\",\n \"city\": \"Rio de Janeiro\",\n \"state\": \"RJ\",\n \"country\": \"BRA\",\n \"street\": \"Praia de Botafogo\",\n \"number\": \"300\",\n \"neighborhood\": \"Botafogo\",\n \"complement\": null,\n \"reference\": \"Grey building\",\n \"geoCoordinates\": []\n },\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"selectedSla\": \"Express\",\n \"lockTTL\": \"8d\",\n \"shippingEstimate\": \"7d\",\n \"price\": 1099,\n \"deliveryWindow\": null\n }\n ]\n },\n \"customData\": {\n \"openTextField\": null,\n \"marketingData\": {\n \"utmSource\": \"buscape\",\n \"utmMedium\": \"\",\n \"utmCampaign\": \"freeshipping\",\n \"utmiPage\": \"_\",\n \"utmiPart\": \"BuscaFullText\",\n \"utmiCampaign\": \"artscase for iphone 5\"\n }\n },\n \"paymentData\": null,\n \"allowMultipleDeliveries\": true\n }\n ]\n }\n}", + "body": "{\n \"marketplaceOrderId\": \"959311095\",\n \"orderId\": \"7890\",\n \"followUpEmail\": \"seller@example.com\",\n \"items\": [\n {\n \"id\": \"2002495\",\n \"quantity\": 1,\n \"seller\": \"1\",\n \"commission\": 0,\n \"freightCommission\": 0,\n \"price\": 2499,\n \"bundleItems\": [],\n \"itemAttachment\": {\n \"name\": null,\n \"content\": {}\n },\n \"attachments\": [],\n \"priceTags\": [],\n \"measurementUnit\": \"g\",\n \"unitMultiplier\": 1,\n \"isGift\": false\n }\n ],\n \"clientProfileData\": {\n \"email\": \"customer@examplemail.com.br\",\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"documentType\": \"taxpayer registration number\",\n \"document\": \"33333333333\",\n \"phone\": \"+55110988887777\",\n \"corporateName\": null,\n \"tradeName\": null,\n \"corporateDocument\": null,\n \"stateInscription\": null,\n \"corporatePhone\": null,\n \"isCorporate\": false,\n \"userProfileId\": null\n },\n \"shippingData\": {\n \"address\": {\n \"addressType\": \"residencial\",\n \"receiverName\": \"John Smith\",\n \"addressId\": \"Home\",\n \"postalCode\": \"12345-000\",\n \"city\": \"Rio de Janeiro\",\n \"state\": \"RJ\",\n \"country\": \"BRA\",\n \"street\": \"Praia de Botafogo\",\n \"number\": \"300\",\n \"neighborhood\": \"Botafogo\",\n \"complement\": null,\n \"reference\": \"Grey building\",\n \"geoCoordinates\": []\n },\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"selectedSla\": \"Express\",\n \"lockTTL\": \"8d\",\n \"shippingEstimate\": \"7d\",\n \"price\": 1099,\n \"deliveryWindow\": null\n }\n ]\n },\n \"customData\": {\n \"openTextField\": null,\n \"marketingData\": {\n \"utmSource\": \"buscape\",\n \"utmMedium\": \"\",\n \"utmCampaign\": \"freeshipping\",\n \"utmiPage\": \"_\",\n \"utmiPart\": \"BuscaFullText\",\n \"utmiCampaign\": \"artscase for iphone 5\"\n }\n },\n \"paymentData\": null,\n \"allowMultipleDeliveries\": true\n}", "cookie": [] } ], @@ -481,7 +481,7 @@ { "listen": "test", "script": { - "id": "f5f47e16-843b-443e-b477-015114eb4a49", + "id": "b02b6ce2-7d79-4d30-90fd-d97c551966bf", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -497,12 +497,12 @@ } }, { - "id": "189f8155-38b0-4dda-a1ca-03ede3780bb8", + "id": "c6f723a0-8e01-436a-9ab5-32e8fce8d5df", "name": "Authorize fulfillment", "request": { "name": "Authorize fulfillment", "description": { - "content": "This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.", + "content": "This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "type": "text/plain" }, "url": { @@ -520,7 +520,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -565,7 +565,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "8b17c736-d0ce-4b31-a454-ae6dc9cd1885", + "id": "edbc6243-be74-4b49-9666-312131264c0d", "name": "OK", "originalRequest": { "url": { @@ -583,7 +583,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -653,7 +653,7 @@ "value": "application/json" } ], - "body": "{\n \"date\": \"2014-10-06 18:52:00\",\n \"marketplaceOrderId\": \"959311095\",\n \"orderId\": \"1138342255777-01\",\n \"receipt\": \"e39d05f9-0c54-4469-a626-8bb5cff169f8\"\n}", + "body": "{\n \"date\": \"2014-10-06 18:52:00\",\n \"marketplaceOrderId\": \"1138342255777-01\",\n \"orderId\": \"959311095\",\n \"receipt\": \"e39d05f9-0c54-4469-a626-8bb5cff169f8\"\n}", "cookie": [] } ], @@ -661,12 +661,13 @@ { "listen": "test", "script": { - "id": "fbabeb29-9731-4001-be20-b638e24ded90", + "id": "51a732ae-f7aa-440c-a510-6c6f7462f678", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:sellerOrderId/fulfill - 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/:sellerOrderId/fulfill - 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/:sellerOrderId/fulfill - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:sellerOrderId/fulfill - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"type\":\"object\",\"properties\":{\"date\":{\"type\":\"string\",\"title\":\"Date\",\"description\":\"Order approval date.\",\"example\":\"2014-10-06 18:52:00\"},\"marketplaceOrderId\":{\"type\":\"string\",\"title\":\"Marketplace Order Id\",\"description\":\"Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order.\",\"example\":\"1138342255777-01\"},\"orderId\":{\"type\":\"string\",\"title\":\"Order Id\",\"description\":\"\",\"example\":\"959311095\"},\"receipt\":{\"type\":\"string\",\"description\":\"Order receipt code.\",\"title\":\"Receipt\",\"example\":\"e39d05f9-0c54-4469-a626-8bb5cff169f8\"}}}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:sellerOrderId/fulfill - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -676,12 +677,12 @@ } }, { - "id": "40b9c0fa-af11-4fb7-9f3d-98c782a76e78", + "id": "66be3d29-3722-4c91-9eac-4dd730fd9f83", "name": "Marketplace order cancellation", "request": { "name": "Marketplace order cancellation", "description": { - "content": "This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seler, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\nThis call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.", + "content": "This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seler, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\n>❗️ This call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "type": "text/plain" }, "url": { @@ -699,7 +700,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -744,7 +745,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "f2905983-11f1-4e54-bf83-05831df218cc", + "id": "ae7b8204-3cfe-440f-a10f-63878c98661c", "name": "OK", "originalRequest": { "url": { @@ -762,7 +763,7 @@ { "disabled": false, "description": { - "content": "(Required) This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "content": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "type": "text/plain" }, "type": "any", @@ -840,12 +841,13 @@ { "listen": "test", "script": { - "id": "618987f2-e84f-4819-8602-d0b6397e9e27", + "id": "0edd840d-b435-46ff-8e6f-07360422c92d", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:orderId/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/:orderId/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/:orderId/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/:orderId/cancel - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"type\":\"object\",\"properties\":{\"date\":{\"type\":\"string\",\"title\":\"Date\",\"description\":\"Order approval date.\",\"example\":\"2014-10-06 18:52:00\"},\"marketplaceOrderId\":{\"type\":\"string\",\"title\":\"Marketplace Order Id\",\"description\":\"Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order.\",\"example\":\"1138342255777-01\"},\"orderId\":{\"type\":\"string\",\"title\":\"Order Id\",\"description\":\"\",\"example\":\"959311095\"},\"receipt\":{\"type\":\"string\",\"description\":\"Order receipt code.\",\"title\":\"Receipt\",\"example\":\"e39d05f9-0c54-4469-a626-8bb5cff169f8\"}}}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:orderId/cancel - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -896,7 +898,7 @@ } ], "info": { - "_postman_id": "8f779dd6-97c3-4c33-936d-ecddf77aab25", + "_postman_id": "f1a8a53e-8673-4f2f-9669-599fc4232eee", "name": "Marketplace Protocol", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { diff --git a/VTEX - Marketplace Protocol - External Seller Fulfillment.json b/VTEX - Marketplace Protocol - External Seller Fulfillment.json index 2e786b3fd..9368797d5 100644 --- a/VTEX - Marketplace Protocol - External Seller Fulfillment.json +++ b/VTEX - Marketplace Protocol - External Seller Fulfillment.json @@ -9,7 +9,7 @@ "servers": [ { "url": "https://{fulfillmentEndpoint}", - "description": "Fulfillment Endpoint", + "description": "Fulfillment Endpoint.", "variables": { "fulfillmentEndpoint": { "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", @@ -25,84 +25,24 @@ "External Seller" ], "summary": "Fulfillment simulation - External Seller", - "description": "This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) notification request returns a response with status `200 OK`, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.\n\nThe seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the paramenters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request, since they are not mandatory data for this context. \n- **Making a shopping cart simulation during checkout**: address information must be sent, since this data is needed to calculate freight values. If the address information (including `postalCode` and `country`) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout. \n \n## Request body example - Indexing simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"isCheckedIn\": false,\n }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"postalCode\": \"22270-030\",\n \"country\": \"BRA\",\n }\n```", + "description": "This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) notification request returns a response with status `200 OK`, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.\n\nThe seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the parameters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request since they are not mandatory data for this context. \n- **Making a shopping cart simulation during checkout**: address information must be sent since this data is needed to calculate freight values. If the address information (including `postalCode` and `country`) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout. \n \n## Request body example - Indexing simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"isCheckedIn\": false,\n }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"postalCode\": \"22270-030\",\n \"country\": \"BRA\",\n }\n```\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "fulfillment-simulation", "parameters": [ { - "name": "fulfillmentEndpoint", - "in": "path", - "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceexample.externalseller.com" - } + "$ref": "#/components/parameters/fulfillmentEndpoint" }, { - "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": { - "required": [ - "postalCode" - ], - "type": "object", - "properties": { - "postalCode": { - "type": "string", - "description": "Delivery address postal code. This field is mandatory for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", - "example": "12345678" - }, - "geoCoordinates": { - "type": "array", - "description": "Geographic coordinates of the delivery address. This may be used instead of the postalCode, in case the marketplace is configured to accept geolocation. Example of value: `[-22.9443504,-43.1825635]`.", - "items": { - "type": "string", - "example": "00.00000000" - } - }, - "country": { - "type": "string", - "description": "ISO 3-digit code of the country where the delivery address is located. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", - "example": "USA" - }, - "items": { - "type": "array", - "description": "Array containing the cart items.", - "items": { - "$ref": "#/components/schemas/fulfillmentItem" - } - }, - "sc": { - "type": "string", - "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.", - "example": "1" - } - } + "$ref": "#/components/schemas/requestFulfillmentSimulation" } } }, @@ -111,870 +51,10 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { "schema": { - "title": "Response body", - "description": "Expected response body of fulfillment simulation", - "type": "object", - "required": [ - "country", - "items", - "logisticsInfo", - "postalCode" - ], - "example": { - "country": "BRA", - "items": [ - { - "id": "2000037", - "listPrice": 67203, - "measurementUnit": "un", - "merchantName": "mySeller1", - "offerings": [ - { - "type": "Warranty", - "id": "5", - "name": "1 year warranty", - "price": 10000 - } - ], - "price": 67203, - "priceTags": [], - "priceValidUntil": "2014-03-01T22:58:28.143", - "quantity": 1, - "requestIndex": 0, - "seller": "1", - "unitMultiplier": 1 - } - ], - "logisticsInfo": [ - { - "itemIndex": 0, - "quantity": 1, - "shipsTo": [ - "BRA" - ], - "slas": [ - { - "id": "Curbside pickup", - "deliveryChannel": "pickup-in-point", - "name": "Curbside pickup", - "shippingEstimate": "0bd", - "price": 0, - "availableDeliveryWindows": [ - { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - } - ], - "pickupStoreInfo": { - "isPickupStore": true, - "friendlyName": "Santa Felicidade", - "address": { - "addressType": "pickup", - "receiverName": "Juliana", - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": "Next to the unicorn statue", - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - }, - "additionalInfo": "" - } - } - ], - "stockBalance": 199, - "deliveryChannels": [ - { - "id": "delivery", - "stockBalance": 179 - }, - { - "id": "pickup-in-point", - "stockBalance": 20 - } - ] - } - ], - "postalCode": "80250000", - "allowMultipleDeliveries": true - }, - "properties": { - "country": { - "title": "Country", - "description": "ISO 3-digit code of the country where the delivery address is located. If you don’t want to send it, use the value null.", - "type": "string", - "example": "BRA" - }, - "items": { - "title": "Items", - "description": "Contains the data about each SKU in the cart.", - "type": "array", - "items": { - "title": "Items", - "description": "Contains the data about each SKU in the cart.", - "type": "object", - "required": [ - "id", - "listPrice", - "measurementUnit", - "merchantName", - "offerings", - "price", - "priceTags", - "priceValidUntil", - "quantity", - "requestIndex", - "seller", - "unitMultiplier" - ], - "properties": { - "id": { - "title": "id", - "description": "SKU ID", - "type": "string", - "example": "2000037" - }, - "listPrice": { - "title": "listPrice", - "description": "List price. It’s the amount presented to the customer as a “previous” price that has been lowered due to a discount. Don’t separate the decimal places. The last two digits are the cents.", - "type": "integer", - "example": 67203 - }, - "measurementUnit": { - "title": "measurementUnit", - "description": "SKU’s measurement unit.", - "type": "string", - "example": "un" - }, - "merchantName": { - "title": "merchantName", - "description": "Name of the marketplace, used to guide payments. This field should be nulled if the marketplace is responsible for processing payments. Check out our [​​Payments in VTEX marketplaces](https://help.vtex.com/en/tutorial/payments-in-vtex-marketplaces--2kYOfWCZYweJkYl18bw9yD) article to know more.", - "type": "string", - "example": "mySeller1" - }, - "offerings": { - "title": "offerings", - "description": "Services that may be offered for this SKU. example are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.", - "type": "array", - "items": { - "title": "offerings", - "description": "Services that may be offered for this SKU. example are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.", - "type": "object", - "required": [ - "type", - "id", - "name", - "price" - ], - "properties": { - "type": { - "title": "type", - "description": "Type of the service.", - "type": "string", - "example": "Warranty" - }, - "id": { - "title": "id", - "description": "Service ID.", - "type": "string", - "example": "5" - }, - "name": { - "title": "name", - "description": "Service name.", - "type": "string", - "example": "1 year warranty" - }, - "price": { - "title": "price", - "description": "Service price. The last two digits are the cents.", - "type": "integer", - "example": 10000 - } - } - }, - "example": [ - { - "type": "Warranty", - "id": "5", - "name": "1 year warranty", - "price": 10000 - } - ] - }, - "price": { - "title": "price", - "description": "Actual selling price of the SKU. Don’t separate the decimal places. The last two digits are the cents.", - "type": "integer", - "example": 67203 - }, - "priceTags": { - "title": "priceTags", - "description": "List with the promotions applied to the SKU.", - "type": "array", - "items": { - "title": "priceTags", - "description": "Promotions applied to the SKU.", - "type": "string", - "example": "promotion 1" - } - }, - "priceValidUntil": { - "title": "priceValidUntil", - "description": "Expiration date of the SKU price. Example: `2014-03-01T22:58:28.143`. In case you don’t want to send it, use the value null.", - "type": "string", - "example": "2014-03-01T22:58:28.143", - "nullable": true - }, - "quantity": { - "title": "quantity", - "description": "Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.", - "type": "integer", - "default": 0, - "example": 1 - }, - "requestIndex": { - "title": "requestIndex", - "description": "Position of this item in the original array (request).", - "type": "integer", - "example": 0 - }, - "seller": { - "title": "seller", - "description": "ID of the seller as registered in VTEX. You should send the same value that came in the request.", - "type": "string", - "example": "1" - }, - "unitMultiplier": { - "title": "unitMultiplier", - "description": "SKU unit multiplier. The default value is 1.", - "type": "integer", - "example": 1 - } - } - }, - "example": [ - { - "id": "2000037", - "listPrice": 67203, - "measurementUnit": "un", - "merchantName": "mySeller1", - "offerings": [ - { - "type": "Warranty", - "id": "5", - "name": "1 year warranty", - "price": 10000 - } - ], - "price": 67203, - "priceTags": [], - "priceValidUntil": "2014-03-01T22:58:28.143", - "quantity": 1, - "requestIndex": 0, - "seller": "1", - "unitMultiplier": 1 - } - ] - }, - "logisticsInfo": { - "title": "logisticsInfo", - "description": "Array that contains the data regarding the delivery methods and stock for each item. If all products are unavailable, this field should return empty.", - "type": "array", - "items": { - "title": "A Schema", - "description": "An explanation about the purpose of this instance.", - "type": "object", - "required": [ - "itemIndex", - "quantity", - "shipsTo", - "slas", - "stockBalance", - "deliveryChannels" - ], - "properties": { - "itemIndex": { - "title": "itemIndex", - "description": "Position of this item in the original array, i.e., in the array that came with the request. This index is what identifies which SKU you are referring to for each object inside the logisticsInfo.", - "type": "integer", - "example": 0 - }, - "quantity": { - "title": "quantity", - "description": "Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.", - "type": "integer", - "example": 1 - }, - "shipsTo": { - "title": "shipsTo", - "description": "ISO 3-digit code of the countries to where the SKU is delivered.", - "type": "array", - "items": { - "title": "shipsTo", - "description": "Array of country codes", - "type": "string", - "example": "BRA" - }, - "example": [ - "BRA", - "BOL" - ] - }, - "slas": { - "title": "slas", - "description": "Contains the available delivery methods.", - "type": "array", - "items": { - "title": "slas", - "description": "Object with delivery methods information.", - "type": "object", - "required": [ - "id", - "deliveryChannel", - "name", - "price", - "shippingEstimate", - "availableDeliveryWindows", - "pickupStoreInfo" - ], - "properties": { - "id": { - "title": "id", - "description": "Identifier of the delivery method.", - "type": "string", - "example": "Curbside pickup" - }, - "deliveryChannel": { - "title": "deliveryChannel", - "description": "Type of delivery channel. The values that are possible are: `pickup-in-point` for pickup point and `delivery` for regular delivery.", - "type": "string", - "example": "pickup-in-point" - }, - "name": { - "title": "name", - "description": "Name of the delivery method.", - "type": "string", - "example": "Curbside pickup" - }, - "price": { - "title": "price", - "description": "Delivery price. The two last digits are the cents.", - "type": "integer", - "example": 846 - }, - "shippingEstimate": { - "title": "shippingEstimate", - "description": "Time estimated for the delivery. Possible suffixes are `bd` for *business day* , `h` for *hours*, and `m` for *minutes*.", - "type": "string", - "example": "19bd" - }, - "availableDeliveryWindows": { - "title": "availableDeliveryWindows", - "description": "Contains the delivery windows available for the SLA.", - "type": "array", - "items": { - "title": "availableDeliveryWindows", - "description": "Object with delivery windows information.", - "type": "object", - "required": [ - "startDateUtc", - "endDateUtc", - "price" - ], - "properties": { - "startDateUtc": { - "title": "startDateUtc", - "description": "Start date of the delivery window.", - "type": "string", - "example": "2013-02-04T08:00:00+00:00" - }, - "endDateUtc": { - "title": "endDateUtc", - "description": "End date of the delivery window.", - "type": "string", - "example": "2013-02-04T13:00:00+00:00" - }, - "price": { - "title": "price", - "description": "Extra price for scheduled delivery. The last two digits are the cents.", - "type": "integer", - "example": 0 - } - }, - "example": { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - } - }, - "example": [ - { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - }, - { - "startDateUtc": "2014-02-04T08:00:00+00:00", - "endDateUtc": "2014-02-04T13:00:00+00:00", - "price": 100 - } - ] - }, - "pickupStoreInfo": { - "title": "pickupStoreInfo", - "description": "Contains the data about the pickup point. If you don’t want to send this, use the value `null`.", - "type": "object", - "nullable": true, - "required": [ - "isPickupStore", - "friendlyName", - "address", - "additionalInfo" - ], - "properties": { - "isPickupStore": { - "title": "isPickupStore", - "description": "`true` if it is a pickup point.", - "type": "boolean", - "example": true - }, - "friendlyName": { - "title": "friendlyName", - "description": "Friendly name of the pickup point.", - "type": "string", - "example": "Store ABC" - }, - "address": { - "title": "address", - "description": "Address data of the pickup point.", - "type": "object", - "required": [ - "addressType", - "receiverName", - "addressId", - "postalCode", - "city", - "state", - "country", - "street", - "number", - "neighborhood", - "complement", - "reference", - "geoCoordinates" - ], - "properties": { - "addressType": { - "title": " addressType", - "description": "The possible value is pickup.", - "type": "string", - "example": "pickup" - }, - "receiverName": { - "title": "receiverName", - "description": "Name of the person who will receive the product. May be sent as `null`.", - "type": "string", - "example": "Juliana", - "nullable": true - }, - "addressId": { - "title": "addressId", - "description": "Identifies the pickup point.", - "type": "string", - "example": "548304ed-dd40-4416-b12b-4b32bfa7b1e0" - }, - "postalCode": { - "title": "postalCode", - "description": "Postal code of the pickup point. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", - "type": "string", - "example": "82320-040" - }, - "city": { - "title": "city", - "description": "Pickup point's city.", - "type": "string", - "example": "Rio de Janeiro" - }, - "state": { - "title": "state", - "description": "Pickup point's state.", - "type": "string", - "example": "RJ" - }, - "country": { - "title": "country", - "description": "3-digit ISO code of the country where the pickup point is located.", - "type": "string", - "example": "BRA" - }, - "street": { - "title": "street", - "description": "Street where the pickup point is located.", - "type": "string", - "example": "Rua Praia de Botafogo" - }, - "number": { - "title": "number", - "description": "Address number of the pickup point.", - "type": "string", - "example": "100" - }, - "neighborhood": { - "title": "neighborhood", - "description": "Neighborhood where the pickup point is located.", - "type": "string", - "example": "Botafogo" - }, - "complement": { - "title": "complement", - "description": "Complement of the pickup point address.", - "type": "string", - "example": "2nd floor" - }, - "reference": { - "title": "reference", - "description": "A reference for the pickup point address. ", - "type": "string", - "example": "Right next to the Unicorn statue.", - "nullable": true - }, - "geoCoordinates": { - "title": "geoCoordinates", - "description": "Contains the geographic coordinates of the pickup point.", - "type": "array", - "items": { - "title": "geoCoordinates", - "description": "Contains the geographic coordinates of the pickup point.", - "type": "number", - "example": 25.401705 - }, - "example": [ - -49.334934, - 25.401705 - ] - } - }, - "example": { - "addressType": "pickup", - "receiverName": "Juliana", - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": "Right next to the Unicorn statue.", - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - } - }, - "additionalInfo": { - "title": "additionalInfo", - "description": "Description or extra information about the pickup point.", - "type": "string", - "example": "Pick up your order at the cashier." - } - }, - "example": { - "isPickupStore": true, - "friendlyName": "Santa Felicidade", - "address": { - "addressType": "pickup", - "receiverName": "Juliana", - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": "Right next to the Unicorn statue.", - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - }, - "additionalInfo": "" - } - } - }, - "example": { - "id": "Curbside pickup", - "deliveryChannel": "pickup-in-point", - "name": "Curbside pickup", - "shippingEstimate": "0bd", - "price": 0, - "availableDeliveryWindows": [ - { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - } - ], - "pickupStoreInfo": { - "isPickupStore": true, - "friendlyName": "Santa Felicidade", - "address": { - "addressType": "pickup", - "receiverName": "Juliana", - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": "Right next to the Unicorn statue.", - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - }, - "additionalInfo": "" - } - } - }, - "example": [ - { - "id": "Curbside pickup", - "deliveryChannel": "pickup-in-point", - "name": "Curbside pickup", - "shippingEstimate": "0bd", - "price": 0, - "availableDeliveryWindows": [ - { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - } - ], - "pickupStoreInfo": { - "isPickupStore": true, - "friendlyName": "Santa Felicidade", - "address": { - "addressType": "pickup", - "receiverName": "Juliana", - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": "Right next to the Unicorn statue.", - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - }, - "additionalInfo": "" - } - } - ] - }, - "stockBalance": { - "title": "stockBalance", - "description": "Stock balance of the SKU.", - "type": "integer", - "example": 199 - }, - "deliveryChannels": { - "title": "deliveryChannels", - "description": "Array contains the stock balance for each channel.", - "type": "array", - "items": { - "title": "deliveryChannels", - "description": "Object containing ID and stockbalance of each delivery channel.", - "type": "object", - "required": [ - "id", - "stockBalance" - ], - "properties": { - "id": { - "title": "id", - "description": "Identifies the channel type whose stock balance will be informed in the next field. Possible values are: pickup-in-point for pickup point and delivery for regular delivery.", - "type": "string", - "example": "pickup-in-point" - }, - "stockBalance": { - "title": "stockBalance", - "description": "Stock balance for the channel type selected in the previous field.", - "type": "integer", - "example": 20 - } - }, - "example": { - "id": "delivery", - "stockBalance": 179 - } - }, - "example": [ - { - "id": "delivery", - "stockBalance": 179 - }, - { - "id": "pickup-in-point", - "stockBalance": 20 - } - ] - } - }, - "example": { - "itemIndex": 0, - "quantity": 1, - "shipsTo": [ - "BRA" - ], - "slas": [ - { - "id": "Curbside pickup", - "deliveryChannel": "pickup-in-point", - "name": "Curbside pickup", - "shippingEstimate": "0bd", - "price": 0, - "availableDeliveryWindows": [ - { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - } - ], - "pickupStoreInfo": { - "isPickupStore": true, - "friendlyName": "Santa Felicidade", - "address": { - "addressType": "pickup", - "receiverName": null, - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": null, - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - }, - "additionalInfo": "" - } - } - ], - "stockBalance": 199, - "deliveryChannels": [ - { - "id": "delivery", - "stockBalance": 179 - }, - { - "id": "pickup-in-point", - "stockBalance": 20 - } - ] - } - }, - "example": [ - { - "itemIndex": 0, - "quantity": 1, - "shipsTo": [ - "BRA" - ], - "slas": [ - { - "id": "Curbside pickup", - "deliveryChannel": "pickup-in-point", - "name": "Curbside pickup", - "shippingEstimate": "0bd", - "price": 0, - "availableDeliveryWindows": [ - { - "startDateUtc": "2013-02-04T08:00:00+00:00", - "endDateUtc": "2013-02-04T13:00:00+00:00", - "price": 0 - } - ], - "pickupStoreInfo": { - "isPickupStore": true, - "friendlyName": "Santa Felicidade", - "address": { - "addressType": "pickup", - "receiverName": null, - "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", - "postalCode": "82320-040", - "city": "Curitiba", - "state": "PR", - "country": "BRA", - "street": "Rua Domingos Strapasson", - "number": "100", - "neighborhood": "Santa Felicidade", - "complement": "Loja 10", - "reference": null, - "geoCoordinates": [ - 49.334934, - 25.401705 - ] - }, - "additionalInfo": "" - } - } - ], - "stockBalance": 199, - "deliveryChannels": [ - { - "id": "delivery", - "stockBalance": 179 - }, - { - "id": "pickup-in-point", - "stockBalance": 20 - } - ] - } - ] - }, - "postalCode": { - "title": "postalCode", - "description": "Postal code of the delivery address. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", - "type": "string", - "example": "80250000" - }, - "allowMultipleDeliveries": { - "description": "Flag for permission of multiple deliveries", - "type": "boolean" - } - } + "$ref": "#/components/schemas/responseFulfillmentSimulation" } } } @@ -989,161 +69,165 @@ "External Seller" ], "summary": "Order placement", - "description": "This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their own store.", + "description": "This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their store.\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| VTEX Fulfilment | Fulfilment Resources | **Place Orders** |\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| Create orders | Place Orders |\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": "order-placement", "parameters": [ { - "name": "fulfillmentEndpoint", - "in": "path", - "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "https://marketplaceexample.externalseller.com" - } + "$ref": "#/components/parameters/fulfillmentEndpoint" }, { - "name": "content-length", - "in": "header", - "description": "Length of the request body.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "2183" - } + "$ref": "#/components/parameters/content-length" }, { - "name": "authorization", - "in": "header", - "description": "Indicates authorization.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "VTEX key=\"appKey\" token=\"appToken\"" - } + "$ref": "#/components/parameters/authorization" }, { - "name": "x-vtex-api-appkey", - "in": "header", - "description": "VTEX API app key.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "appKey" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "x-vtex-api-apptoken", - "in": "header", - "description": "VTEX API app token.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "appToken" - } + "$ref": "#/components/securitySchemes/appKey" }, { - "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/securitySchemes/appToken" }, { - "name": "accept-enconding", - "in": "header", - "description": "Indicates the types of response enconding the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "gzip, deflate" - } + "$ref": "#/components/parameters/accept-enconding" }, { - "name": "x-vtex-operation-id", - "in": "header", - "description": "VTEX operation ID.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "8032114b-63e9-4e64-b30c-f7afcf676d7a" - } + "$ref": "#/components/parameters/vtexOperationID" }, { - "name": "x-forwarded-proto", - "in": "header", - "description": "Determines the protocol used by the client in the request.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "https" - } + "$ref": "#/components/parameters/forwardedProto" }, { - "name": "x-forwarded-for", - "in": "header", - "description": "Identifies the originating IP address of the HTTP client.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "179.35.30.186, 130.176.35.67, 172.16.247.49" - } + "$ref": "#/components/parameters/forwardedFor" }, { - "name": "x-vtex-cache-client-bypass", - "in": "header", - "description": "VTEX cache client bypass.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1" - } + "$ref": "#/components/parameters/vtexCacheClientBypass" }, { - "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" }, { - "name": "traceparent", - "in": "header", - "description": "Identifies the incoming request in a tracing system.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "00-083c0ca18bc8d94183f333809a70cd64-bf5e9a641e230540-00" - } + "$ref": "#/components/parameters/traceparent" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/orderPlacement" }, - "example": {} + "example": { + "marketplaceOrderId": "1138342255777-01", + "marketplaceServicesEndpoint": "https://marketplaceservicesendpoint.myvtex.com/", + "marketplacePaymentValue": 2499, + "items": [ + { + "id": "123456789abc", + "quantity": 1, + "seller": "seller-example", + "commission": 0, + "freightCommission": 0, + "price": 2499, + "bundleItems": [ + { + "id": "bundle-item-1", + "quantity": 2 + }, + { + "id": "bundle-item-2", + "quantity": 1 + } + ], + "itemsAttachment": [ + { + "id": "attachment-1", + "name": "Product Manual", + "url": "https://example.com/manual.pdf" + } + ], + "attachments": [ + { + "id": "attachment-2", + "name": "Product Image", + "url": "https://example.com/image.jpg" + } + ], + "priceTags": [ + { + "identifier": "1234abc-5678b-1234c", + "isPercentual": false, + "name": "discount@name-1234abc-5678b-1234c", + "rawValue": 12, + "value": 1200 + } + ], + "measurementUnit": "g", + "unitMultiplier": 1, + "isGift": false + } + ], + "paymentData": null, + "clientProfileData": { + "email": "customer@examplemail.com", + "firstName": "first-name", + "lastName": "last-name", + "documentType": "cpf", + "document": "123456789", + "phone": "+55110988887777", + "corporateName": null, + "tradeName": null, + "corporateDocument": null, + "stateInscription": null, + "corporatePhone": null, + "isCorporate": false + }, + "shippingData": { + "address": { + "addressType": "residential", + "receiverName": "receiver-name", + "addressId": "Home", + "postalCode": "12345-000", + "city": "Rio de Janeiro", + "state": "Rio de Janeiro", + "country": "BRA", + "street": "Praia de Botafogo", + "number": "300", + "neighborhood": "Botafogo", + "complement": "3rd floor", + "reference": "Grey building", + "geoCoordinates": [ + "00.00000", + "00.00000" + ] + }, + "logisticsInfo": [ + { + "itemIndex": 0, + "selectedSla": "Express", + "lockTTL": "8d", + "shippingEstimate": "7d", + "price": 1099, + "deliveryWindow": { + "startDateUtc": "2016-04-20T08:00:00+00:00", + "endDateUtc": "2016-04-20T12:00:00+00:00", + "listPrice": 10 + } + } + ], + "updateStatus": "updated" + }, + "marketingData": { + "utmSource": "Facebook", + "utmMedium": "CPC", + "utmCampaign": "Black friday", + "utmiPage": "utmi_page-example", + "utmiPart": "utmi_part-exmaple", + "utmiCampaign": "utmi_campaign-exmaple" + }, + "openTextField": "open-text-example" + } } }, "required": true @@ -1154,94 +238,88 @@ "headers": {}, "content": { "application/json": { - "schema":{ + "schema": { "$ref": "#/components/schemas/responseOrderPlacement" }, "example": { - "response": { - "value": [ + "marketplaceOrderId": "959311095", + "orderId": "7890", + "followUpEmail": "seller@example.com", + "items": [ + { + "id": "2002495", + "quantity": 1, + "seller": "1", + "commission": 0, + "freightCommission": 0, + "price": 2499, + "bundleItems": [], + "itemAttachment": { + "name": null, + "content": {} + }, + "attachments": [], + "priceTags": [], + "measurementUnit": "g", + "unitMultiplier": 1, + "isGift": false + } + ], + "clientProfileData": { + "email": "customer@examplemail.com.br", + "firstName": "John", + "lastName": "Smith", + "documentType": "taxpayer registration number", + "document": "33333333333", + "phone": "+55110988887777", + "corporateName": null, + "tradeName": null, + "corporateDocument": null, + "stateInscription": null, + "corporatePhone": null, + "isCorporate": false, + "userProfileId": null + }, + "shippingData": { + "address": { + "addressType": "residencial", + "receiverName": "John Smith", + "addressId": "Home", + "postalCode": "12345-000", + "city": "Rio de Janeiro", + "state": "RJ", + "country": "BRA", + "street": "Praia de Botafogo", + "number": "300", + "neighborhood": "Botafogo", + "complement": null, + "reference": "Grey building", + "geoCoordinates": [] + }, + "logisticsInfo": [ { - "marketplaceOrderId": "959311095", - "orderId": "7890", - "followUpEmail": "seller@example.com", - "items": [ - { - "id": "2002495", - "quantity": 1, - "seller": "1", - "commission": 0, - "freightCommission": 0, - "price": 2499, - "bundleItems": [], - "itemAttachment": { - "name": null, - "content": {} - }, - "attachments": [], - "priceTags": [], - "measurementUnit": "g", - "unitMultiplier": 1, - "isGift": false - } - ], - "clientProfileData": { - "email": "customer@examplemail.com.br", - "firstName": "John", - "lastName": "Smith", - "documentType": "taxpayer registration number", - "document": "33333333333", - "phone": "+55110988887777", - "corporateName": null, - "tradeName": null, - "corporateDocument": null, - "stateInscription": null, - "corporatePhone": null, - "isCorporate": false, - "userProfileId": null - }, - "shippingData": { - "address": { - "addressType": "residencial", - "receiverName": "John Smith", - "addressId": "Home", - "postalCode": "12345-000", - "city": "Rio de Janeiro", - "state": "RJ", - "country": "BRA", - "street": "Praia de Botafogo", - "number": "300", - "neighborhood": "Botafogo", - "complement": null, - "reference": "Grey building", - "geoCoordinates": [] - }, - "logisticsInfo": [ - { - "itemIndex": 0, - "selectedSla": "Express", - "lockTTL": "8d", - "shippingEstimate": "7d", - "price": 1099, - "deliveryWindow": null - } - ] - }, - "customData":{ - "openTextField": null, - "marketingData": { - "utmSource": "buscape", - "utmMedium": "", - "utmCampaign": "freeshipping", - "utmiPage": "_", - "utmiPart": "BuscaFullText", - "utmiCampaign": "artscase for iphone 5" - } - }, - "paymentData": null, - "allowMultipleDeliveries": true + "itemIndex": 0, + "selectedSla": "Express", + "lockTTL": "8d", + "shippingEstimate": "7d", + "price": 1099, + "deliveryWindow": null } ] - } + }, + "customData": { + "openTextField": null, + "marketingData": { + "utmSource": "buscape", + "utmMedium": "", + "utmCampaign": "freeshipping", + "utmiPage": "_", + "utmiPart": "BuscaFullText", + "utmiCampaign": "artscase for iphone 5" + } + }, + "paymentData": null, + "allowMultipleDeliveries": true } } } @@ -1255,71 +333,27 @@ "External Seller" ], "summary": "Authorize fulfillment", - "description": "This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.", + "description": "This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "authorize-fulfillment", "parameters": [ { - "name": "fulfillmentEndpoint", - "in": "path", - "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "https://marketplaceexample.externalseller.com" - } + "$ref": "#/components/parameters/fulfillmentEndpoint" }, { - "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", - "default": "application/json" - } + "$ref": "#/components/parameters/Content-Type" }, { - "name": "sellerOrderId", - "in": "path", - "description": "Seller's order ID of the order ready for fulfillment. The seller can be a VTEX seller or an external one.", - "required": true, - "example": "00-1268540501456-01", - "style": "simple", - "schema": { - "type": "string", - "example": "00-1268540501456-01" - } + "$ref": "#/components/parameters/sellerOrderId" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "required": [ - "marketplaceOrderId" - ], - "type": "object", - "properties": { - "marketplaceOrderId": { - "type": "string", - "description": "Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order.", - "example": "1138342255777-01" - } - } + "$ref": "#/components/schemas/requestOrderId" } } }, @@ -1328,18 +362,16 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2014-10-06 18:52:00", - "marketplaceOrderId": "959311095", - "orderId": "1138342255777-01", - "receipt": "e39d05f9-0c54-4469-a626-8bb5cff169f8" - } - } + "schema": { + "$ref": "#/components/schemas/repsonseOrderId" + }, + "example": { + "date": "2014-10-06 18:52:00", + "marketplaceOrderId": "1138342255777-01", + "orderId": "959311095", + "receipt": "e39d05f9-0c54-4469-a626-8bb5cff169f8" } } } @@ -1353,70 +385,27 @@ "External Seller" ], "summary": "Marketplace order cancellation", - "description": "This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seler, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\nThis call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.", + "description": "This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seller, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\n>⚠️ This call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.\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| Cancela Pedidos | 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": "mkp-order-cancellation", "parameters": [ { - "name": "fulfillmentEndpoint", - "in": "path", - "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceexample.externalseller.com" - } + "$ref": "#/components/parameters/fulfillmentEndpoint" }, { - "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" }, { - "name": "orderId", - "in": "path", - "description": "ID of the order being fulfilled", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "default": "1138342255777-01" - } + "$ref": "#/components/parameters/orderId" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "required": [ - "marketplaceOrderId" - ], - "type": "object", - "properties": { - "marketplaceOrderId": { - "type": "string", - "description": "Identifies the order. The seller should use this ID to trigger the cancellation of the corresponding order.", - "default": "1138342255777-01" - } - } + "$ref": "#/components/schemas/requestOrderId" }, "example": { "marketplaceOrderId": "1138342255777-01" @@ -1428,18 +417,16 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2019-05-09 15:31:23", - "marketplaceOrderId": "959311095", - "orderId": "1138342255777-01", - "receipt": "e39d05f9-0c54-4469-a626-8bb5cff169f8" - } - } + "schema": { + "$ref": "#/components/schemas/repsonseOrderId" + }, + "example": { + "date": "2019-05-09 15:31:23", + "marketplaceOrderId": "959311095", + "orderId": "1138342255777-01", + "receipt": "e39d05f9-0c54-4469-a626-8bb5cff169f8" } } } @@ -1798,7 +785,7 @@ }, "selectedSla": { "type": "string", - "description": "Selected shipping option", + "description": "Selected shipping option.", "example": "Express" }, "lockTTL": { @@ -1842,7 +829,7 @@ }, "updateStatus": { "type": "string", - "description": "Indicate whether this object's information is up to date according to the order's items. An order can not be placed if `\"outdated\"`", + "description": "Indicate whether this object's information is up to date according to the order's items. An order can not be placed if `\"outdated\"`.", "example": "updated" } } @@ -1863,29 +850,29 @@ }, "utmCampaign": { "type": "string", - "description": "UTM campaign", + "description": "UTM campaign.", "example": "Black friday" }, "utmiPage": { "type": "string", - "description": "utmi_page (internal utm)", + "description": "utmi_page (internal utm).", "example": "utmi_page-example" }, "utmiPart": { "type": "string", - "description": "utmi_part (internal utm)", + "description": "utmi_part (internal utm).", "example": "utmi_part-exmaple" }, "utmiCampaign": { "type": "string", - "description": "utmi_campaign (internal utm)", + "description": "utmi_campaign (internal utm).", "example": "utmi_campaign-exmaple" } } }, "openTextField": { "type": "string", - "description": "Optional field meant to hold additional information about the order. We recommend using this field for text, not data formats such as `json` even if escaped. For that purpose, see [Creating customizable fields](https://developers.vtex.com/vtex-rest-api/docs/creating-customizable-fields-in-the-cart-with-checkout-api-1)", + "description": "Optional field meant to hold additional information about the order. We recommend using this field for text, not data formats such as `json` even if escaped. For that purpose, see [Creating customizable fields](https://developers.vtex.com/vtex-rest-api/docs/creating-customizable-fields-in-the-cart-with-checkout-api-1).", "example": "open-text-example" } } @@ -1894,19 +881,19 @@ "type": "object", "properties": { "marketplaceOrderId": { - "description": "Number of the order in the marketplace", + "description": "Number of the order in the marketplace.", "type": "string" }, "orderId": { - "description": "Order number", + "description": "Order number.", "type": "string" }, "followUpEmail": { - "description": "Email for contact with the store (seller)", + "description": "Email for contact with the store (seller).", "type": "string" }, "items": { - "description": "List of order items", + "description": "List of order items.", "type": "array", "items": { "type": "object", @@ -2012,7 +999,7 @@ } }, "clientProfileData": { - "description": "Customer's data", + "description": "Customer's data.", "type": "object", "properties": { "email": { @@ -2190,7 +1177,7 @@ }, "selectedSla": { "type": "string", - "description": "Selected shipping option", + "description": "Selected shipping option.", "example": "Express" }, "lockTTL": { @@ -2241,11 +1228,11 @@ "default": null }, "customData": { - "description": "Custom data for the order", + "description": "Custom data for the order.", "type": "object" }, "allowMultipleDeliveries": { - "description": "Flag for permission of multiple deliveries", + "description": "Flag for permission of multiple deliveries.", "type": "boolean" } } @@ -2289,6 +1276,947 @@ "example": "content-example" } } + }, + "requestFulfillmentSimulation": { + "required": [ + "postalCode" + ], + "type": "object", + "properties": { + "postalCode": { + "type": "string", + "description": "Delivery address postal code. This field is mandatory for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", + "example": "12345678" + }, + "geoCoordinates": { + "type": "array", + "description": "Geographic coordinates of the delivery address. This may be used instead of the postalCode, in case the marketplace is configured to accept geolocation. Example of value: `[-22.9443504,-43.1825635]`.", + "items": { + "type": "string", + "example": "00.00000000" + } + }, + "country": { + "type": "string", + "description": "ISO 3-digit code of the country where the delivery address is located. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", + "example": "USA" + }, + "items": { + "type": "array", + "description": "Array containing the cart items.", + "items": { + "$ref": "#/components/schemas/fulfillmentItem" + } + }, + "sc": { + "type": "string", + "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.", + "example": "1" + } + } + }, + "responseFulfillmentSimulation": { + "title": "Response body", + "description": "Expected response body of fulfillment simulation.", + "type": "object", + "required": [ + "country", + "items", + "logisticsInfo", + "postalCode" + ], + "example": { + "country": "BRA", + "items": [ + { + "id": "2000037", + "listPrice": 67203, + "measurementUnit": "un", + "merchantName": "mySeller1", + "offerings": [ + { + "type": "Warranty", + "id": "5", + "name": "1 year warranty", + "price": 10000 + } + ], + "price": 67203, + "priceTags": [], + "priceValidUntil": "2014-03-01T22:58:28.143", + "quantity": 1, + "requestIndex": 0, + "seller": "1", + "unitMultiplier": 1 + } + ], + "logisticsInfo": [ + { + "itemIndex": 0, + "quantity": 1, + "shipsTo": [ + "BRA" + ], + "slas": [ + { + "id": "Curbside pickup", + "deliveryChannel": "pickup-in-point", + "name": "Curbside pickup", + "shippingEstimate": "0bd", + "price": 0, + "availableDeliveryWindows": [ + { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + } + ], + "pickupStoreInfo": { + "isPickupStore": true, + "friendlyName": "Santa Felicidade", + "address": { + "addressType": "pickup", + "receiverName": "Juliana", + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": "Next to the unicorn statue", + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + }, + "additionalInfo": "" + } + } + ], + "stockBalance": 199, + "deliveryChannels": [ + { + "id": "delivery", + "stockBalance": 179 + }, + { + "id": "pickup-in-point", + "stockBalance": 20 + } + ] + } + ], + "postalCode": "80250000", + "allowMultipleDeliveries": true + }, + "properties": { + "country": { + "title": "Country", + "description": "ISO 3-digit code of the country where the delivery address is located. If you don’t want to send it, use the value null.", + "type": "string", + "example": "BRA" + }, + "items": { + "title": "Items", + "description": "Contains the data about each SKU in the cart.", + "type": "array", + "items": { + "title": "Items", + "description": "Contains the data about each SKU in the cart.", + "type": "object", + "required": [ + "id", + "listPrice", + "measurementUnit", + "merchantName", + "offerings", + "price", + "priceTags", + "priceValidUntil", + "quantity", + "requestIndex", + "seller", + "unitMultiplier" + ], + "properties": { + "id": { + "title": "id", + "description": "SKU ID.", + "type": "string", + "example": "2000037" + }, + "listPrice": { + "title": "listPrice", + "description": "List price. It’s the amount presented to the customer as a “previous” price that has been lowered due to a discount. Don’t separate the decimal places. The last two digits are the cents.", + "type": "integer", + "example": 67203 + }, + "measurementUnit": { + "title": "measurementUnit", + "description": "SKU’s measurement unit.", + "type": "string", + "example": "un" + }, + "merchantName": { + "title": "merchantName", + "description": "Name of the marketplace, used to guide payments. This field should be nulled if the marketplace is responsible for processing payments. Check out our [​​Payments in VTEX marketplaces](https://help.vtex.com/en/tutorial/payments-in-vtex-marketplaces--2kYOfWCZYweJkYl18bw9yD) article to know more.", + "type": "string", + "example": "mySeller1" + }, + "offerings": { + "title": "offerings", + "description": "Services that may be offered for this SKU. example are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.", + "type": "array", + "items": { + "title": "offerings", + "description": "Services that may be offered for this SKU. example are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.", + "type": "object", + "required": [ + "type", + "id", + "name", + "price" + ], + "properties": { + "type": { + "title": "type", + "description": "Type of the service.", + "type": "string", + "example": "Warranty" + }, + "id": { + "title": "id", + "description": "Service ID.", + "type": "string", + "example": "5" + }, + "name": { + "title": "name", + "description": "Service name.", + "type": "string", + "example": "1 year warranty" + }, + "price": { + "title": "price", + "description": "Service price. The last two digits are the cents.", + "type": "integer", + "example": 10000 + } + } + }, + "example": [ + { + "type": "Warranty", + "id": "5", + "name": "1 year warranty", + "price": 10000 + } + ] + }, + "price": { + "title": "price", + "description": "Actual selling price of the SKU. Don’t separate the decimal places. The last two digits are the cents.", + "type": "integer", + "example": 67203 + }, + "priceTags": { + "title": "priceTags", + "description": "List with the promotions applied to the SKU.", + "type": "array", + "items": { + "title": "priceTags", + "description": "Promotions applied to the SKU.", + "type": "string", + "example": "promotion 1" + } + }, + "priceValidUntil": { + "title": "priceValidUntil", + "description": "Expiration date of the SKU price. Example: `2014-03-01T22:58:28.143`. In case you don’t want to send it, use the value null.", + "type": "string", + "example": "2014-03-01T22:58:28.143", + "nullable": true + }, + "quantity": { + "title": "quantity", + "description": "Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.", + "type": "integer", + "default": 0, + "example": 1 + }, + "requestIndex": { + "title": "requestIndex", + "description": "Position of this item in the original array (request).", + "type": "integer", + "example": 0 + }, + "seller": { + "title": "seller", + "description": "ID of the seller as registered in VTEX. You should send the same value that came in the request.", + "type": "string", + "example": "1" + }, + "unitMultiplier": { + "title": "unitMultiplier", + "description": "SKU unit multiplier. The default value is 1.", + "type": "integer", + "example": 1 + } + } + }, + "example": [ + { + "id": "2000037", + "listPrice": 67203, + "measurementUnit": "un", + "merchantName": "mySeller1", + "offerings": [ + { + "type": "Warranty", + "id": "5", + "name": "1 year warranty", + "price": 10000 + } + ], + "price": 67203, + "priceTags": [], + "priceValidUntil": "2014-03-01T22:58:28.143", + "quantity": 1, + "requestIndex": 0, + "seller": "1", + "unitMultiplier": 1 + } + ] + }, + "logisticsInfo": { + "title": "logisticsInfo", + "description": "Array that contains the data regarding the delivery methods and stock for each item. If all products are unavailable, this field should return empty.", + "type": "array", + "items": { + "description": "Description of each logistics data object.", + "type": "object", + "required": [ + "itemIndex", + "quantity", + "shipsTo", + "slas", + "stockBalance", + "deliveryChannels" + ], + "properties": { + "itemIndex": { + "title": "itemIndex", + "description": "Position of this item in the original array, i.e., in the array that came with the request. This index is what identifies which SKU you are referring to for each object inside the `logisticsInfo`.", + "type": "integer", + "example": 0 + }, + "quantity": { + "title": "quantity", + "description": "Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.", + "type": "integer", + "example": 1 + }, + "shipsTo": { + "title": "shipsTo", + "description": "ISO 3-digit code of the countries to where the SKU is delivered.", + "type": "array", + "items": { + "title": "shipsTo", + "description": "Array of country codes.", + "type": "string", + "example": "BRA" + }, + "example": [ + "BRA", + "BOL" + ] + }, + "slas": { + "title": "slas", + "description": "Contains the available delivery methods.", + "type": "array", + "items": { + "title": "slas", + "description": "Object with delivery methods information.", + "type": "object", + "required": [ + "id", + "deliveryChannel", + "name", + "price", + "shippingEstimate", + "availableDeliveryWindows", + "pickupStoreInfo" + ], + "properties": { + "id": { + "title": "id", + "description": "Identifier of the delivery method.", + "type": "string", + "example": "Curbside pickup" + }, + "deliveryChannel": { + "title": "deliveryChannel", + "description": "Type of delivery channel. The values that are possible are: `pickup-in-point` for pickup point and `delivery` for regular delivery.", + "type": "string", + "example": "pickup-in-point" + }, + "name": { + "title": "name", + "description": "Name of the delivery method.", + "type": "string", + "example": "Curbside pickup" + }, + "price": { + "title": "price", + "description": "Delivery price. The two last digits are the cents.", + "type": "integer", + "example": 846 + }, + "shippingEstimate": { + "title": "shippingEstimate", + "description": "Time estimated for the delivery. Possible suffixes are `bd` for *business day* , `h` for *hours*, and `m` for *minutes*.", + "type": "string", + "example": "19bd" + }, + "availableDeliveryWindows": { + "title": "availableDeliveryWindows", + "description": "Contains the delivery windows available for the SLA.", + "type": "array", + "items": { + "title": "availableDeliveryWindows", + "description": "Object with delivery windows information.", + "type": "object", + "required": [ + "startDateUtc", + "endDateUtc", + "price" + ], + "properties": { + "startDateUtc": { + "title": "startDateUtc", + "description": "Start date of the delivery window.", + "type": "string", + "example": "2013-02-04T08:00:00+00:00" + }, + "endDateUtc": { + "title": "endDateUtc", + "description": "End date of the delivery window.", + "type": "string", + "example": "2013-02-04T13:00:00+00:00" + }, + "price": { + "title": "price", + "description": "Extra price for scheduled delivery. The last two digits are the cents.", + "type": "integer", + "example": 0 + } + }, + "example": { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + } + }, + "example": [ + { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + }, + { + "startDateUtc": "2014-02-04T08:00:00+00:00", + "endDateUtc": "2014-02-04T13:00:00+00:00", + "price": 100 + } + ] + }, + "pickupStoreInfo": { + "title": "pickupStoreInfo", + "description": "Contains the data about the pickup point. If you do not want to send this, use the value `null`.", + "type": "object", + "nullable": true, + "required": [ + "isPickupStore", + "friendlyName", + "address", + "additionalInfo" + ], + "properties": { + "isPickupStore": { + "title": "isPickupStore", + "description": "`true` if it is a pickup point.", + "type": "boolean", + "example": true + }, + "friendlyName": { + "title": "friendlyName", + "description": "Friendly name of the pickup point.", + "type": "string", + "example": "Store ABC" + }, + "address": { + "title": "address", + "description": "Address data of the pickup point.", + "type": "object", + "required": [ + "addressType", + "receiverName", + "addressId", + "postalCode", + "city", + "state", + "country", + "street", + "number", + "neighborhood", + "complement", + "reference", + "geoCoordinates" + ], + "properties": { + "addressType": { + "title": " addressType", + "description": "The possible value is pickup.", + "type": "string", + "example": "pickup" + }, + "receiverName": { + "title": "receiverName", + "description": "Name of the person who will receive the product. May be sent as `null`.", + "type": "string", + "example": "Juliana", + "nullable": true + }, + "addressId": { + "title": "addressId", + "description": "Identifies the pickup point.", + "type": "string", + "example": "548304ed-dd40-4416-b12b-4b32bfa7b1e0" + }, + "postalCode": { + "title": "postalCode", + "description": "Postal code of the pickup point. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", + "type": "string", + "example": "82320-040" + }, + "city": { + "title": "city", + "description": "Pickup point's city.", + "type": "string", + "example": "Rio de Janeiro" + }, + "state": { + "title": "state", + "description": "Pickup point's state.", + "type": "string", + "example": "RJ" + }, + "country": { + "title": "country", + "description": "3-digit ISO code of the country where the pickup point is located.", + "type": "string", + "example": "BRA" + }, + "street": { + "title": "street", + "description": "Street where the pickup point is located.", + "type": "string", + "example": "Rua Praia de Botafogo" + }, + "number": { + "title": "number", + "description": "Address number of the pickup point.", + "type": "string", + "example": "100" + }, + "neighborhood": { + "title": "neighborhood", + "description": "Neighborhood where the pickup point is located.", + "type": "string", + "example": "Botafogo" + }, + "complement": { + "title": "complement", + "description": "Complement of the pickup point address.", + "type": "string", + "example": "2nd floor" + }, + "reference": { + "title": "reference", + "description": "A reference for the pickup point address. ", + "type": "string", + "example": "Right next to the Unicorn statue.", + "nullable": true + }, + "geoCoordinates": { + "title": "geoCoordinates", + "description": "Contains the geographic coordinates of the pickup point.", + "type": "array", + "items": { + "title": "geoCoordinates", + "description": "Contains the geographic coordinates of the pickup point.", + "type": "number", + "example": 25.401705 + }, + "example": [ + -49.334934, + 25.401705 + ] + } + }, + "example": { + "addressType": "pickup", + "receiverName": "Juliana", + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": "Right next to the Unicorn statue.", + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + } + }, + "additionalInfo": { + "title": "additionalInfo", + "description": "Description or extra information about the pickup point.", + "type": "string", + "example": "Pick up your order at the cashier." + } + }, + "example": { + "isPickupStore": true, + "friendlyName": "Santa Felicidade", + "address": { + "addressType": "pickup", + "receiverName": "Juliana", + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": "Right next to the Unicorn statue.", + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + }, + "additionalInfo": "" + } + } + }, + "example": { + "id": "Curbside pickup", + "deliveryChannel": "pickup-in-point", + "name": "Curbside pickup", + "shippingEstimate": "0bd", + "price": 0, + "availableDeliveryWindows": [ + { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + } + ], + "pickupStoreInfo": { + "isPickupStore": true, + "friendlyName": "Santa Felicidade", + "address": { + "addressType": "pickup", + "receiverName": "Juliana", + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": "Right next to the Unicorn statue.", + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + }, + "additionalInfo": "" + } + } + }, + "example": [ + { + "id": "Curbside pickup", + "deliveryChannel": "pickup-in-point", + "name": "Curbside pickup", + "shippingEstimate": "0bd", + "price": 0, + "availableDeliveryWindows": [ + { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + } + ], + "pickupStoreInfo": { + "isPickupStore": true, + "friendlyName": "Santa Felicidade", + "address": { + "addressType": "pickup", + "receiverName": "Juliana", + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": "Right next to the Unicorn statue.", + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + }, + "additionalInfo": "" + } + } + ] + }, + "stockBalance": { + "title": "stockBalance", + "description": "Stock balance of the SKU.", + "type": "integer", + "example": 199 + }, + "deliveryChannels": { + "title": "deliveryChannels", + "description": "Array contains the stock balance for each channel.", + "type": "array", + "items": { + "title": "deliveryChannels", + "description": "Object containing ID and stockbalance of each delivery channel.", + "type": "object", + "required": [ + "id", + "stockBalance" + ], + "properties": { + "id": { + "title": "id", + "description": "Identifies the channel type whose stock balance will be informed in the next field. Possible values are: pickup-in-point for pickup point and delivery for regular delivery.", + "type": "string", + "example": "pickup-in-point" + }, + "stockBalance": { + "title": "stockBalance", + "description": "Stock balance for the channel type selected in the previous field.", + "type": "integer", + "example": 20 + } + }, + "example": { + "id": "delivery", + "stockBalance": 179 + } + }, + "example": [ + { + "id": "delivery", + "stockBalance": 179 + }, + { + "id": "pickup-in-point", + "stockBalance": 20 + } + ] + } + }, + "example": { + "itemIndex": 0, + "quantity": 1, + "shipsTo": [ + "BRA" + ], + "slas": [ + { + "id": "Curbside pickup", + "deliveryChannel": "pickup-in-point", + "name": "Curbside pickup", + "shippingEstimate": "0bd", + "price": 0, + "availableDeliveryWindows": [ + { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + } + ], + "pickupStoreInfo": { + "isPickupStore": true, + "friendlyName": "Santa Felicidade", + "address": { + "addressType": "pickup", + "receiverName": null, + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": null, + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + }, + "additionalInfo": "" + } + } + ], + "stockBalance": 199, + "deliveryChannels": [ + { + "id": "delivery", + "stockBalance": 179 + }, + { + "id": "pickup-in-point", + "stockBalance": 20 + } + ] + } + }, + "example": [ + { + "itemIndex": 0, + "quantity": 1, + "shipsTo": [ + "BRA" + ], + "slas": [ + { + "id": "Curbside pickup", + "deliveryChannel": "pickup-in-point", + "name": "Curbside pickup", + "shippingEstimate": "0bd", + "price": 0, + "availableDeliveryWindows": [ + { + "startDateUtc": "2013-02-04T08:00:00+00:00", + "endDateUtc": "2013-02-04T13:00:00+00:00", + "price": 0 + } + ], + "pickupStoreInfo": { + "isPickupStore": true, + "friendlyName": "Santa Felicidade", + "address": { + "addressType": "pickup", + "receiverName": null, + "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0", + "postalCode": "82320-040", + "city": "Curitiba", + "state": "PR", + "country": "BRA", + "street": "Rua Domingos Strapasson", + "number": "100", + "neighborhood": "Santa Felicidade", + "complement": "Loja 10", + "reference": null, + "geoCoordinates": [ + 49.334934, + 25.401705 + ] + }, + "additionalInfo": "" + } + } + ], + "stockBalance": 199, + "deliveryChannels": [ + { + "id": "delivery", + "stockBalance": 179 + }, + { + "id": "pickup-in-point", + "stockBalance": 20 + } + ] + } + ] + }, + "postalCode": { + "title": "postalCode", + "description": "Postal code of the delivery address. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.", + "type": "string", + "example": "80250000" + }, + "allowMultipleDeliveries": { + "description": "Flag for permission of multiple deliveries.", + "type": "boolean" + } + } + }, + "requestOrderId": { + "required": [ + "marketplaceOrderId" + ], + "type": "object", + "properties": { + "marketplaceOrderId": { + "type": "string", + "description": "Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order.", + "example": "1138342255777-01" + } + } + }, + "repsonseOrderId": { + "type": "object", + "properties": { + "date": { + "type": "string", + "title": "Date", + "description": "Order approval date.", + "example": "2014-10-06 18:52:00" + }, + "marketplaceOrderId": { + "type": "string", + "title": "Marketplace Order Id", + "description": "Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order.", + "example": "1138342255777-01" + }, + "orderId": { + "type": "string", + "title": "Order Id", + "description": "Order number.", + "example": "959311095" + }, + "receipt": { + "type": "string", + "description": "Order receipt code.", + "title": "Receipt", + "example": "e39d05f9-0c54-4469-a626-8bb5cff169f8" + } + } } }, "securitySchemes": { @@ -2302,6 +2230,152 @@ "in": "header", "name": "X-VTEX-API-AppToken" } + }, + "parameters": { + "fulfillmentEndpoint": { + "name": "fulfillmentEndpoint", + "in": "path", + "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "marketplaceexample.externalseller.com" + } + }, + "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", + "example": "application/json" + } + }, + "Content-Type": { + "name": "Content-Type", + "in": "header", + "description": "Describes the type of the content being sent.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "application/json" + } + }, + "content-length": { + "name": "content-length", + "in": "header", + "description": "Length of the request body.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "2183" + } + }, + "authorization": { + "name": "authorization", + "in": "header", + "description": "Indicates authorization.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "VTEX key=\"appKey\" token=\"appToken\"" + } + }, + "accept-enconding": { + "name": "accept-enconding", + "in": "header", + "description": "Indicates the types of response enconding the client can understand.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "gzip, deflate" + } + }, + "vtexOperationID": { + "name": "x-vtex-operation-id", + "in": "header", + "description": "VTEX operation ID.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "8032114b-63e9-4e64-b30c-f7afcf676d7a" + } + }, + "forwardedProto": { + "name": "x-forwarded-proto", + "in": "header", + "description": "Determines the protocol used by the client in the request.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "https" + } + }, + "forwardedFor": { + "name": "x-forwarded-for", + "in": "header", + "description": "Identifies the originating IP address of the HTTP client.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "179.35.30.186, 130.176.35.67, 172.16.247.49" + } + }, + "vtexCacheClientBypass": { + "name": "x-vtex-cache-client-bypass", + "in": "header", + "description": "VTEX cache client bypass.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "1" + } + }, + "traceparent": { + "name": "traceparent", + "in": "header", + "description": "Identifies the incoming request in a tracing system.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "00-083c0ca18bc8d94183f333809a70cd64-bf5e9a641e230540-00" + } + }, + "sellerOrderId": { + "name": "sellerOrderId", + "in": "path", + "description": "Seller's order ID of the order ready for fulfillment. The seller can be a VTEX seller or an external one.", + "required": true, + "example": "00-1268540501456-01", + "style": "simple", + "schema": { + "type": "string", + "example": "00-1268540501456-01" + } + }, + "orderId": { + "name": "orderId", + "in": "path", + "description": "ID of the order being fulfilled.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "1138342255777-01" + } + } } }, "tags": [