From bb16a792b417f25db8666862e604768dd23ec6de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Wed, 13 Dec 2023 19:16:18 -0300 Subject: [PATCH 1/8] KR5| external seller marketplace Update request, response, schema, descriptions, $ref and permissions. --- ...rotocol - External Seller Marketplace.json | 686 +++++++++--------- 1 file changed, 330 insertions(+), 356 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index f9b940e25..f96ea07ac 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -3,7 +3,6 @@ "info": { "title": "Marketplace Protocol", "description": "\r\nThe _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", - "contact": {}, "version": "1.0" }, "servers": [ @@ -25,132 +24,28 @@ "External Seller" ], "summary": "Send invoice", - "description": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.", + "description": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.3\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "send-invoice", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/Content-Type" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" } ], "requestBody": { - "description": "", + "description": "Description of fields and example of a request body.", "content": { "application/json": { "schema": { - "required": [ - "type", - "invoiceNumber", - "items" - ], - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.", - "example": "Output" - }, - "invoiceNumber": { - "type": "string", - "description": "Invoice number", - "example": "NFe-00002" - }, - "courier": { - "type": "string", - "description": "Courier, if available on invoice.", - "example": "courier-example" - }, - "trackingNumber": { - "type": "string", - "description": "Tracking number.", - "example": "12345678abc" - }, - "trackingUrl": { - "type": "string", - "description": "Tracking URL.", - "example": "https://courier-example.com/tracking" - }, - "items": { - "type": "array", - "description": "Array containing the order items.", - "items": { - "type": "object", - "description": "", - "required": [ - "id", - "quantity", - "price" - ], - "properties": { - "id": { - "type": "string", - "description": "SKU ID.", - "example": "6" - }, - "quantity": { - "type": "integer", - "description": "Quantity of items of the SKU in the cart.", - "example": 1 - }, - "price": { - "type": "integer", - "description": "Price of the item.", - "example": 5500 - } - } - } - }, - "issuanceDate": { - "type": "string", - "description": "Issuance date.", - "example": "2021-05-21T10:00:00" - }, - "invoiceValue": { - "type": "integer", - "description": "Invoice value.", - "example": 6000 - } - } + "$ref": "#/components/schemas/requestSendInvoice" } } }, @@ -159,17 +54,10 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" } } } @@ -184,93 +72,30 @@ "External Seller" ], "summary": "Send tracking information", - "description": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.", + "description": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **Notify invoice** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "send-tracking-information", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "invoiceNumber", - "in": "path", - "description": "Invoice number.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "NFe-00002" - } + "$ref": "#/components/parameters/invoiceNumber" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { - "description": "", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "courier": { - "type": "string", - "description": "Courier.", - "example": "courier-example" - }, - "trackingNumber": { - "type": "string", - "description": "Tracking number.", - "example": "12345678abc" - }, - "trackingUrl": { - "type": "string", - "description": "Tracking URL.", - "example": "https://courier-example.com/tracking" - }, - "dispatchedDate": { - "type": "string", - "description": "Date of order dispatch.", - "example": "2021-06-09" - } - } + "$ref": "#/components/schemas/requestSendTracking" } } }, @@ -279,17 +104,10 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" } } } @@ -304,110 +122,31 @@ "External Seller" ], "summary": "Update tracking status", - "description": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.", + "description": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **Notify invoice** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "update-tracking-status", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "invoiceNumber", - "in": "path", - "description": "Invoice number.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "NFe-00002" - } + "$ref": "#/components/parameters/invoiceNumber" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { - "description": "", + "description": "Description of fields in the request body.", "content": { "application/json": { "schema": { - "type": "object", - "required": [ - "isDelivered" - ], - "properties": { - "isDelivered": { - "type": "boolean", - "description": "Indicates if order has been delivered. `false` if it is in transit.", - "example": true - }, - "events": { - "type": "array", - "description": "Array containing information on each tracking event received.", - "items": { - "type": "object", - "properties": { - "city": { - "type": "string", - "description": "City where the event ocurred.", - "example": "Rio de Janeiro" - }, - "state": { - "type": "string", - "description": "State where the event ocurred.", - "example": "Rio de Janeiro" - }, - "description": { - "type": "string", - "description": "Description of the event.", - "example": "Order delivered." - }, - "date": { - "type": "string", - "description": "Date when event ocurred.", - "example": "2021-03-16" - } - } - } - } - } + "$ref": "#/components/schemas/requestUpdateTrackingStatus" } } }, @@ -419,14 +158,8 @@ "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" } } } @@ -441,70 +174,28 @@ "External Seller" ], "summary": "Cancel order in marketplace", - "description": "This request is sent by the external seller to the VTEX marketplace to cancel an order.", + "description": "This request is sent by the external seller to the VTEX marketplace to cancel an order.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Order Cancellation** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Cancel Orders | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "cancel-order-in-marketplace", "parameters": [ { - "name": "marketplaceServicesEndpoint", - "in": "path", - "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "marketplaceservicesendpoint.myvtex.com" - } + "$ref": "#/components/parameters/marketplaceServicesEndpoint" }, { - "name": "marketplaceOrderId", - "in": "path", - "description": "Identifies the order in the marketplace.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "1138342255777-01" - } + "$ref": "#/components/parameters/marketplaceOrderId" }, { - "name": "Accept", - "in": "header", - "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Accept" }, { - "name": "Content-Type", - "in": "header", - "description": "Describes the type of the content being sent.", - "required": true, - "style": "simple", - "schema": { - "type": "string", - "example": "application/json" - } + "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { - "description": "", + "description": "Description of the request body field.", "content": { "application/json": { "schema": { - "type": "object", - "required": [ - "reason" - ], - "properties": { - "reason": { - "type": "string", - "description": "Insert here the reason for the order's cancellation.", - "example": "Product is unavailable" - } - } + "$ref": "#/components/schemas/requestCancelOrderMarketplace" } } }, @@ -513,17 +204,10 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { - "examples": { - "response": { - "value": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" - } - } + "schema": { + "$ref": "#/components/schemas/responseFulfill" } } } @@ -537,6 +221,9 @@ { "appKey": [], "appToken": [] + }, + { + "VtexIdclientAutCookie": [] } ], "components": { @@ -544,12 +231,299 @@ "appKey": { "type": "apiKey", "in": "header", - "name": "X-VTEX-API-AppKey" + "name": "X-VTEX-API-AppKey", + "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "appToken": { "type": "apiKey", "in": "header", - "name": "X-VTEX-API-AppToken" + "name": "X-VTEX-API-AppToken", + "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." + }, + "VtexIdclientAutCookie": { + "type": "apiKey", + "in": "header", + "name": "VtexIdclientAutCookie", + "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." + } + }, + "parameters": { + "Content-Type": { + "name": "Content-Type", + "in": "header", + "description": "Type of the content being sent.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "application/json" + } + }, + "Accept": { + "name": "Accept", + "in": "header", + "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "application/json" + } + }, + "marketplaceServicesEndpoint": { + "name": "marketplaceServicesEndpoint", + "in": "path", + "description": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "marketplaceservicesendpoint.myvtex.com" + } + }, + "marketplaceOrderId": { + "name": "marketplaceOrderId", + "in": "path", + "description": "Identifies the order in the marketplace.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "1138342255777-01" + } + }, + "invoiceNumber": { + "name": "invoiceNumber", + "in": "path", + "description": "Invoice number.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "NFe-00002" + } + } + }, + "schemas": { + "requestSendInvoice": { + "required": [ + "type", + "invoiceNumber", + "items" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.", + "example": "Output" + }, + "invoiceNumber": { + "type": "string", + "description": "Invoice number", + "example": "NFe-00002" + }, + "courier": { + "type": "string", + "description": "Courier, if available on invoice.", + "example": "courier-example" + }, + "trackingNumber": { + "type": "string", + "description": "Tracking number.", + "example": "12345678abc" + }, + "trackingUrl": { + "type": "string", + "description": "Tracking URL.", + "example": "https://courier-example.com/tracking" + }, + "items": { + "type": "array", + "description": "Array containing the order items.", + "items": { + "type": "object", + "description": "Specification data for each order item.", + "required": [ + "id", + "quantity", + "price" + ], + "properties": { + "id": { + "type": "string", + "description": "SKU ID.", + "example": "6" + }, + "quantity": { + "type": "integer", + "description": "Quantity of items of the SKU in the cart.", + "example": 1 + }, + "price": { + "type": "integer", + "description": "Price of the item.", + "example": 5500 + } + } + } + }, + "issuanceDate": { + "type": "string", + "description": "Issuance date.", + "example": "2021-05-21T10:00:00" + }, + "invoiceValue": { + "type": "integer", + "description": "Invoice value.", + "example": 6000 + } + }, + "example": { + "type": "Output", + "invoiceNumber": "NFe-00002", + "courier": "courier-example", + "trackingNumber": "12345678abc", + "trackingUrl": "https://courier-example.com/tracking", + "items": [ + { + "id": "6", + "quantity": 1, + "price": 5500 + } + ], + "issuanceDate": "2021-05-21T10:00:00", + "invoiceValue": 6000 + } + }, + "responseFulfill": { + "properties": { + "date": { + "type": "string", + "description": "Request processing date and time.", + "example": "2021-06-09T15:22:56.7612218-02:00" + }, + "orderId": { + "type": "string", + "description": "Order ID referring to the Invoice number sent.", + "example": "1138342255777-01" + }, + "receipt": { + "type": "string", + "description": "Requisition receipt code.", + "example": "527b1ae251264ef1b7a9b597cd8f16b9" + } + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" + } + }, + "requestSendTracking": { + "required": [ + "courier", + "trackingNumber", + "trackingUrl", + "dispatchedDate" + ], + "properties": { + "courier": { + "type": "string", + "description": "Courier.", + "example": "courier-example" + }, + "trackingNumber": { + "type": "string", + "description": "Tracking number.", + "example": "12345678abc" + }, + "trackingUrl": { + "type": "string", + "description": "Tracking URL.", + "example": "https://courier-example.com/tracking" + }, + "dispatchedDate": { + "type": "string", + "description": "Date of order dispatch.", + "example": "2021-06-09" + } + }, + "example": { + "courier": "courier-example", + "trackingNumber": "12345678abc", + "trackingUrl": "https://courier-example.com/tracking", + "dispatchedDate": "2021-06-09" + } + }, + "requestUpdateTrackingStatus": { + "type": "object", + "required": [ + "isDelivered" + ], + "properties": { + "isDelivered": { + "type": "boolean", + "description": "Indicates if order has been delivered. `false` if it is in transit.", + "example": true + }, + "events": { + "type": "array", + "description": "Array containing information on each tracking event received.", + "items": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "City where the event ocurred.", + "example": "Rio de Janeiro" + }, + "state": { + "type": "string", + "description": "State where the event ocurred.", + "example": "Rio de Janeiro" + }, + "description": { + "type": "string", + "description": "Description of the event.", + "example": "Order delivered." + }, + "date": { + "type": "string", + "description": "Date when event ocurred.", + "example": "2021-03-16" + } + } + } + } + }, + "example": { + "isDelivered": true, + "events": [ + { + "city": "Rio de Janeiro", + "state": "Rio de Janeiro", + "description": "Order delivered.", + "date": "2021-03-16" + } + ] + } + }, + "requestCancelOrderMarketplace": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "reason": { + "type": "string", + "description": "Insert here the reason for the order's cancellation.", + "example": "Product is unavailable." + } + }, + "example": { + "reason": "Product is unavailable." + } } } }, @@ -558,4 +532,4 @@ "name": "External Seller" } ] -} +} \ No newline at end of file From 4ebadd94f1f24eea9ab39cf3d7a10be161120252 Mon Sep 17 00:00:00 2001 From: anabaarbosa <> Date: Thu, 14 Dec 2023 16:52:38 +0000 Subject: [PATCH 2/8] Update generated files by portman --- ...rotocol - External Seller Marketplace.json | 100 +++++++++--------- 1 file changed, 52 insertions(+), 48 deletions(-) diff --git a/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json b/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json index d6deb4420..e3855a4ad 100644 --- a/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/PostmanCollections/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -1,10 +1,10 @@ { "_": { - "postman_id": "ea548ab7-0a34-4b85-aca6-fb65075655da" + "postman_id": "02752372-e668-4f32-9b9a-56bb96f5f9aa" }, "item": [ { - "id": "be99d402-44bd-40c0-9e6f-7c816a15dd42", + "id": "5e388ec1-2a8f-4f7a-b9e5-2852edc05cca", "name": "External Seller", "description": { "content": "", @@ -12,12 +12,12 @@ }, "item": [ { - "id": "1e6669be-8e49-4cc0-a4c6-1be9c333e4ec", + "id": "5d6bbd73-f16e-429e-93b8-2f580ee7ae28", "name": "Send invoice", "request": { "name": "Send invoice", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.", + "content": "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.3\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "type": "text/plain" }, "url": { @@ -35,22 +35,22 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "(Required) Identifies the order in the marketplace.", "type": "text/plain" }, "type": "any", - "value": "{{marketplaceServicesEndpoint}}", - "key": "marketplaceServicesEndpoint" + "value": "1138342255777-01", + "key": "marketplaceOrderId" }, { "disabled": false, "description": { - "content": "(Required) Identifies the order in the marketplace.", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", - "value": "1138342255777-01", - "key": "marketplaceOrderId" + "value": "{{marketplaceServicesEndpoint}}", + "key": "marketplaceServicesEndpoint" } ] }, @@ -80,7 +80,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "ac7ed4d4-39df-455a-ae86-790e77ba6320", + "id": "ebef224c-46ce-4b48-91ba-d15c41e17962", "name": "OK", "originalRequest": { "url": { @@ -98,22 +98,22 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "(Required) Identifies the order in the marketplace.", "type": "text/plain" }, "type": "any", - "value": "{{marketplaceServicesEndpoint}}", - "key": "marketplaceServicesEndpoint" + "value": "1138342255777-01", + "key": "marketplaceOrderId" }, { "disabled": false, "description": { - "content": "(Required) Identifies the order in the marketplace.", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", - "value": "1138342255777-01", - "key": "marketplaceOrderId" + "value": "{{marketplaceServicesEndpoint}}", + "key": "marketplaceServicesEndpoint" } ] }, @@ -138,7 +138,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -176,12 +176,13 @@ { "listen": "test", "script": { - "id": "d59f8909-6625-43d9-98e9-f9c9e2d676e2", + "id": "061d23b4-1b84-44b1-a732-cf1c2c221bdd", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -191,12 +192,12 @@ } }, { - "id": "f262b16c-7f72-47d7-ba99-413cc51cec64", + "id": "5766c16c-bf90-4d6a-b398-7156c3767b33", "name": "Send tracking information", "request": { "name": "Send tracking information", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.", + "content": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **Notify invoice** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "type": "text/plain" }, "url": { @@ -215,7 +216,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -270,7 +271,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "9050e56d-ecbd-4967-9ebb-bd07f39ae3c7", + "id": "c8d10502-5fb3-4a13-a0e5-fa733088b042", "name": "OK", "originalRequest": { "url": { @@ -289,7 +290,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -339,7 +340,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -377,12 +378,13 @@ { "listen": "test", "script": { - "id": "d7cfb4d1-cf45-4d64-a776-94be874c1f11", + "id": "11c5b244-9ff6-4e61-ab36-c467070a3f8a", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -392,12 +394,12 @@ } }, { - "id": "8bd276ca-a62d-43e5-89d7-a4589104138f", + "id": "d31827ff-f38d-45f7-9bd0-bd761fa1e226", "name": "Update tracking status", "request": { "name": "Update tracking status", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.", + "content": "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **Notify invoice** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "type": "text/plain" }, "url": { @@ -417,7 +419,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -459,7 +461,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{\n \"isDelivered\": true,\n \"events\": [\n {\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"description\": \"Order delivered.\",\n \"date\": \"2021-03-16\"\n },\n {\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"description\": \"Order delivered.\",\n \"date\": \"2021-03-16\"\n }\n ]\n}", + "raw": "{\n \"isDelivered\": true,\n \"events\": [\n {\n \"city\": \"Rio de Janeiro\",\n \"state\": \"Rio de Janeiro\",\n \"description\": \"Order delivered.\",\n \"date\": \"2021-03-16\"\n }\n ]\n}", "options": { "raw": { "language": "json" @@ -472,7 +474,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "1c9d50fb-a23d-41ce-8f5e-057e5027ea41", + "id": "6a48d3a3-7149-4a2f-9c9d-cd7dbae6e42f", "name": "OK", "originalRequest": { "url": { @@ -492,7 +494,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -542,7 +544,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -580,12 +582,13 @@ { "listen": "test", "script": { - "id": "2860bcaa-37fe-4940-8f44-52a160a32c1c", + "id": "657c2698-2b1d-4308-bf0e-5132ee61beb9", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/tracking - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -595,12 +598,12 @@ } }, { - "id": "577e1a3c-6995-4c91-ae1d-247fc0ac7960", + "id": "4f95492d-5366-4f41-af47-e37f6cda051c", "name": "Cancel order in marketplace", "request": { "name": "Cancel order in marketplace", "description": { - "content": "This request is sent by the external seller to the VTEX marketplace to cancel an order.", + "content": "This request is sent by the external seller to the VTEX marketplace to cancel an order.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Order Cancellation** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Cancel Orders | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "type": "text/plain" }, "url": { @@ -618,7 +621,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -650,7 +653,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{\n \"reason\": \"Product is unavailable\"\n}", + "raw": "{\n \"reason\": \"Product is unavailable.\"\n}", "options": { "raw": { "language": "json" @@ -663,7 +666,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "52019e41-0396-437b-9d66-72d7ef913a8c", + "id": "7a7784a8-832d-4c08-aa41-1c7214fc1303", "name": "OK", "originalRequest": { "url": { @@ -681,7 +684,7 @@ { "disabled": false, "description": { - "content": "(Required) This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", + "content": "This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).", "type": "text/plain" }, "type": "any", @@ -721,7 +724,7 @@ { "disabled": false, "description": { - "content": "(Required) Describes the type of the content being sent.", + "content": "(Required) Type of the content being sent.", "type": "text/plain" }, "key": "Content-Type", @@ -735,7 +738,7 @@ "method": "POST", "body": { "mode": "raw", - "raw": "{\n \"reason\": \"Product is unavailable\"\n}", + "raw": "{\n \"reason\": \"Product is unavailable.\"\n}", "options": { "raw": { "language": "json" @@ -759,12 +762,13 @@ { "listen": "test", "script": { - "id": "3532bd96-4ce9-4a16-ae07-28e84b49e989", + "id": "d2c7f745-189a-4e17-8873-48cc2b176e20", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", - "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n" + "// Validate if response has JSON Body \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", + "// Response Validation\nconst schema = {\"properties\":{\"date\":{\"type\":\"string\",\"description\":\"Request processing date and time.\",\"example\":\"2021-06-09T15:22:56.7612218-02:00\"},\"orderId\":{\"type\":\"string\",\"description\":\"Order ID referring to the Invoice number sent.\",\"example\":\"1138342255777-01\"},\"receipt\":{\"type\":\"string\",\"description\":\"Requisition receipt code.\",\"example\":\"527b1ae251264ef1b7a9b597cd8f16b9\"}},\"example\":{\"date\":\"2021-06-09T15:22:56.7612218-02:00\",\"orderId\":\"1138342255777-01\",\"receipt\":\"527b1ae251264ef1b7a9b597cd8f16b9\"},\"type\":\"object\"}\n\n// Validate if response matches JSON schema \npm.test(\"[POST]::/pvt/orders/:marketplaceOrderId/cancel - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -815,7 +819,7 @@ } ], "info": { - "_postman_id": "ea548ab7-0a34-4b85-aca6-fb65075655da", + "_postman_id": "02752372-e668-4f32-9b9a-56bb96f5f9aa", "name": "Marketplace Protocol", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { From 773e18b3524d516131ae639a61f4077a98a6496e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Thu, 14 Dec 2023 15:16:24 -0300 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Karen Krieger --- ...ace Protocol - External Seller Marketplace.json | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index f96ea07ac..267c9df58 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -41,7 +41,6 @@ } ], "requestBody": { - "description": "Description of fields and example of a request body.", "content": { "application/json": { "schema": { @@ -72,7 +71,7 @@ "External Seller" ], "summary": "Send tracking information", - "description": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **Notify invoice** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", + "description": "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **Notify invoice** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Allows you to report invoices (NF) and tracking data | Notify invoice |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "send-tracking-information", "parameters": [ { @@ -142,7 +141,6 @@ } ], "requestBody": { - "description": "Description of fields in the request body.", "content": { "application/json": { "schema": { @@ -155,7 +153,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "content": { "application/json": { "schema": { @@ -174,7 +171,7 @@ "External Seller" ], "summary": "Cancel order in marketplace", - "description": "This request is sent by the external seller to the VTEX marketplace to cancel an order.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Order Cancellation** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Cancel Orders | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", + "description": "This request is sent by the external seller to the VTEX marketplace to cancel an order.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Order Cancellation** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Cancel Orders | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "cancel-order-in-marketplace", "parameters": [ { @@ -191,7 +188,6 @@ } ], "requestBody": { - "description": "Description of the request body field.", "content": { "application/json": { "schema": { @@ -256,7 +252,7 @@ "style": "simple", "schema": { "type": "string", - "example": "application/json" + "default": "application/json" } }, "Accept": { @@ -267,7 +263,7 @@ "style": "simple", "schema": { "type": "string", - "example": "application/json" + "default": "application/json" } }, "marketplaceServicesEndpoint": { @@ -320,7 +316,7 @@ }, "invoiceNumber": { "type": "string", - "description": "Invoice number", + "description": "Invoice number.", "example": "NFe-00002" }, "courier": { From 3403d0792a58f0804fc7b7214f0ee35ece6ff1fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Thu, 14 Dec 2023 16:30:15 -0300 Subject: [PATCH 4/8] Update VTEX - Marketplace Protocol - External Seller Marketplace.json --- ...ce Protocol - External Seller Marketplace.json | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index 267c9df58..9afa7383d 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -159,6 +159,11 @@ "$ref": "#/components/schemas/responseFulfill" } } + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } }, @@ -396,18 +401,15 @@ "properties": { "date": { "type": "string", - "description": "Request processing date and time.", - "example": "2021-06-09T15:22:56.7612218-02:00" + "description": "Request processing date and time." }, "orderId": { "type": "string", - "description": "Order ID referring to the Invoice number sent.", - "example": "1138342255777-01" + "description": "Order ID referring to the Invoice number sent." }, "receipt": { "type": "string", - "description": "Requisition receipt code.", - "example": "527b1ae251264ef1b7a9b597cd8f16b9" + "description": "Requisition receipt code." } }, "example": { @@ -468,6 +470,7 @@ "description": "Array containing information on each tracking event received.", "items": { "type": "object", + "description": "Description of tracking event fields.", "properties": { "city": { "type": "string", From c29e595ba86293c45a7b15951e40d3eda083d484 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Thu, 14 Dec 2023 17:39:39 -0300 Subject: [PATCH 5/8] Updates Spectral errors --- ...rotocol - External Seller Marketplace.json | 97 ++++++++++--------- 1 file changed, 49 insertions(+), 48 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index 9afa7383d..70a64d4e0 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -57,6 +57,11 @@ "application/json": { "schema": { "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } @@ -95,6 +100,12 @@ "application/json": { "schema": { "$ref": "#/components/schemas/requestSendTracking" + }, + "example": { + "courier": "courier-example", + "trackingNumber": "12345678abc", + "trackingUrl": "https://courier-example.com/tracking", + "dispatchedDate": "2021-06-09" } } }, @@ -107,12 +118,17 @@ "application/json": { "schema": { "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } - } - }, - "deprecated": false + }, + "deprecated": false + } } }, "/pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}/tracking": { @@ -157,13 +173,13 @@ "application/json": { "schema": { "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } - }, - "example": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } }, @@ -209,6 +225,11 @@ "application/json": { "schema": { "$ref": "#/components/schemas/responseFulfill" + }, + "example": { + "date": "2021-06-09T15:22:56.7612218-02:00", + "orderId": "1138342255777-01", + "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } } } @@ -316,28 +337,23 @@ "properties": { "type": { "type": "string", - "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.", - "example": "Output" + "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns." }, "invoiceNumber": { "type": "string", - "description": "Invoice number.", - "example": "NFe-00002" + "description": "Invoice number." }, "courier": { "type": "string", - "description": "Courier, if available on invoice.", - "example": "courier-example" + "description": "Courier, if available on invoice." }, "trackingNumber": { "type": "string", - "description": "Tracking number.", - "example": "12345678abc" + "description": "Tracking number." }, "trackingUrl": { "type": "string", - "description": "Tracking URL.", - "example": "https://courier-example.com/tracking" + "description": "Tracking URL." }, "items": { "type": "array", @@ -353,31 +369,26 @@ "properties": { "id": { "type": "string", - "description": "SKU ID.", - "example": "6" + "description": "SKU ID." }, "quantity": { "type": "integer", - "description": "Quantity of items of the SKU in the cart.", - "example": 1 + "description": "Quantity of items of the SKU in the cart." }, "price": { "type": "integer", - "description": "Price of the item.", - "example": 5500 + "description": "Price of the item." } } } }, "issuanceDate": { "type": "string", - "description": "Issuance date.", - "example": "2021-05-21T10:00:00" + "description": "Issuance date." }, "invoiceValue": { "type": "integer", - "description": "Invoice value.", - "example": 6000 + "description": "Invoice value." } }, "example": { @@ -428,23 +439,19 @@ "properties": { "courier": { "type": "string", - "description": "Courier.", - "example": "courier-example" + "description": "Courier." }, "trackingNumber": { "type": "string", - "description": "Tracking number.", - "example": "12345678abc" + "description": "Tracking number." }, "trackingUrl": { "type": "string", - "description": "Tracking URL.", - "example": "https://courier-example.com/tracking" + "description": "Tracking URL." }, "dispatchedDate": { "type": "string", - "description": "Date of order dispatch.", - "example": "2021-06-09" + "description": "Date of order dispatch." } }, "example": { @@ -462,8 +469,7 @@ "properties": { "isDelivered": { "type": "boolean", - "description": "Indicates if order has been delivered. `false` if it is in transit.", - "example": true + "description": "Indicates if order has been delivered. `false` if it is in transit." }, "events": { "type": "array", @@ -474,23 +480,19 @@ "properties": { "city": { "type": "string", - "description": "City where the event ocurred.", - "example": "Rio de Janeiro" + "description": "City where the event ocurred." }, "state": { "type": "string", - "description": "State where the event ocurred.", - "example": "Rio de Janeiro" + "description": "State where the event ocurred." }, "description": { "type": "string", - "description": "Description of the event.", - "example": "Order delivered." + "description": "Description of the event." }, "date": { "type": "string", - "description": "Date when event ocurred.", - "example": "2021-03-16" + "description": "Date when event ocurred." } } } @@ -516,8 +518,7 @@ "properties": { "reason": { "type": "string", - "description": "Insert here the reason for the order's cancellation.", - "example": "Product is unavailable." + "description": "Insert here the reason for the order's cancellation." } }, "example": { From 39ac3ae7010add749bf123f50fad325ffa7e0736 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Thu, 14 Dec 2023 18:10:09 -0300 Subject: [PATCH 6/8] Update VTEX - Marketplace Protocol - External Seller Marketplace.json --- ...rotocol - External Seller Marketplace.json | 43 ++++++++++++------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index 70a64d4e0..77e0a65ea 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -126,9 +126,9 @@ } } } - }, + } + }, "deprecated": false - } } }, "/pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}/tracking": { @@ -337,23 +337,28 @@ "properties": { "type": { "type": "string", - "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns." + "description": "Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.", + "example":"Output" }, "invoiceNumber": { "type": "string", - "description": "Invoice number." + "description": "Invoice number.", + "example":"NFe-00002" }, "courier": { "type": "string", - "description": "Courier, if available on invoice." + "description": "Courier, if available on invoice.", + "example":"courier-example" }, "trackingNumber": { "type": "string", - "description": "Tracking number." + "description": "Tracking number.", + "example":"12345678abc" }, "trackingUrl": { "type": "string", - "description": "Tracking URL." + "description": "Tracking URL.", + "example": "https://courier-example.com/tracking" }, "items": { "type": "array", @@ -384,11 +389,13 @@ }, "issuanceDate": { "type": "string", - "description": "Issuance date." + "description": "Issuance date.", + "example": "2021-05-21T10:00:00" }, "invoiceValue": { "type": "integer", - "description": "Invoice value." + "description": "Invoice value.", + "example": 6000 } }, "example": { @@ -439,19 +446,23 @@ "properties": { "courier": { "type": "string", - "description": "Courier." + "description": "Courier.", + "example":"courier-example" }, "trackingNumber": { "type": "string", - "description": "Tracking number." + "description": "Tracking number.", + "example": "12345678abc" }, "trackingUrl": { "type": "string", - "description": "Tracking URL." + "description": "Tracking URL.", + "example": "https://courier-example.com/tracking" }, "dispatchedDate": { "type": "string", - "description": "Date of order dispatch." + "description": "Date of order dispatch.", + "example":"2021-06-09" } }, "example": { @@ -469,7 +480,8 @@ "properties": { "isDelivered": { "type": "boolean", - "description": "Indicates if order has been delivered. `false` if it is in transit." + "description": "Indicates if order has been delivered. `false` if it is in transit.", + "example": true }, "events": { "type": "array", @@ -518,7 +530,8 @@ "properties": { "reason": { "type": "string", - "description": "Insert here the reason for the order's cancellation." + "description": "Insert here the reason for the order's cancellation.", + "example": "Product is unavailable." } }, "example": { From a8135713a1847506d67cc2fff6fa86776cef8b64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Thu, 14 Dec 2023 18:20:01 -0300 Subject: [PATCH 7/8] Update VTEX - Marketplace Protocol - External Seller Marketplace.json --- ...rotocol - External Seller Marketplace.json | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index 77e0a65ea..99653db56 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -374,15 +374,18 @@ "properties": { "id": { "type": "string", - "description": "SKU ID." + "description": "SKU ID.", + "example": "6" }, "quantity": { "type": "integer", - "description": "Quantity of items of the SKU in the cart." + "description": "Quantity of items of the SKU in the cart.", + "example": 1 }, "price": { "type": "integer", - "description": "Price of the item." + "description": "Price of the item.", + "example": 5500 } } } @@ -492,19 +495,23 @@ "properties": { "city": { "type": "string", - "description": "City where the event ocurred." + "description": "City where the event ocurred.", + "example": "Rio de Janeiro" }, "state": { "type": "string", - "description": "State where the event ocurred." + "description": "State where the event ocurred.", + "example": "Rio de Janeiro" }, "description": { "type": "string", - "description": "Description of the event." + "description": "Description of the event.", + "example": "Order delivered." }, "date": { "type": "string", - "description": "Date when event ocurred." + "description": "Date when event ocurred.", + "example": "2021-03-16" } } } From 29e92e68e203d78f5896c04333a288a525da66dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Patr=C3=ADcia=20F=2E=20Barbosa?= Date: Tue, 19 Dec 2023 10:40:05 -0300 Subject: [PATCH 8/8] Update VTEX - Marketplace Protocol - External Seller Marketplace.json --- ...rotocol - External Seller Marketplace.json | 52 +++---------------- 1 file changed, 7 insertions(+), 45 deletions(-) diff --git a/VTEX - Marketplace Protocol - External Seller Marketplace.json b/VTEX - Marketplace Protocol - External Seller Marketplace.json index 99653db56..fc2247cf4 100644 --- a/VTEX - Marketplace Protocol - External Seller Marketplace.json +++ b/VTEX - Marketplace Protocol - External Seller Marketplace.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Marketplace Protocol", - "description": "\r\nThe _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", + "description": "The _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", "version": "1.0" }, "servers": [ @@ -400,43 +400,25 @@ "description": "Invoice value.", "example": 6000 } - }, - "example": { - "type": "Output", - "invoiceNumber": "NFe-00002", - "courier": "courier-example", - "trackingNumber": "12345678abc", - "trackingUrl": "https://courier-example.com/tracking", - "items": [ - { - "id": "6", - "quantity": 1, - "price": 5500 - } - ], - "issuanceDate": "2021-05-21T10:00:00", - "invoiceValue": 6000 } }, "responseFulfill": { "properties": { "date": { "type": "string", - "description": "Request processing date and time." + "description": "Request processing date and time.", + "example":"2021-06-09T15:22:56.7612218-02:00" }, "orderId": { "type": "string", - "description": "Order ID referring to the Invoice number sent." + "description": "Order ID referring to the Invoice number sent.", + "example": "1138342255777-01" }, "receipt": { "type": "string", - "description": "Requisition receipt code." + "description": "Requisition receipt code.", + "example": "527b1ae251264ef1b7a9b597cd8f16b9" } - }, - "example": { - "date": "2021-06-09T15:22:56.7612218-02:00", - "orderId": "1138342255777-01", - "receipt": "527b1ae251264ef1b7a9b597cd8f16b9" } }, "requestSendTracking": { @@ -467,12 +449,6 @@ "description": "Date of order dispatch.", "example":"2021-06-09" } - }, - "example": { - "courier": "courier-example", - "trackingNumber": "12345678abc", - "trackingUrl": "https://courier-example.com/tracking", - "dispatchedDate": "2021-06-09" } }, "requestUpdateTrackingStatus": { @@ -516,17 +492,6 @@ } } } - }, - "example": { - "isDelivered": true, - "events": [ - { - "city": "Rio de Janeiro", - "state": "Rio de Janeiro", - "description": "Order delivered.", - "date": "2021-03-16" - } - ] } }, "requestCancelOrderMarketplace": { @@ -540,9 +505,6 @@ "description": "Insert here the reason for the order's cancellation.", "example": "Product is unavailable." } - }, - "example": { - "reason": "Product is unavailable." } } }