From d9badf009accfdb123db72de25fdc72c815fa8dd Mon Sep 17 00:00:00 2001 From: Carolina Menezes Date: Fri, 27 Oct 2023 19:53:42 -0300 Subject: [PATCH 01/11] add: creating-a-regular-order-with-the-checkout-api --- ...-a-regular-order-with-the-checkout-api.mdx | 1058 +++++++++++++++++ 1 file changed, 1058 insertions(+) create mode 100644 docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx diff --git a/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx b/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx new file mode 100644 index 0000000000..dae4677ebd --- /dev/null +++ b/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx @@ -0,0 +1,1058 @@ +--- +title: "Creating a regular order with the Checkout API" +slug: "creating-a-regular-order-with-the-checkout-api" +hidden: false +createdAt: "2023-07-18T17:08:52.219Z" +updatedAt: "2023-07-18T17:08:52.219Z" +excerpt: "Learn how to use VTEX APIs to efficiently handle the placement, payment, and delivery aspects of a regular order." +hideTOC: true +--- + +This step-by-step guide will walk you through the process of using the [Checkout API](https://developers.vtex.com/docs/api-reference/checkout-api) for handling the placement, payment, and delivery aspects of a regular order, with all responsibilities managed within the scope of a single account. This process is divided into the following steps + +1. **Assess cart requirements:** The process begins with the simulation of a cart to assess available delivery and payment options. Additionally, since indicating an email address is necessary to place an order, this step also includes verifying the existence of a customer by cross-referencing their email address in the database. +2. **Assemble the cart:** After assessing the cart requirements, the next step is to assemble the cart, ensuring that all essential order information is organized accurately under the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) object. +3. **Handle the order:** This step involves placing the order on the VTEX platform and sending the necessary payment data to resolve the order payment. +4. **Processing and validating the order:** The process ends by processing order details and conducting a verification procedure to confirm the successful placement of the order. + + + + + +```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43] +curl --request post \ + --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/orderForms/simulation?RnbBehavior=0' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' \ + --data '{"items":[{"id":"1","quantity":1,"seller":"1"}],"country":"BRA","postalCode":"12345-000","geoCoordinates":[-47.924747467041016]}' +``` + +```python Python +import http.client + +conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") + +payload = "{\"items\":[{\"id\":\"1\",\"quantity\":1,\"seller\":\"1\"}],\"country\":\"BRA\",\"postalCode\":\"12345-000\",\"geoCoordinates\":[-47.924747467041016]}" + +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "", + 'X-VTEX-API-AppToken': "" + } + +conn.request("post", "/api/checkout/pub/orderForms/simulation?RnbBehavior=0", payload, headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) +``` + +```js Node.js mark=5[15:27],5[29:41] +const http = require("https"); + +const options = { + "method": "post", + "hostname": "{accountname}.{environment}.com.br", + "port": null, + "path": "/api/checkout/pub/orderForms/simulation?RnbBehavior=0", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "", + "X-VTEX-API-AppToken": "" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.write(JSON.stringify({ + items: [{id: '1', quantity: 1, seller: '1'}], + country: 'BRA', + postalCode: '12345-000', + geoCoordinates: [-47.924747467041016] +})); +req.end(); +``` + +```json Response +{ + "allowManualPrice": boolean, + "canEditData": boolean, + "clientPreferencesData": {}, + "clientProfileData": {}, + "commercialConditionData": {}, + "customData": {}, + "giftRegistryData": {}, + "hooksData": {}, + "ignoreProfileData": boolean, + "isCheckedIn": boolean, + "itemMetadata": {}, + "items": [], + "itemsOrdination": {}, + "loggedIn": boolean, + "marketingData": {}, + "messages": [], + "openTextField": {}, + "orderFormId": string, + "paymentData": {}, + "ratesAndBenefitsData": {}, + "salesChannel": string, + "selectableGifts": [], + "sellers": {}, + "shippingData": {}, + "storeId": {}, + "storePreferencesData": {}, + "totalizers": {}, + "userProfileId": {}, + "userType": {}, + "value": number +} +``` + +```json orderForm.json +{ + "allowManualPrice": boolean, + "canEditData": boolean, + "clientPreferencesData": {}, + "clientProfileData": {}, + "commercialConditionData": {}, + "customData": {}, + "giftRegistryData": {}, + "hooksData": {}, + "ignoreProfileData": boolean, + "isCheckedIn": boolean, + "itemMetadata": {}, + "items": {}, + "itemsOrdination": {}, + "loggedIn": boolean, + "marketingData": {}, + "messages": [], + "openTextField": {}, + "orderFormId": string, + "paymentData": {}, + "ratesAndBenefitsData": {}, + "salesChannel": "1", + "selectableGifts": {}, + "sellers": {}, + "shippingData": {}, + "storeId": {}, + "storePreferencesData": {}, + "totalizers": {}, + "userProfileId": {}, + "userType": {}, + "value": number +} +``` + + + +## Before you begin + +Before proceeding any further, ensure that you have a valid `appKey` and `appToken` granted with the necessary permissions to access the Checkout and Payments Gateway APIs. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. + +> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. + +--- + +## Step 1 - Assessing cart requirements + +In this step, we will verify if your store can fulfill the cart requirements and gather essential order information to ensure a smooth order placement process in the subsequent steps. + +### Simulating a cart + +This step provides essential information regarding the available delivery and payment options for the specific combination of items in the cart. + +- Send a request to the [`Cart simulation`](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForms/simulation) API endpoint. Specify the SKU ID (`items.id`), the number of items in the cart (`items.quantity`), and the Seller's ID (`items.seller`) in the request body. +- Take note of the `items`, `shippingData.logisticsInfo`, and `paymentData` objects, as we will use this data in the following steps. + + + +```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43] +``` + +```python Python mark=3[37:49],3[51:63] +``` + +```js Node.js mark=5[15:27],5[29:41] +``` + +--- + +```json Response mark=13,20,25 +``` + + + +--- + +### Checking for existing customer + +This step verifies if the email used to place the order is already related to a customer in your database. This verification serves to not only enhance operational efficiency but also proactively prevent potential permission-related issues. + +- Send a request to the [`Get client by email`](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles) endpoint to check for existing profiles associated with a specific email address. If the response to this request returns any content, it means the shopper’s information is in your database. In such cases, you can proceed using this data in subsequent steps, sparing the shopper from the need to provide their email again. +- If applicable, take note of the `availableAddresses` and `userProfile` objects, as we will use this data in the following steps. + + + +```shell Shell mark=2[18:30],2[32:44],2[85:98],5[32:39],6[34:43] +curl --request get \ + --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/profiles?email={emailAddress}' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' +``` + +```python Python mark=3[37:49],3[51:63] +import http.client + +conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") + +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "", + 'X-VTEX-API-AppToken': "" + } + +conn.request("get", "/api/checkout/pub/profiles?email={emailAddress}", headers=headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) +``` + +```js Node.js mark=5[15:27],5[29:41] +const http = require("https"); + +const options = { + "method": "get", + "hostname": "{accountname}.{environment}.com.br", + "port": null, + "path": "/api/checkout/pub/profiles?email={emailAddress}", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "", + "X-VTEX-API-AppToken": "" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.end(); +``` + +--- + +```json Response mark=6:20,24:35 +{ + "userProfileId": string, + "profileProvider": string, + "availableAccounts": [], + "availableAddresses": [ + { + "addressType": string, + "receiverName": string, + "addressId": string, + "isDisposable": boolean, + "postalCode": string, + "city": string, + "state": string, + "country": string, + "street": string, + "number": string, + "neighborhood": string, + "complement": null, + "reference": null, + "geoCoordinates": [] + } + ], + "userProfile": { + "email": string, + "firstName": string, + "lastName": string, + "document": string, + "documentType": string, + "phone": string, + "corporateName": null, + "tradeName": null, + "corporateDocument": null, + "stateInscription": null, + "corporatePhone": null, + "isCorporate": boolean, + "profileCompleteOnLoading": null, + "profileErrorOnLoading": null, + "customerClass": null + }, + "isComplete": boolean +} +``` + + + +--- + +## Step 2 - Assembling the cart + +In this step, we will arrange the order details into the specified data format, following the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) data structure. This formatted cart data will be used as the request body in the following steps. + +Below, we will briefly examine the key elements that make up the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields), which include: + +- `items` +- `clientProfileData` +- `shippingData.address` +- `shippingData.logisticsInfo` +- `paymentData` + +Note that while an `orderForm` can have various elements, a standard order typically consists of the abovementioned ones. + + + +```json orderForm.json focus=5,13,25,20 +``` + + + +--- + +### `items` + +`items` is an array that contains all data pertinent to the SKUs being purchased. Build the `items` array using the `items` array obtained from the [Simulating a cart](#simulating-a-cart) step. For more complex examples, see the [Place order](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) API reference. + + + +```json orderForm.json focus=2:9 +{ + "items": [ + { + "id": "1", + "quantity": 1, + "seller": "1", + "price": 10000 + } + ], + "clientProfileData": {}, + "shippingData": { + "address": {}, + "logisticsInfo": [] + }, + "paymentData": {} +} +``` + + + +--- + +### `clientProfileData`: New customers + +`clientProfileData` is an object that contains information about the customer. If you noted the customer does not exist in your database during the [Checking for existing customer](#checking-for-existing-customer) step, build the `clientProfileData` object with the data of the new customer willing to place the order. + + + +```json orderForm.json focus=3:16 +{ + "items": [], + "clientProfileData": { + "email": "email@domain.com", + "firstName": "First name", + "lastName": "Last name", + "document": "078051120", + "documentType": "ssn", + "phone": "1234567890", + "corporateName": null, + "tradeName": null, + "corporateDocument": null, + "stateInscription": null, + "corporatePhone": null, + "isCorporate": false + }, + "shippingData": { + "address": {}, + "logisticsInfo": [] + }, + "paymentData": {} +} +``` + + + +--- + +### `clientProfileData`: Existing customers + +If the customer already exists in your database, use the `userProfile.email` obtained in the [Checking for existing customer](#checking-for-existing-customer) step to build the `clientProfileData` object. Note that the email address is enough to register the order to the shopper’s existing account. + + + +```json orderForm.json focus=3:5 +{ + "items": [], + "clientProfileData": { + "email": "email@domain.com" + }, + "shippingData": { + "address": {}, + "logisticsInfo": [] + }, + "paymentData": {} +} +``` + + + +--- + +### `shippingData.address`: New customers + +`shippingData.address` is an object that contains information about the shipping address. If you noted the customer does not exist in your database during the [Checking for existing customer](#checking-for-existing-customer) step, build the `shippingData.address` object with the data of the new customer willing to place the order. + + + +```json orderForm.json focus=4:19 +{ + "items": [], + "clientProfileData": {}, + "shippingData": { + "address": { + "addressType": "residential", + "receiverName": "Testing VTEX", + "postalCode": "33301", + "city": "Fort Lauderdale", + "state": "FL", + "country": "USA", + "street": "110 East Broward Blvd", + "number": null, + "neighborhood": null, + "complement": "Suite 1700", + "reference": null, + "geoCoordinates": [] + } + }, + "paymentData": {} +} +``` + + + +--- + +### `shippingData.address`: Existing customers + +If the customer already exists in your database, use the desired `addressId` obtained from the [Checking for existing customer](#checking-for-existing-customer) step to build the `shippingData.address` block. + + + +```json orderForm.json focus=4:8 +{ + "items": [], + "clientProfileData": {}, + "shippingAddress": { + "address": { + "addressId": "666c2e830bd9474ab6f6cc53fb6dd2d2" + } + }, + "paymentData": {} +} +``` + + + +--- + +### `shippingData.logisticsInfo` + +`logisticsInfo` is an array that contains logistics information, such as the desired delivery option and freight cost for each item in the `items` array. + +- Create the `logisticsInfo` array with the same number of objects as in the `items` array. For each object within the `logisticsInfo` array, define the following elements: + + - `itemIndex` - index of the corresponding item in the `items` array. For example, the object referring to the first item in the `items` array has an `itemIndex` of `0`. + - `selectedSla` - desired delivery option. You can find the `id` value of the available options in the `slas` array obtained from the [Simulating a cart](#simulating-a-cart) step. + - `price` - price of the item. You can retrieve this value from the [Simulating a cart](#simulating-a-cart) step. + - (Optional) If the delivery method is pickup point, add the information `"selectedDeliveryChannel": "pickup-in-point"`. + + + +```json orderForm.json focus=4:14 +{ + "items": [], + "clientProfileData": {}, + "shippingData": { + "address": {}, + "logisticsInfo": [ + { + "itemIndex": 0, + "selectedSla": "Regular", + "price": 100, + "selectedDeliveryChannel": "pickup-in-point" + } + ] + }, + "paymentData": {} +} +``` + + + +--- + +### `paymentData.payments` + +`paymentData.payments` is an array that contains information regarding the chosen payment method and installment preferences for the order. Build the `paymentData.payments` array considering the response obtained from the [Simulating a cart](#simulating-a-cart) step. For each payment option, define the following elements: + +- `paymentSystem` - ID of the desired payment system. +- `referenceValue` - reference value used to calculate interest rates. If no interest applies to the order, the `value` and `referenceValue` should be the same. +- `value` - total amount to be paid by the shopper. +- `installments` - number of installments. + +For more complex examples, see the [Place order](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) API reference. + + + +```json orderForm.json focus=8:17 +{ + "items": [], + "clientProfileData": {}, + "shippingData": { + "address": {}, + "logisticsInfo": [] + }, + "paymentData": { + "payments": [ + { + "paymentSystem": "1", + "referenceValue": 10100, + "value": 10100, + "installments": 1 + } + ] + } +} +``` + + + +--- + +## Step 3 - Handling the order + +In this step, we will use the `orderForm` we built in the previous steps to place an order on the VTEX platform. + +### Reviewing the `orderForm` of a new customer + +After building the `orderForm` for your order, ensure it adheres to a valid JSON format. For new customers, your `orderForm` should resemble this structure. + + + +```json orderForm.json +{ + "items": [ + { + "id": "1", + "quantity": 1, + "seller": "1", + "price": 10000 + } + ], + "clientProfileData": { + "email": "email@domain.com", + "firstName": "Testing", + "lastName": "VTEX", + "document": "078051120", + "documentType": "ssn", + "phone": "1234567890", + "corporateName": null, + "tradeName": null, + "corporateDocument": null, + "stateInscription": null, + "corporatePhone": null, + "isCorporate": false + }, + "shippingData": { + "address": { + "addressType": "residential", + "receiverName": "Testing VTEX", + "postalCode": "33301", + "city": "Fort Lauderdale", + "state": "FL", + "country": "USA", + "street": "110 East Broward Blvd", + "number": null, + "neighborhood": null, + "complement": "Suite 1700", + "reference": null, + "geoCoordinates": [] + }, + "logisticsInfo": [ + { + "itemIndex": 0, + "selectedSla": "Regular", + "price": 100 + } + ] + }, + "paymentData": { + "payments": [ + { + "paymentSystem": "1", + "referenceValue": 10100, + "value": 10100, + "installments": 1 + } + ] + } +} +``` + + + +--- + +### Reviewing the `orderForm` of an existing customer + +For returning customers, the `orderForm` for your order should resemble this structure. + + + +```json orderForm.json +{ + "items": [ + { + "id": "1", + "quantity": 1, + "seller": "1", + "price": 10000 + } + ], + "clientProfileData": { + "email": "email@domain.com" + }, + "shippingData": { + "address": { + "addressId": "666c2e830bd9474ab6f6cc53fb6dd2d2" + }, + "logisticsInfo": [ + { + "itemIndex": 0, + "selectedSla": "Regular", + "price": 100 + } + ] + }, + "paymentData": { + "payments": [ + { + "paymentSystem": "1", + "referenceValue": 10100, + "value": 10100, + "installments": 1 + } + ] + } +} +``` + + + +--- + +### Placing the order + +Send a request to the [`Place order`](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) endpoint, using the `orderForm` you built as the request body. + +Upon receiving a `201 Created` response, take note of these four pieces of information: + +- `orderId` - ID of the order within VTEX’s Order Management System (OMS). You can find the `orderId` within each object in the `orders` array. +- `transactionId` - ID of the transaction, which can be found within the objects contained in the `transactionData.merchantTransactions` array. +- `addressId` - ID of the customer address. If you plan to use the same address for both shipping and billing, get the `addressId` from the `orders[].shippingData.address` object. +- `Vtex_CHKO_Auth` - authentication cookie provided in the response. + +>❗ If you are using an email from an existing customer, ensure that the corresponding customer account is logged into your store. Otherwise, the process will fail. + + + +```shell Shell mark=2[17:29],2[31:43] +curl --request put \ + --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/orders' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: ' \ + --header 'X-VTEX-API-AppToken: ' \ + --data 'YOUR_ORDERFORM' +``` + +```python Python mark=3[37:49],3[51:63] +import http.client + +conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") + +payload = "YOUR_ORDERFORM" + +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "", + 'X-VTEX-API-AppToken': "" + } + +conn.request("put", "/api/checkout/pub/orders", payload, headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) +``` + +```js Node.js mark=5[15:27],5[29:41] +const http = require("https"); + +const options = { + "method": "put", + "hostname": "{accountname}.{environment}.com.br", + "port": null, + "path": "/api/checkout/pub/orders", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "", + "X-VTEX-API-AppToken": "" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.write(JSON.stringify(YOUR_ORDERFORM)); +req.end(); +``` + +--- + +```json Response mark=7,18,29 +{ + "orderForm": null, + "transactionData": { + "merchantTransactions": [ + { + "id": string, + "transactionId": string, + "merchantName": string, + "payments": [], + "transactionId": string, + } + ], + "receiverUri": string, + "gatewayCallbackTemplatePath": string + }, + "orders": [ + { + "orderId": string, + "orderGroup": string, + "state": null, + "isCheckedIn": boolean, + "sellerOrderId": string, + "storeId": null, + "checkedInPickupPointId": null, + "value": number, + "items": [], + "shippingData": { + "address": { + "addressId": string + } + }, + "paymentData": {}, + "clientPreferencesData": null, + "commercialConditionData": null, + "giftRegistryData": null, + "marketingData": null, + "storePreferencesData": {}, + "openTextField": {}, + "invoiceData": null, + "itemMetadata": {}, + "taxData": null, + "customData": null, + "hooksData": null, + "changeData": null, + "subscriptionData": null, + "salesChannel": string, + "followUpEmail": string, + "creationDate": string, + "lastChange": string, + "timeZoneCreationDate": string, + "timeZoneLastChange": string, + "isCompleted": boolean, + "hostName": string, + "merchantName": null, + "userType": string, + "roundingError": number, + "allowEdition": boolean, + "allowCancellation": boolean, + "isUserDataVisible": boolean, + "allowChangeSeller": boolean, + "orderFormCreationDate": string, + } + ], + "salesAssociateData": {} +} +``` + + + +--- + +### Resolving the order payment + +In this step, we will communicate the necessary payment data to VTEX for the finalization of the order's payment. + +>❗ Starting from the moment the order is placed, you have a window of five minutes to complete the payment process. Failure to do so will result in automatic cancellation, and the order will be labeled as "incomplete." + +- Send a request to the [Send payments information public](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pub/transactions/-transactionId-/payments) endpoint, considering the following: + + - Use the `orderId` value obtained in the previous step as the `orderId` query-string parameter. + - Use the `transactionId` value obtained in the previous step as a path parameter. + - Ensure that the request body is based on the `paymentData` section of your `orderForm`. + - In the `fields` object, use the `addressId` field to reference an existing address or introduce a new `address` object for an entirely new address. + +> If you intend to send saved credit card data, you can use the [Send payments with saved credit card](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/payments) endpoint instead. + + + +```shell Shell mark=2[17:29],2[31:43] +curl --request post \ + --url 'https://apiexamples.vtexpayments.com.br/api/pub/transactions/{{transactionId}}/payments?orderId={{orderId}}' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: ' \ + --header 'X-VTEX-API-AppToken: ' \ + --data '[{"paymentSystem":4,"installments":1,"currencyCode":"BRL","value":100,"installmentsInterestRate":0,"installmentsValue":100,"referenceValue":100,"fields":{"holderName":"UserTest","cardNumber":"5378244888889174","validationCode":"231","dueDate":"10/19","document":"8041734561","accountId":"","address":null,"callbackUrl":""},"transaction":{"id":"{{transactionId}}","merchantName":"{{accountName}}"}}]' +``` + +```python Python mark=3[37:49],3[51:63] +import http.client + +conn = http.client.HTTPSConnection("apiexamples.vtexpayments.com.br") + +payload = "[{\"paymentSystem\":4,\"installments\":1,\"currencyCode\":\"BRL\",\"value\":100,\"installmentsInterestRate\":0,\"installmentsValue\":100,\"referenceValue\":100,\"fields\":{\"holderName\":\"UserTest\",\"cardNumber\":\"5378244888889174\",\"validationCode\":\"231\",\"dueDate\":\"10/19\",\"document\":\"8041734561\",\"accountId\":\"\",\"address\":null,\"callbackUrl\":\"\"},\"transaction\":{\"id\":\"{{transactionId}}\",\"merchantName\":\"{{accountName}}\"}}]" + +headers = { + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "", + 'X-VTEX-API-AppToken': "" + } + +conn.request("post", "/api/pub/transactions/%7B%7BtransactionId%7D%7D/payments?orderId=%7B%7BorderId%7D%7D", payload, headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) +``` + +```js Node.js mark=5[15:27],5[29:41] +const http = require("https"); + +const options = { + "method": "post", + "hostname": "apiexamples.vtexpayments.com.br", + "port": null, + "path": "/api/pub/transactions/%7B%7BtransactionId%7D%7D/payments?orderId=%7B%7BorderId%7D%7D", + "headers": { + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "", + "X-VTEX-API-AppToken": "" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.write(JSON.stringify([ + { + paymentSystem: 4, + installments: 1, + currencyCode: 'BRL', + value: 100, + installmentsInterestRate: 0, + installmentsValue: 100, + referenceValue: 100, + fields: { + holderName: 'UserTest', + cardNumber: '5378244888889174', + validationCode: '231', + dueDate: '10/19', + document: '8041734561', + accountId: '', + address: null, + callbackUrl: '' + }, + transaction: {id: '{{transactionId}}', merchantName: '{{accountName}}'} + } +])); +req.end(); +``` + +--- + +```txt Response +200 OK +``` + + + +--- + +## Step 4 - Processing and validating the order + +In this final step, we will process the order. + +- Send a request to the [Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-) endpoint. If the payment is processed without any issues, the order should be successfully placed; otherwise, a `status 500` error might occur. + +> Note that this process uses the gateway connectors configured in your VTEX environment. Be careful to prevent any unwanted charges or unexpected payment denials. + + + +```shell Shell mark=2[17:29],2[31:43],2[86:97],5[21:28] +curl --request post \ + --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/gatewayCallback/{orderGroup}' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'Cookie: {cookie}' \ + --header 'X-VTEX-API-AppKey: ' \ + --header 'X-VTEX-API-AppToken: ' +``` + +```python Python mark=3[37:49],3[51:63] +import http.client + +conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") + +headers = { + 'Cookie': "Vtex_CHKO_Auth=0e/RpYIEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=; CheckoutDataAccess=0e/PoiTEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=", + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "", + 'X-VTEX-API-AppToken': "" + } + +conn.request("post", "/api/checkout/pub/gatewayCallback/123456789", headers=headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) +``` + +```js Node.js mark=5[15:27],5[29:41] +const http = require("https"); + +const options = { + "method": "post", + "hostname": "{accountname}.{environment}.com.br", + "port": null, + "path": "/api/checkout/pub/gatewayCallback/123456789", + "headers": { + "Cookie": "Vtex_CHKO_Auth=0e/RpYIEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=; CheckoutDataAccess=0e/PoiTEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=", + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "", + "X-VTEX-API-AppToken": "" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.end(); +``` + +--- + +```txt Response +200 OK +``` + + + +--- + +### Verifying the order placement + +Finally, you can confirm if your order was correctly placed by checking the [Order management](https://help.vtex.com/en/tutorial/orders-list--tutorials_200#) in VTEX Admin. Alternatively, you can use the [Get order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-) and [List orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders) endpoints for this purpose. + + + +```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43] +``` + +```python Python mark=3[37:49],3[51:63] +``` + +```js Node.js mark=5[15:27],5[29:41] +``` + +--- + +```json Response +{} +``` + + + + \ No newline at end of file From 5eb085b431e6cd5c995f7025b7b923bd7828e1e1 Mon Sep 17 00:00:00 2001 From: Carolina Menezes Date: Fri, 27 Oct 2023 21:18:04 -0300 Subject: [PATCH 02/11] feat/managing-skus --- docs/guides/Catalog/managing-skus.mdx | 420 ++++++++++++++++++++++++++ 1 file changed, 420 insertions(+) create mode 100644 docs/guides/Catalog/managing-skus.mdx diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx new file mode 100644 index 0000000000..6a07742d11 --- /dev/null +++ b/docs/guides/Catalog/managing-skus.mdx @@ -0,0 +1,420 @@ +--- +title: "Managing SKUs" +slug: "managing-skus" +hidden: false +createdAt: "2021-12-14T13:56:04.502Z" +updatedAt: "2022-02-04T21:26:33.803Z" +--- + +This step-by-step guide will walk you through the process of creating, updating, and activating [Stock Keeping Unit (SKU)](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/3mJbIqMlz6oKDmyZ2bKJoA#) in the VTEX platform. A SKU corresponds to the actual item in the inventory that customers can purchase, which means it is equivalent to a unique product variation, such as a "long sleeve gray size S shirt." + + + + + +```sh Shell mark=2[16:28],2[30:42],5[31:38],6[33:42] +curl --request post \ + --url https://{accountName}.{environment}.com.br/api/catalog/pvt/stockkeepingunit \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' \ + --data '{"Id":1,"ProductId":42,"IsActive":false,"ActivateIfPossible":true,"Name":"Size 10","RefId":"B096QW8Y8Z","Ean":"8949461894984","PackagedHeight":10,"PackagedLength":10,"PackagedWidth":10,"PackagedWeightKg":10,"Height":1,"Length":1,"Width":1,"WeightKg":1,"CubicWeight":0.1667,"IsKit":false,"CreationDate":"2020-01-25T15:51:29.2614605","RewardValue":1,"EstimatedDateArrival":null,"ManufacturerCode":"123","CommercialConditionId":1,"MeasurementUnit":"un","UnitMultiplier":2,"ModalType":null,"KitItensSellApart":false,"Videos":["https://www.youtube.com/"]}' +``` + +```py Python +import http.client + +conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") + +payload = "{\"Id\":1,\"ProductId\":42,\"IsActive\":false,\"ActivateIfPossible\":true,\"Name\":\"Size 10\",\"RefId\":\"B096QW8Y8Z\",\"Ean\":\"8949461894984\",\"PackagedHeight\":10,\"PackagedLength\":10,\"PackagedWidth\":10,\"PackagedWeightKg\":10,\"Height\":1,\"Length\":1,\"Width\":1,\"WeightKg\":1,\"CubicWeight\":0.1667,\"IsKit\":false,\"CreationDate\":\"2020-01-25T15:51:29.2614605\",\"RewardValue\":1,\"EstimatedDateArrival\":null,\"ManufacturerCode\":\"123\",\"CommercialConditionId\":1,\"MeasurementUnit\":\"un\",\"UnitMultiplier\":2,\"ModalType\":null,\"KitItensSellApart\":false,\"Videos\":[\"https://www.youtube.com/\"]}" + +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" + } + +conn.request("post", "/api/catalog/pvt/stockkeepingunit", payload, headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) +``` + +```js Node.js +const http = require("https"); + +const options = { + "method": "post", + "hostname": "{accountName}.{environment}.com.br", + "port": null, + "path": "/api/catalog/pvt/stockkeepingunit", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.write(JSON.stringify({ + Id: 1, + ProductId: 42, + IsActive: false, + ActivateIfPossible: true, + Name: 'Size 10', + RefId: 'B096QW8Y8Z', + Ean: '8949461894984', + PackagedHeight: 10, + PackagedLength: 10, + PackagedWidth: 10, + PackagedWeightKg: 10, + Height: 1, + Length: 1, + Width: 1, + WeightKg: 1, + CubicWeight: 0.1667, + IsKit: false, + CreationDate: '2020-01-25T15:51:29.2614605', + RewardValue: 1, + EstimatedDateArrival: null, + ManufacturerCode: '123', + CommercialConditionId: 1, + MeasurementUnit: 'un', + UnitMultiplier: 2, + ModalType: null, + KitItensSellApart: false, + Videos: ['https://www.youtube.com/'] +})); +req.end(); +``` + +--- + +```json Body +{ + "Id": 1, + "ProductId": 310117069, + "IsActive": false, + "ActivateIfPossible": true, + "Name": "sku test", + "RefId": "125478", + "Ean": "8949461894984", + "PackagedHeight": 10, + "PackagedLength": 10, + "PackagedWidth": 10, + "PackagedWeightKg": 10, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.1667, + "IsKit": false, + "CreationDate": null, + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": "123", + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 2.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": ["https://www.youtube.com/"] +} +``` + + + +## Before you begin + +Before you begin, make sure you have: + +- Created a [product](https://developers.vtex.com/docs/guides/products) for the SKU. +- Obtained a valid `appKey` and `appToken` with the necessary permissions to access the **Catalog API**. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. + +> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. + +--- + +## Creating an SKU + +Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit) to create a new SKU, considering the following: + +- Do not set `IsActive` as `true`. If you send the request to activate the SKU when creating it, you will receive a `400 Bad Request` error. The `IsActive` attribute must always be `false` when sending that request for activation to occur afterward, as explained in [Activating an SKU](#activating-an-sku). +- It's recommended to set `ActivateIfPossible` as `true,` unless you plan to have an internal workflow to [manually activate SKUs](#manual-activation). +- If there is a need to create a new SKU with a specific custom ID, specify the `Id` (`integer`) in the request. Otherwise, VTEX will generate the ID automatically. +- Besides the `mainID`, provide at least one of the following alternate IDs in the request body: `RefId` or `EAN`. It is possible to provide both as well. + +### Request body example (custom ID) + + + +```sh Shell +``` + +```py Python +``` + +```js Node.js +``` + +--- + +```json Body +``` + + + +--- + +#### **Request body example (automatically generated ID)** + + + +```sh Shell +``` + +```py Python +``` + +```js Node.js +``` + +--- + +```json Body +{ + "ProductId": 310117069, + "IsActive": false, + "ActivateIfPossible": true, + "Name": "sku test", + "RefId": "125478", + "Ean": "8949461894984", + "PackagedHeight": 10, + "PackagedLength": 10, + "PackagedWidth": 10, + "PackagedWeightKg": 10, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.1667, + "IsKit": false, + "CreationDate": null, + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": "123", + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 2.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": ["https://www.youtube.com/"] +} +``` + + + +--- + +#### **Response body example** + +```json +{ + "Id": 1, + "ProductId": 310117069, + "IsActive": false, + "ActivateIfPossible": true, + "Name": "sku test", + "RefId": "125478", + "Ean": "8949461894984", + "PackagedHeight": 10, + "PackagedLength": 10, + "PackagedWidth": 10, + "PackagedWeightKg": 10, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.1667, + "IsKit": false, + "CreationDate": null, + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": "123", + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 2.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": ["https://www.youtube.com/"] +} +``` + +--- + +## Updating an SKU + +After an SKU has been successfully created, if any changes are needed or if it's necessary to [activate it manually](#manual-activation), use the [Update SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-). + +#### **Request body example** + + + +```sh Shell +``` + +```py Python +``` + +```js Node.js +``` + +--- + +```json Body +{ + "Id": 70, + "ProductId": 42, + "IsActive": true, + "Name": "Size 10", + "RefId": "B096QW8Y8Z", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.0, + "IsKit": false, + "CreationDate": "2020-01-25T15:51:00", + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": null, + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 1.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": [] +} +``` + + + +--- + +#### **Response body example** + + + +```sh Shell +``` + +```py Python +``` + +```js Node.js +``` + +--- + +```json Body +{ + "Id": 70, + "ProductId": 42, + "IsActive": true, + "Name": "Size 10", + "RefId": "B096QW8Y8Z", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.0, + "IsKit": false, + "CreationDate": "2020-01-25T15:51:00", + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": null, + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 1.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": [] +} +``` + + + +--- + +## Activating an SKU + +Before you can activate an SKU, it must meet the following requirements: + +- The SKU must have at least one of the following alternate IDs configured: `RefId` or `EAN`. +- The SKU must have at least one image associated. To associate an image to an SKU, use the [Create SKU file endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). +- If the SKU has [specifications](https://developers.vtex.com/docs/guides/specifications), they must be filled in. +- If the field `ActivateIfPossible` is `false`, the SKU must be activated manually. For more information, check the [Manual activation](#manual-activation) section. +- If the SKU is a [kit](https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog/pvt/stockkeepingunitkit), it must have at least one component active. +- The SKU must be associated with an active product, which, in turn, must be associated with an active Brand and an active Category. + +Once the SKU complies with all the aspects listed above, there are two ways that you can activate your SKU - [manually](https://developers.vtex.com/docs/guides/how-to-activate-an-sku#manual-activation) or [automatically](https://developers.vtex.com/docs/guides/how-to-activate-an-sku#automatic-activation). Read the following sections for more details. + +> ⚠️ Note that additional configurations are necessary for a product and its SKUs to become visible in a store: +> +> - Having registered a price for the SKU in the associated trade policy (also known as sales channel). Read the Pricing onboarding guide for more information on this process. +> - Having at least one unit in stock. Read the Fulfillment onboarding guide for more information on managing inventory. +> - Configuring your storefront's CMS to display products correctly, as described in this Frequently Asked Question. + +--- + +### Manual activation + +To manually activate your SKU, follow these steps: + +1. [Create the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit), setting `IsActive` as `false` and `ActivateIfPossible` as `false`. +2. If the SKU is a kit, [create and associate SKU components](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-post-sku-kit). +3. [Create and associate SKU files](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). +4. [Update the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-) as active, setting `IsActive` as `true`. + +Now, the SKU should be active in your store. + +--- + +### Automatic activation + +This configuration will automatically update the SKU as active once it is associated with an image or an active component. You do not need to update the SKU as in the previous steps. + +To automatically activate your SKU, follow these steps: + +1. [Create the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit), setting `IsActive` as `false` and `ActivateIfPossible` as `true`. +2. If the SKU is a kit, [create and associate SKU components](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunitkit). +3. [Create and associate SKU files](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). + +Now, the SKU should be active in your store. + + From 86933039a5f17625de2f3954b7249cff6d1f0ccc Mon Sep 17 00:00:00 2001 From: Carolina Menezes Date: Tue, 31 Oct 2023 17:49:53 -0300 Subject: [PATCH 03/11] fix/creating-a-regular-order --- ...-a-regular-order-with-the-checkout-api.mdx | 236 +++++++++++------- 1 file changed, 144 insertions(+), 92 deletions(-) diff --git a/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx b/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx index dae4677ebd..57a1fce577 100644 --- a/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx +++ b/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx @@ -8,20 +8,20 @@ excerpt: "Learn how to use VTEX APIs to efficiently handle the placement, paymen hideTOC: true --- -This step-by-step guide will walk you through the process of using the [Checkout API](https://developers.vtex.com/docs/api-reference/checkout-api) for handling the placement, payment, and delivery aspects of a regular order, with all responsibilities managed within the scope of a single account. This process is divided into the following steps +This step-by-step guide will walk you through the process of using the [Checkout API](https://developers.vtex.com/docs/api-reference/checkout-api) for handling the placement, payment, and delivery aspects of a regular order, with all responsibilities managed within the scope of a single account. This process is divided into the following steps: -1. **Assess cart requirements:** The process begins with the simulation of a cart to assess available delivery and payment options. Additionally, since indicating an email address is necessary to place an order, this step also includes verifying the existence of a customer by cross-referencing their email address in the database. -2. **Assemble the cart:** After assessing the cart requirements, the next step is to assemble the cart, ensuring that all essential order information is organized accurately under the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) object. +1. **Assess cart requirements:** The process begins with the simulation of a cart to assess available delivery and payment options. Additionally, since indicating an email address is necessary to place an order, this step also includes verifying if the provided email is already associated with an existing customer. +2. **Assemble the cart:** After assessing the cart requirements, the next step is to assemble the cart, ensuring that all essential order information is organized according to the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) data structure. 3. **Handle the order:** This step involves placing the order on the VTEX platform and sending the necessary payment data to resolve the order payment. -4. **Processing and validating the order:** The process ends by processing order details and conducting a verification procedure to confirm the successful placement of the order. +4. **Process and validate the order:** The process ends by processing order details and conducting a verification procedure to confirm the successful placement of the order. -```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43] +```shell Shell curl --request post \ - --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/orderForms/simulation?RnbBehavior=0' \ + --url 'https://{accountName}.{environment}.com.br/api/checkout/pub/orderForms/simulation?RnbBehavior=0' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-VTEX-API-AppKey: {appKey}' \ @@ -32,16 +32,16 @@ curl --request post \ ```python Python import http.client -conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") +conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") payload = "{\"items\":[{\"id\":\"1\",\"quantity\":1,\"seller\":\"1\"}],\"country\":\"BRA\",\"postalCode\":\"12345-000\",\"geoCoordinates\":[-47.924747467041016]}" headers = { - 'Accept': "application/json", - 'Content-Type': "application/json", - 'X-VTEX-API-AppKey': "", - 'X-VTEX-API-AppToken': "" - } + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} conn.request("post", "/api/checkout/pub/orderForms/simulation?RnbBehavior=0", payload, headers) @@ -56,14 +56,14 @@ const http = require("https"); const options = { "method": "post", - "hostname": "{accountname}.{environment}.com.br", + "hostname": "{accountName}.{environment}.com.br", "port": null, "path": "/api/checkout/pub/orderForms/simulation?RnbBehavior=0", "headers": { "Accept": "application/json", "Content-Type": "application/json", - "X-VTEX-API-AppKey": "", - "X-VTEX-API-AppToken": "" + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" } }; @@ -163,7 +163,7 @@ req.end(); ## Before you begin -Before proceeding any further, ensure that you have a valid `appKey` and `appToken` granted with the necessary permissions to access the Checkout and Payments Gateway APIs. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. +Before proceeding any further, ensure that you have a valid `appKey` and `appToken` granted with the necessary permissions to access the [Checkout](https://developers.vtex.com/docs/api-reference/checkout-api) and [Payments Gateway](https://developers.vtex.com/docs/api-reference/payments-gateway-api) APIs. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. > ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. @@ -182,13 +182,13 @@ This step provides essential information regarding the available delivery and pa -```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43] +```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43],7[11:138] ``` -```python Python mark=3[37:49],3[51:63] +```python Python mark=3[37:49],3[51:63],10[25:32],11[27:36],5[12:161] ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],5[29:41],11[25:32],12[27:36],30:33 ``` --- @@ -211,24 +211,24 @@ This step verifies if the email used to place the order is already related to a ```shell Shell mark=2[18:30],2[32:44],2[85:98],5[32:39],6[34:43] curl --request get \ - --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/profiles?email={emailAddress}' \ + --url 'https://{accountName}.{environment}.com.br/api/checkout/pub/profiles?email={emailAddress}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-VTEX-API-AppKey: {appKey}' \ --header 'X-VTEX-API-AppToken: {appToken}' ``` -```python Python mark=3[37:49],3[51:63] +```python Python mark=3[37:49],3[51:63],8[25:32],9[27:36],12[55:68] import http.client -conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") +conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") headers = { - 'Accept': "application/json", - 'Content-Type': "application/json", - 'X-VTEX-API-AppKey': "", - 'X-VTEX-API-AppToken': "" - } + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} conn.request("get", "/api/checkout/pub/profiles?email={emailAddress}", headers=headers) @@ -238,19 +238,19 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],5[29:41],7[44:57],11[25:32],12[27:36] const http = require("https"); const options = { "method": "get", - "hostname": "{accountname}.{environment}.com.br", + "hostname": "{accountName}.{environment}.com.br", "port": null, "path": "/api/checkout/pub/profiles?email={emailAddress}", "headers": { "Accept": "application/json", "Content-Type": "application/json", - "X-VTEX-API-AppKey": "", - "X-VTEX-API-AppToken": "" + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" } }; @@ -686,7 +686,7 @@ For returning customers, the `orderForm` for your order should resemble this str ### Placing the order -Send a request to the [`Place order`](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) endpoint, using the `orderForm` you built as the request body. +Send a request to the [`Place order`](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) endpoint using the `orderForm` you built as the request body. Upon receiving a `201 Created` response, take note of these four pieces of information: @@ -699,29 +699,29 @@ Upon receiving a `201 Created` response, take note of these four pieces of infor -```shell Shell mark=2[17:29],2[31:43] +```shell Shell mark=2[17:29],2[31:43],5[31:38],6[33:42],7[10:20] curl --request put \ - --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/orders' \ + --url 'https://{accountName}.{environment}.com.br/api/checkout/pub/orders' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ - --header 'X-VTEX-API-AppKey: ' \ - --header 'X-VTEX-API-AppToken: ' \ - --data 'YOUR_ORDERFORM' + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' \ + --data '{orderForm}' ``` -```python Python mark=3[37:49],3[51:63] +```python Python mark=3[37:49],3[51:63],10[25:32],11[27:36],5[12:22] import http.client -conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") +conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") -payload = "YOUR_ORDERFORM" +payload = "{orderForm}" headers = { - 'Accept': "application/json", - 'Content-Type': "application/json", - 'X-VTEX-API-AppKey': "", - 'X-VTEX-API-AppToken': "" - } + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} conn.request("put", "/api/checkout/pub/orders", payload, headers) @@ -731,19 +731,19 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],5[29:41],11[25:32],12[27:36],29[26:36] const http = require("https"); const options = { "method": "put", - "hostname": "{accountname}.{environment}.com.br", + "hostname": "{accountName}.{environment}.com.br", "port": null, "path": "/api/checkout/pub/orders", "headers": { "Accept": "application/json", "Content-Type": "application/json", - "X-VTEX-API-AppKey": "", - "X-VTEX-API-AppToken": "" + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" } }; @@ -760,7 +760,7 @@ const req = http.request(options, function (res) { }); }); -req.write(JSON.stringify(YOUR_ORDERFORM)); +req.write(JSON.stringify({orderForm})); req.end(); ``` @@ -855,29 +855,29 @@ In this step, we will communicate the necessary payment data to VTEX for the fin -```shell Shell mark=2[17:29],2[31:43] +```shell Shell mark=2[17:29],2[72:86],2[105:113],4[31:38],5[33:42],6[10:407] curl --request post \ - --url 'https://apiexamples.vtexpayments.com.br/api/pub/transactions/{{transactionId}}/payments?orderId={{orderId}}' \ + --url 'https://{accountName}.vtexpayments.com.br/api/pub/transactions/{transactionId}/payments?orderId={orderId}' \ --header 'Content-Type: application/json' \ - --header 'X-VTEX-API-AppKey: ' \ - --header 'X-VTEX-API-AppToken: ' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' \ --data '[{"paymentSystem":4,"installments":1,"currencyCode":"BRL","value":100,"installmentsInterestRate":0,"installmentsValue":100,"referenceValue":100,"fields":{"holderName":"UserTest","cardNumber":"5378244888889174","validationCode":"231","dueDate":"10/19","document":"8041734561","accountId":"","address":null,"callbackUrl":""},"transaction":{"id":"{{transactionId}}","merchantName":"{{accountName}}"}}]' ``` -```python Python mark=3[37:49],3[51:63] +```python Python mark=3[37:49],9[25:32],10[27:36],13[45:59],13[78:86] import http.client -conn = http.client.HTTPSConnection("apiexamples.vtexpayments.com.br") +conn = http.client.HTTPSConnection("{accountName}.vtexpayments.com.br") payload = "[{\"paymentSystem\":4,\"installments\":1,\"currencyCode\":\"BRL\",\"value\":100,\"installmentsInterestRate\":0,\"installmentsValue\":100,\"referenceValue\":100,\"fields\":{\"holderName\":\"UserTest\",\"cardNumber\":\"5378244888889174\",\"validationCode\":\"231\",\"dueDate\":\"10/19\",\"document\":\"8041734561\",\"accountId\":\"\",\"address\":null,\"callbackUrl\":\"\"},\"transaction\":{\"id\":\"{{transactionId}}\",\"merchantName\":\"{{accountName}}\"}}]" headers = { - 'Content-Type': "application/json", - 'X-VTEX-API-AppKey': "", - 'X-VTEX-API-AppToken': "" - } + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} -conn.request("post", "/api/pub/transactions/%7B%7BtransactionId%7D%7D/payments?orderId=%7B%7BorderId%7D%7D", payload, headers) +conn.request("post", "/api/pub/transactions/{transactionId}/payments?orderId={orderId}", payload, headers) res = conn.getresponse() data = res.read() @@ -885,18 +885,18 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],10[25:32],11[27:36],29:48,7[33:47],7[66:74] const http = require("https"); const options = { "method": "post", - "hostname": "apiexamples.vtexpayments.com.br", + "hostname": "{accountName}.vtexpayments.com.br", "port": null, - "path": "/api/pub/transactions/%7B%7BtransactionId%7D%7D/payments?orderId=%7B%7BorderId%7D%7D", + "path": "/api/pub/transactions/{transactionId}/payments?orderId={orderId}", "headers": { "Content-Type": "application/json", - "X-VTEX-API-AppKey": "", - "X-VTEX-API-AppToken": "" + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" } }; @@ -950,7 +950,7 @@ req.end(); ## Step 4 - Processing and validating the order -In this final step, we will process the order. +In this final step, we will process the order. - Send a request to the [Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-) endpoint. If the payment is processed without any issues, the order should be successfully placed; otherwise, a `status 500` error might occur. @@ -958,30 +958,30 @@ In this final step, we will process the order. -```shell Shell mark=2[17:29],2[31:43],2[86:97],5[21:28] +```shell Shell mark=2[18:30],2[32:44],2[86:97],5[21:28],6[32:39],7[34:43] curl --request post \ - --url 'https://{accountname}.{environment}.com.br/api/checkout/pub/gatewayCallback/{orderGroup}' \ + --url 'https://{accountName}.{environment}.com.br/api/checkout/pub/gatewayCallback/{orderGroup}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Cookie: {cookie}' \ - --header 'X-VTEX-API-AppKey: ' \ - --header 'X-VTEX-API-AppToken: ' + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' ``` -```python Python mark=3[37:49],3[51:63] +```python Python mark=3[37:49],3[51:63],9[25:32],10[27:36],6[14:21],13[57:68] import http.client -conn = http.client.HTTPSConnection("{accountname}.{environment}.com.br") +conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") headers = { - 'Cookie': "Vtex_CHKO_Auth=0e/RpYIEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=; CheckoutDataAccess=0e/PoiTEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=", - 'Accept': "application/json", - 'Content-Type': "application/json", - 'X-VTEX-API-AppKey': "", - 'X-VTEX-API-AppToken': "" - } + 'Cookie': "{cookie}", + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} -conn.request("post", "/api/checkout/pub/gatewayCallback/123456789", headers=headers) +conn.request("post", "/api/checkout/pub/gatewayCallback/{orderGroup}", headers) res = conn.getresponse() data = res.read() @@ -989,20 +989,20 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],5[29:41],12[25:32],13[27:36],7[45:56] const http = require("https"); const options = { "method": "post", - "hostname": "{accountname}.{environment}.com.br", + "hostname": "{accountName}.{environment}.com.br", "port": null, - "path": "/api/checkout/pub/gatewayCallback/123456789", + "path": "/api/checkout/pub/gatewayCallback/{orderGroup}", "headers": { - "Cookie": "Vtex_CHKO_Auth=0e/RpYIEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=; CheckoutDataAccess=0e/PoiTEZu19BuwXB4tZ7eIGu9HT8vdUAHWQDHDpxMc=", + "Cookie": "{cookie}", "Accept": "application/json", "Content-Type": "application/json", - "X-VTEX-API-AppKey": "", - "X-VTEX-API-AppToken": "" + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" } }; @@ -1038,21 +1038,73 @@ Finally, you can confirm if your order was correctly placed by checking the [Ord -```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43] +```shell Shell mark=2[17:29],5[31:38],6[33:42],2[76:84] +curl --request get \ + --url 'https://{accountName}.vtexcommercestable.com.br/api/oms/pvt/orders/{orderId}' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' ``` -```python Python mark=3[37:49],3[51:63] +```python Python mark=3[37:49],8[25:32],9[27:36],12[42:50] +import http.client + +conn = http.client.HTTPSConnection("{accountName}.vtexcommercestable.com.br") + +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} + +conn.request("get", "/api/oms/pvt/orders/{orderId}", headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],7[31:39],11[25:32],12[27:36] +const http = require("https"); + +const options = { + "method": "get", + "hostname": "{accountName}.vtexcommercestable.com.br", + "port": null, + "path": "/api/oms/pvt/orders/{orderId}", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.end(); ``` --- -```json Response -{} +```txt Response +200 OK ``` - \ No newline at end of file + From b5a16d4b0fa2f068002af6f6548da756fdded9ec Mon Sep 17 00:00:00 2001 From: Carolina Menezes Date: Wed, 1 Nov 2023 14:37:01 -0300 Subject: [PATCH 04/11] improve: maging-skus --- docs/guides/Catalog/managing-skus.mdx | 439 ++++++++++++++++---------- 1 file changed, 268 insertions(+), 171 deletions(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index 6a07742d11..d40f4577f7 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -1,40 +1,50 @@ --- title: "Managing SKUs" slug: "managing-skus" +excerpt: "Learn how to create, update, and activate an SKU with the Catalog API." hidden: false createdAt: "2021-12-14T13:56:04.502Z" updatedAt: "2022-02-04T21:26:33.803Z" --- -This step-by-step guide will walk you through the process of creating, updating, and activating [Stock Keeping Unit (SKU)](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/3mJbIqMlz6oKDmyZ2bKJoA#) in the VTEX platform. A SKU corresponds to the actual item in the inventory that customers can purchase, which means it is equivalent to a unique product variation, such as a "long sleeve gray size S shirt." +This step-by-step guide will walk you through the process of creating, updating, and activating a [Stock Keeping Unit (SKU)](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/3mJbIqMlz6oKDmyZ2bKJoA#) within the VTEX platform. An SKU represents a specific item in the inventory that customers can purchase, essentially serving as a unique product variation, such as a "long sleeve gray size S shirt." +## Before you begin + +Before you begin managing your SKUs, make sure you've completed the following steps: + +- **Create a Product**: Your SKUs should be associated with an existing product. If you haven't created a product yet, refer to the [Product](https://developers.vtex.com/docs/guides/products) for more information. +- **Obtain API Credentials**: Ensure you have a valid `appKey` and `appToken` with the necessary permissions to access the [Catalog API](https://developers.vtex.com/docs/api-reference/catalog-api). For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. + +> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. + -```sh Shell mark=2[16:28],2[30:42],5[31:38],6[33:42] +```sh Shell mark=2[16:28],5[31:38],6[33:42],7[10:15] curl --request post \ - --url https://{accountName}.{environment}.com.br/api/catalog/pvt/stockkeepingunit \ + --url https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/stockkeepingunit \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-VTEX-API-AppKey: {appKey}' \ --header 'X-VTEX-API-AppToken: {appToken}' \ - --data '{"Id":1,"ProductId":42,"IsActive":false,"ActivateIfPossible":true,"Name":"Size 10","RefId":"B096QW8Y8Z","Ean":"8949461894984","PackagedHeight":10,"PackagedLength":10,"PackagedWidth":10,"PackagedWeightKg":10,"Height":1,"Length":1,"Width":1,"WeightKg":1,"CubicWeight":0.1667,"IsKit":false,"CreationDate":"2020-01-25T15:51:29.2614605","RewardValue":1,"EstimatedDateArrival":null,"ManufacturerCode":"123","CommercialConditionId":1,"MeasurementUnit":"un","UnitMultiplier":2,"ModalType":null,"KitItensSellApart":false,"Videos":["https://www.youtube.com/"]}' + --data '{body}' ``` -```py Python +```py Python mark=3[37:49],5[12:17],10[25:32],11[28:36] import http.client -conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") +conn = http.client.HTTPSConnection("{accountName}.vtexcommercestable.com.br") -payload = "{\"Id\":1,\"ProductId\":42,\"IsActive\":false,\"ActivateIfPossible\":true,\"Name\":\"Size 10\",\"RefId\":\"B096QW8Y8Z\",\"Ean\":\"8949461894984\",\"PackagedHeight\":10,\"PackagedLength\":10,\"PackagedWidth\":10,\"PackagedWeightKg\":10,\"Height\":1,\"Length\":1,\"Width\":1,\"WeightKg\":1,\"CubicWeight\":0.1667,\"IsKit\":false,\"CreationDate\":\"2020-01-25T15:51:29.2614605\",\"RewardValue\":1,\"EstimatedDateArrival\":null,\"ManufacturerCode\":\"123\",\"CommercialConditionId\":1,\"MeasurementUnit\":\"un\",\"UnitMultiplier\":2,\"ModalType\":null,\"KitItensSellApart\":false,\"Videos\":[\"https://www.youtube.com/\"]}" +payload = "{body}" headers = { - 'Accept': "application/json", - 'Content-Type': "application/json", - 'X-VTEX-API-AppKey': "{appKey}", - 'X-VTEX-API-AppToken': "{appToken}" - } + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} conn.request("post", "/api/catalog/pvt/stockkeepingunit", payload, headers) @@ -44,12 +54,12 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js +```js Node.js mark=5[15:27],11[25:32],12[28:36],29[26:31] const http = require("https"); const options = { "method": "post", - "hostname": "{accountName}.{environment}.com.br", + "hostname": "{accountName}.vtexcommercestable.com.br", "port": null, "path": "/api/catalog/pvt/stockkeepingunit", "headers": { @@ -73,41 +83,13 @@ const req = http.request(options, function (res) { }); }); -req.write(JSON.stringify({ - Id: 1, - ProductId: 42, - IsActive: false, - ActivateIfPossible: true, - Name: 'Size 10', - RefId: 'B096QW8Y8Z', - Ean: '8949461894984', - PackagedHeight: 10, - PackagedLength: 10, - PackagedWidth: 10, - PackagedWeightKg: 10, - Height: 1, - Length: 1, - Width: 1, - WeightKg: 1, - CubicWeight: 0.1667, - IsKit: false, - CreationDate: '2020-01-25T15:51:29.2614605', - RewardValue: 1, - EstimatedDateArrival: null, - ManufacturerCode: '123', - CommercialConditionId: 1, - MeasurementUnit: 'un', - UnitMultiplier: 2, - ModalType: null, - KitItensSellApart: false, - Videos: ['https://www.youtube.com/'] -})); +req.write(JSON.stringify({body})); req.end(); ``` --- -```json Body +```json Response { "Id": 1, "ProductId": 310117069, @@ -141,65 +123,38 @@ req.end(); -## Before you begin - -Before you begin, make sure you have: - -- Created a [product](https://developers.vtex.com/docs/guides/products) for the SKU. -- Obtained a valid `appKey` and `appToken` with the necessary permissions to access the **Catalog API**. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. - -> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. - --- ## Creating an SKU -Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit) to create a new SKU, considering the following: - -- Do not set `IsActive` as `true`. If you send the request to activate the SKU when creating it, you will receive a `400 Bad Request` error. The `IsActive` attribute must always be `false` when sending that request for activation to occur afterward, as explained in [Activating an SKU](#activating-an-sku). -- It's recommended to set `ActivateIfPossible` as `true,` unless you plan to have an internal workflow to [manually activate SKUs](#manual-activation). -- If there is a need to create a new SKU with a specific custom ID, specify the `Id` (`integer`) in the request. Otherwise, VTEX will generate the ID automatically. -- Besides the `mainID`, provide at least one of the following alternate IDs in the request body: `RefId` or `EAN`. It is possible to provide both as well. - -### Request body example (custom ID) - - - -```sh Shell -``` - -```py Python -``` - -```js Node.js -``` - ---- +Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit) to create a new SKU, considering the following points when building the request body: -```json Body -``` +- `IsActive`: Ensure that `IsActive` is set to `false`. Activating it during creation will result in a `400 Bad Request` error. +- `ActivateIfPossible`: It's recommended to set `ActivateIfPossible` as `true,` unless you plan to have an internal workflow to [manually activate SKUs](#manual-activation). +- **Alternate IDs**: Provide at least one of the following IDs in the request body: `RefId` or `EAN`. You can also provide both if necessary. - +When sending the request body, you can specify the desired SKU `Id` or let VTEX automatically generate it, as presented in the following. ---- +### Custom `Id`: Request body -#### **Request body example (automatically generated ID)** +If there is a need to create a new SKU with a specific custom `Id`, specify the `Id` (`integer`) in the request body. -```sh Shell +```sh Shell mark=2[16:28],5[31:38],6[33:42],7[10:15] ``` -```py Python +```py Python mark=3[37:49],5[12:17],10[25:32],11[28:36] ``` -```js Node.js +```js Node.js mark=5[15:27],11[25:32],12[28:36],29[26:31] ``` --- -```json Body +```json Body mark=2,4:5,7:8 { + "Id": 1, "ProductId": 310117069, "IsActive": false, "ActivateIfPossible": true, @@ -233,11 +188,25 @@ Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api --- -#### **Response body example** +### Automatically generated ID: Request body + +If there's no need to specify a custom `Id`, you can omit it from the request body, and VTEX will automatically generate the `Id`. + + + +```sh Shell mark=2[16:28],5[31:38],6[33:42],7[10:15] +``` + +```py Python mark=3[37:49],5[12:17],10[25:32],11[28:36] +``` + +```js Node.js mark=5[15:27],11[25:32],12[28:36],29[26:31] +``` + +--- -```json +```json Body mark=3:4,6:7 { - "Id": 1, "ProductId": 310117069, "IsActive": false, "ActivateIfPossible": true, @@ -267,54 +236,125 @@ Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api } ``` + + --- ## Updating an SKU -After an SKU has been successfully created, if any changes are needed or if it's necessary to [activate it manually](#manual-activation), use the [Update SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-). - -#### **Request body example** +After successfully creating an SKU, you can update its details by sending a request to the [Update SKU](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-) endpoint. To update an SKU, provide the SKU's unique `skuId` in the URL and include the updated information in the request body. -```sh Shell +```sh Shell mark=2[17:29],2[90:96],5[31:38],6[33:42],7[10:15] +curl --request put \ + --url 'https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/stockkeepingunit/{skuId}' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' \ + --data '{body}' ``` -```py Python +```py Python mark=3[37:49],5[12:17],10[25:32],11[28:36],14[56:62] +import http.client + +conn = http.client.HTTPSConnection("{accountName}.vtexcommercestable.com.br") + +payload = "{body}" + +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} + +conn.request("put", "/api/catalog/pvt/stockkeepingunit/{skuId}", payload, headers) + +res = conn.getresponse() +data = res.read() + +print(data.decode("utf-8")) ``` -```js Node.js +```js Node.js mark=5[15:27],7[45:51],11[25:32],12[28:36],29[26:31] +const http = require("https"); + +const options = { + "method": "put", + "hostname": "{accountName}.vtexcommercestable.com.br", + "port": null, + "path": "/api/catalog/pvt/stockkeepingunit/{skuId}", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" + } +}; + +const req = http.request(options, function (res) { + const chunks = []; + + res.on("data", function (chunk) { + chunks.push(chunk); + }); + + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.write(JSON.stringify({body})); +req.end(); ``` --- ```json Body { - "Id": 70, - "ProductId": 42, - "IsActive": true, - "Name": "Size 10", - "RefId": "B096QW8Y8Z", - "PackagedHeight": 15.0, - "PackagedLength": 15.0, - "PackagedWidth": 15.0, - "PackagedWeightKg": 15.0, - "Height": null, - "Length": null, - "Width": null, - "WeightKg": null, - "CubicWeight": 0.0, - "IsKit": false, - "CreationDate": "2020-01-25T15:51:00", - "RewardValue": null, - "EstimatedDateArrival": null, - "ManufacturerCode": null, - "CommercialConditionId": 1, - "MeasurementUnit": "un", - "UnitMultiplier": 1.0, - "ModalType": null, - "KitItensSellApart": false, - "Videos": [] + "Id": 70, + "ProductId": 42, + "IsActive": true, + "Name": "Size 10", + "RefId": "B096QW8Y8Z", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, + // Other attributes to update +} +``` + +```json Response +{ + "Id": 70, + "ProductId": 42, + "IsActive": true, + "Name": "Size 10", + "RefId": "B096QW8Y8Z", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.0, + "IsKit": false, + "CreationDate": "2020-01-25T15:51:00", + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": null, + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 1.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": [] } ``` @@ -322,48 +362,56 @@ After an SKU has been successfully created, if any changes are needed or if it's --- -#### **Response body example** +## Activating an SKU - +Activating an SKU means making it available for purchase in your store, allowing customers to browse, search, and buy the associated product. To be activated, ensure your SKU meets the following requirements: -```sh Shell -``` +- **Alternate IDs**: The SKU must have at least one of the following alternate IDs configured: `RefId` or `EAN`. +- **Image**: The SKU must have at least one image associated with it. Use the [Create SKU file endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file) to associate an image to an SKU. +- **Specifications**: If the SKU has [specifications](https://developers.vtex.com/docs/guides/specifications), they must be filled in. +- **Kit**: For [kit](https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog/pvt/stockkeepingunitkit) SKUs, at least one component must be active. +- **Product**: The SKU must be associated with an active product, which, in turn, must be related to an active [Brand](https://developers.vtex.com/docs/guides/brands) and an active [Category](https://developers.vtex.com/docs/guides/categories). -```py Python -``` +Once the SKU meets these requirements, you can activate it using one of the following methods: [automatic](#automatic-activation) or [manual](#manual-activation). -```js Node.js -``` +### Automatic activation ---- +If your SKU's `IsActive` is set to `false` and `ActivateIfPossible` is set to `true`, your SKU will automatically become active as soon as it is associated with an image or an active component. -```json Body + + +```json Response mark=7:8 { - "Id": 70, - "ProductId": 42, - "IsActive": true, - "Name": "Size 10", - "RefId": "B096QW8Y8Z", - "PackagedHeight": 15.0, - "PackagedLength": 15.0, - "PackagedWidth": 15.0, - "PackagedWeightKg": 15.0, + "Id": 1, + "ProductId": 310117069, + //If IsActive is false and ActivateIfPossible is true, + //the SKU will become active as soon as it is associated + //with an image or an active component. + "IsActive": false, + "ActivateIfPossible": true, + "Name": "sku test", + "RefId": "125478", + "Ean": "8949461894984", + "PackagedHeight": 10, + "PackagedLength": 10, + "PackagedWidth": 10, + "PackagedWeightKg": 10, "Height": null, "Length": null, "Width": null, "WeightKg": null, - "CubicWeight": 0.0, + "CubicWeight": 0.1667, "IsKit": false, - "CreationDate": "2020-01-25T15:51:00", + "CreationDate": null, "RewardValue": null, "EstimatedDateArrival": null, - "ManufacturerCode": null, + "ManufacturerCode": "123", "CommercialConditionId": 1, "MeasurementUnit": "un", - "UnitMultiplier": 1.0, + "UnitMultiplier": 2.0, "ModalType": null, "KitItensSellApart": false, - "Videos": [] + "Videos": ["https://www.youtube.com/"] } ``` @@ -371,50 +419,99 @@ After an SKU has been successfully created, if any changes are needed or if it's --- -## Activating an SKU +### Manual activation -Before you can activate an SKU, it must meet the following requirements: +If your SKU's `IsActive` is set to `false` and `ActivateIfPossible` is set to `false`, send a request to the [Update the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-) endpoint, setting `IsActive` as `true`. -- The SKU must have at least one of the following alternate IDs configured: `RefId` or `EAN`. -- The SKU must have at least one image associated. To associate an image to an SKU, use the [Create SKU file endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). -- If the SKU has [specifications](https://developers.vtex.com/docs/guides/specifications), they must be filled in. -- If the field `ActivateIfPossible` is `false`, the SKU must be activated manually. For more information, check the [Manual activation](#manual-activation) section. -- If the SKU is a [kit](https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog/pvt/stockkeepingunitkit), it must have at least one component active. -- The SKU must be associated with an active product, which, in turn, must be associated with an active Brand and an active Category. + -Once the SKU complies with all the aspects listed above, there are two ways that you can activate your SKU - [manually](https://developers.vtex.com/docs/guides/how-to-activate-an-sku#manual-activation) or [automatically](https://developers.vtex.com/docs/guides/how-to-activate-an-sku#automatic-activation). Read the following sections for more details. +```sh Shell mark=2[17:29],2[90:96],5[31:38],6[33:42],7[10:15] +curl --request put \ + --url 'https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/stockkeepingunit/{skuId}' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'X-VTEX-API-AppKey: {appKey}' \ + --header 'X-VTEX-API-AppToken: {appToken}' \ + --data '{body}' +``` -> ⚠️ Note that additional configurations are necessary for a product and its SKUs to become visible in a store: -> -> - Having registered a price for the SKU in the associated trade policy (also known as sales channel). Read the Pricing onboarding guide for more information on this process. -> - Having at least one unit in stock. Read the Fulfillment onboarding guide for more information on managing inventory. -> - Configuring your storefront's CMS to display products correctly, as described in this Frequently Asked Question. +```py Python mark=3[37:49],5[12:17],10[25:32],11[28:36],14[56:62] +import http.client ---- +conn = http.client.HTTPSConnection("{accountName}.vtexcommercestable.com.br") -### Manual activation +payload = "{body}" -To manually activate your SKU, follow these steps: +headers = { + 'Accept': "application/json", + 'Content-Type': "application/json", + 'X-VTEX-API-AppKey': "{appKey}", + 'X-VTEX-API-AppToken': "{appToken}" +} -1. [Create the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit), setting `IsActive` as `false` and `ActivateIfPossible` as `false`. -2. If the SKU is a kit, [create and associate SKU components](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-post-sku-kit). -3. [Create and associate SKU files](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). -4. [Update the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-) as active, setting `IsActive` as `true`. +conn.request("put", "/api/catalog/pvt/stockkeepingunit/{skuId}", payload, headers) -Now, the SKU should be active in your store. +res = conn.getresponse() +data = res.read() ---- +print(data.decode("utf-8")) +``` -### Automatic activation +```js Node.js mark=5[15:27],7[45:51],11[25:32],12[28:36],29[26:31] +const http = require("https"); -This configuration will automatically update the SKU as active once it is associated with an image or an active component. You do not need to update the SKU as in the previous steps. +const options = { + "method": "put", + "hostname": "{accountName}.vtexcommercestable.com.br", + "port": null, + "path": "/api/catalog/pvt/stockkeepingunit/{skuId}", + "headers": { + "Accept": "application/json", + "Content-Type": "application/json", + "X-VTEX-API-AppKey": "{appKey}", + "X-VTEX-API-AppToken": "{appToken}" + } +}; -To automatically activate your SKU, follow these steps: +const req = http.request(options, function (res) { + const chunks = []; -1. [Create the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit), setting `IsActive` as `false` and `ActivateIfPossible` as `true`. -2. If the SKU is a kit, [create and associate SKU components](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunitkit). -3. [Create and associate SKU files](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). + res.on("data", function (chunk) { + chunks.push(chunk); + }); -Now, the SKU should be active in your store. + res.on("end", function () { + const body = Buffer.concat(chunks); + console.log(body.toString()); + }); +}); + +req.write(JSON.stringify({body})); +req.end(); +``` + +--- + +```json Body mark=5 +{ + "Id": 70, + "ProductId": 42, + //Set the IsActive attribute to true + "IsActive": true, + "Name": "Size 10", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, +} +``` + + + +>❗ Note that additional configurations are necessary for a product and its SKUs to become visible in a store: +> +> - Register a price for the SKU in the associated trade policy (sales channel). Refer to the [Pricing](https://developers.vtex.com/docs/guides/pricing-overview) guide for more information. +> - Ensure you have at least one unit in stock. Manage your inventory by following the [Fulfillment](https://developers.vtex.com/docs/guides/fulfillment) guide. +> - Configure your storefront to display products correctly. From 2f9c392bdfb8015241a00deb6b9f3d08844c5d07 Mon Sep 17 00:00:00 2001 From: Carolina Menezes <60782333+carolinamenezes@users.noreply.github.com> Date: Wed, 1 Nov 2023 16:30:25 -0300 Subject: [PATCH 05/11] Update docs/guides/Catalog/managing-skus.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Rabello <77292838+julia-rabello@users.noreply.github.com> --- docs/guides/Catalog/managing-skus.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index d40f4577f7..1891e77698 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -15,7 +15,7 @@ This step-by-step guide will walk you through the process of creating, updating, Before you begin managing your SKUs, make sure you've completed the following steps: -- **Create a Product**: Your SKUs should be associated with an existing product. If you haven't created a product yet, refer to the [Product](https://developers.vtex.com/docs/guides/products) for more information. +- **Create a Product**: Your SKUs should be associated with an existing product. If you haven't created a product yet, refer to the [Product](https://developers.vtex.com/docs/guides/products) guide for more information. - **Obtain API Credentials**: Ensure you have a valid `appKey` and `appToken` with the necessary permissions to access the [Catalog API](https://developers.vtex.com/docs/api-reference/catalog-api). For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. > ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. From 1e06482b0fbaba1a2560f4a95c816d1d74edc6f2 Mon Sep 17 00:00:00 2001 From: Carolina Menezes <60782333+carolinamenezes@users.noreply.github.com> Date: Wed, 1 Nov 2023 16:31:37 -0300 Subject: [PATCH 06/11] Update docs/guides/Catalog/managing-skus.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Rabello <77292838+julia-rabello@users.noreply.github.com> --- docs/guides/Catalog/managing-skus.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index 1891e77698..3d6b0a1654 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -370,7 +370,7 @@ Activating an SKU means making it available for purchase in your store, allowing - **Image**: The SKU must have at least one image associated with it. Use the [Create SKU file endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file) to associate an image to an SKU. - **Specifications**: If the SKU has [specifications](https://developers.vtex.com/docs/guides/specifications), they must be filled in. - **Kit**: For [kit](https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog/pvt/stockkeepingunitkit) SKUs, at least one component must be active. -- **Product**: The SKU must be associated with an active product, which, in turn, must be related to an active [Brand](https://developers.vtex.com/docs/guides/brands) and an active [Category](https://developers.vtex.com/docs/guides/categories). +- **Product**: The SKU must be associated with an active [product](https://developers.vtex.com/docs/guides/products), which, in turn, must be related to an active [Brand](https://developers.vtex.com/docs/guides/brands) and an active [Category](https://developers.vtex.com/docs/guides/categories). Once the SKU meets these requirements, you can activate it using one of the following methods: [automatic](#automatic-activation) or [manual](#manual-activation). From 86f6a70af2a030385bfe621fb1641dd78adb7f3e Mon Sep 17 00:00:00 2001 From: Carolina Menezes <60782333+carolinamenezes@users.noreply.github.com> Date: Wed, 1 Nov 2023 16:31:58 -0300 Subject: [PATCH 07/11] Update docs/guides/Catalog/managing-skus.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Rabello <77292838+julia-rabello@users.noreply.github.com> --- docs/guides/Catalog/managing-skus.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index 3d6b0a1654..593a912461 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -384,9 +384,6 @@ If your SKU's `IsActive` is set to `false` and `ActivateIfPossible` is set to `t { "Id": 1, "ProductId": 310117069, - //If IsActive is false and ActivateIfPossible is true, - //the SKU will become active as soon as it is associated - //with an image or an active component. "IsActive": false, "ActivateIfPossible": true, "Name": "sku test", From cd1c2938d1f9ffc3df69b53ba22b96ee520f3710 Mon Sep 17 00:00:00 2001 From: Carolina Menezes <60782333+carolinamenezes@users.noreply.github.com> Date: Wed, 1 Nov 2023 16:32:10 -0300 Subject: [PATCH 08/11] Update docs/guides/Catalog/managing-skus.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Rabello <77292838+julia-rabello@users.noreply.github.com> --- docs/guides/Catalog/managing-skus.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index 593a912461..8ecd951ba7 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -135,7 +135,7 @@ Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api When sending the request body, you can specify the desired SKU `Id` or let VTEX automatically generate it, as presented in the following. -### Custom `Id`: Request body +### Custom ID: Request body If there is a need to create a new SKU with a specific custom `Id`, specify the `Id` (`integer`) in the request body. From 65952e63d78cd02c5588dc2152af0ef89b83e6de Mon Sep 17 00:00:00 2001 From: Carolina Menezes <60782333+carolinamenezes@users.noreply.github.com> Date: Wed, 1 Nov 2023 16:32:23 -0300 Subject: [PATCH 09/11] Update docs/guides/Catalog/managing-skus.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Rabello <77292838+julia-rabello@users.noreply.github.com> --- docs/guides/Catalog/managing-skus.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index 8ecd951ba7..1db0fd693a 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -133,7 +133,7 @@ Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api - `ActivateIfPossible`: It's recommended to set `ActivateIfPossible` as `true,` unless you plan to have an internal workflow to [manually activate SKUs](#manual-activation). - **Alternate IDs**: Provide at least one of the following IDs in the request body: `RefId` or `EAN`. You can also provide both if necessary. -When sending the request body, you can specify the desired SKU `Id` or let VTEX automatically generate it, as presented in the following. +When sending the request body, you can specify the desired SKU `Id` or let VTEX automatically generate it, as presented in the following sections. ### Custom ID: Request body From 16ce8e10d1d837b65cb7a140804320205670f2b2 Mon Sep 17 00:00:00 2001 From: Carolina Menezes Date: Wed, 1 Nov 2023 16:52:16 -0300 Subject: [PATCH 10/11] fix/implement reviewer suggestions --- docs/guides/Catalog/managing-skus.mdx | 159 +++++++++++++++++--------- 1 file changed, 108 insertions(+), 51 deletions(-) diff --git a/docs/guides/Catalog/managing-skus.mdx b/docs/guides/Catalog/managing-skus.mdx index 1db0fd693a..df689de155 100644 --- a/docs/guides/Catalog/managing-skus.mdx +++ b/docs/guides/Catalog/managing-skus.mdx @@ -9,16 +9,30 @@ updatedAt: "2022-02-04T21:26:33.803Z" This step-by-step guide will walk you through the process of creating, updating, and activating a [Stock Keeping Unit (SKU)](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/3mJbIqMlz6oKDmyZ2bKJoA#) within the VTEX platform. An SKU represents a specific item in the inventory that customers can purchase, essentially serving as a unique product variation, such as a "long sleeve gray size S shirt." - - ## Before you begin Before you begin managing your SKUs, make sure you've completed the following steps: -- **Create a Product**: Your SKUs should be associated with an existing product. If you haven't created a product yet, refer to the [Product](https://developers.vtex.com/docs/guides/products) guide for more information. +- **Create a Product**: Your SKUs should be associated with an existing product. If you haven't created a product yet, refer to the [Product](https://developers.vtex.com/docs/guides/products) for more information. - **Obtain API Credentials**: Ensure you have a valid `appKey` and `appToken` with the necessary permissions to access the [Catalog API](https://developers.vtex.com/docs/api-reference/catalog-api). For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. -> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. +> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. Additionally, in the code viewer on the right, you can switch between different code files or tabs to view the corresponding code examples. + + + +## Creating an SKU + +Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit) to create a new SKU, considering the following points when building the request body: + +- `IsActive`: Ensure that `IsActive` is set to `false`. Activating it during creation will result in a `400 Bad Request` error. +- `ActivateIfPossible`: It's recommended to set `ActivateIfPossible` as `true,` unless you plan to have an internal workflow to [manually activate SKUs](#manual-activation). +- **Alternate IDs**: Provide at least one of the following IDs in the request body: `RefId` or `EAN`. You can also provide both if necessary. + +When sending the request body, you can specify the desired SKU `Id` or let VTEX automatically generate it, as presented in the following. + +### Custom `Id`: Request body + +If there is a need to create a new SKU with a specific custom `Id`, specify the `Id` (`integer`) in the request body. @@ -89,7 +103,7 @@ req.end(); --- -```json Response +```json Body mark=2,4:5,7:8 { "Id": 1, "ProductId": 310117069, @@ -121,38 +135,7 @@ req.end(); } ``` - - ---- - -## Creating an SKU - -Send a request to the [Create SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit) to create a new SKU, considering the following points when building the request body: - -- `IsActive`: Ensure that `IsActive` is set to `false`. Activating it during creation will result in a `400 Bad Request` error. -- `ActivateIfPossible`: It's recommended to set `ActivateIfPossible` as `true,` unless you plan to have an internal workflow to [manually activate SKUs](#manual-activation). -- **Alternate IDs**: Provide at least one of the following IDs in the request body: `RefId` or `EAN`. You can also provide both if necessary. - -When sending the request body, you can specify the desired SKU `Id` or let VTEX automatically generate it, as presented in the following sections. - -### Custom ID: Request body - -If there is a need to create a new SKU with a specific custom `Id`, specify the `Id` (`integer`) in the request body. - - - -```sh Shell mark=2[16:28],5[31:38],6[33:42],7[10:15] -``` - -```py Python mark=3[37:49],5[12:17],10[25:32],11[28:36] -``` - -```js Node.js mark=5[15:27],11[25:32],12[28:36],29[26:31] -``` - ---- - -```json Body mark=2,4:5,7:8 +```json Response { "Id": 1, "ProductId": 310117069, @@ -324,7 +307,22 @@ req.end(); "PackagedLength": 15.0, "PackagedWidth": 15.0, "PackagedWeightKg": 15.0, - // Other attributes to update + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.0, + "IsKit": false, + "CreationDate": "2020-01-25T15:51:00", + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": null, + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 1.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": [] } ``` @@ -370,7 +368,7 @@ Activating an SKU means making it available for purchase in your store, allowing - **Image**: The SKU must have at least one image associated with it. Use the [Create SKU file endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file) to associate an image to an SKU. - **Specifications**: If the SKU has [specifications](https://developers.vtex.com/docs/guides/specifications), they must be filled in. - **Kit**: For [kit](https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog/pvt/stockkeepingunitkit) SKUs, at least one component must be active. -- **Product**: The SKU must be associated with an active [product](https://developers.vtex.com/docs/guides/products), which, in turn, must be related to an active [Brand](https://developers.vtex.com/docs/guides/brands) and an active [Category](https://developers.vtex.com/docs/guides/categories). +- **Product**: The SKU must be associated with an active product, which, in turn, must be related to an active [Brand](https://developers.vtex.com/docs/guides/brands) and an active [Category](https://developers.vtex.com/docs/guides/categories). Once the SKU meets these requirements, you can activate it using one of the following methods: [automatic](#automatic-activation) or [manual](#manual-activation). @@ -378,9 +376,15 @@ Once the SKU meets these requirements, you can activate it using one of the foll If your SKU's `IsActive` is set to `false` and `ActivateIfPossible` is set to `true`, your SKU will automatically become active as soon as it is associated with an image or an active component. +Here's an overview of the necessary steps to implement automatic SKU activation: + +1. [Create the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit), setting `IsActive` as `false` and `ActivateIfPossible` as `true`. +2. If the SKU is a kit, [create and associate SKU components](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunitkit). +3. [Create and associate SKU files](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). + -```json Response mark=7:8 +```json Response mark=4:5 { "Id": 1, "ProductId": 310117069, @@ -420,6 +424,13 @@ If your SKU's `IsActive` is set to `false` and `ActivateIfPossible` is set to `t If your SKU's `IsActive` is set to `false` and `ActivateIfPossible` is set to `false`, send a request to the [Update the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-) endpoint, setting `IsActive` as `true`. +Here's an overview of the necessary steps to implement manual SKU activation: + +1. [Create the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit), setting `IsActive` as `false` and `ActivateIfPossible` as `false`. +2. If the SKU is a kit, [create and associate SKU components](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-post-sku-kit). +3. [Create and associate SKU files](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit/-skuId-/file). +4. [Update the SKU](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-) as active, setting `IsActive` as `true`. + ```sh Shell mark=2[17:29],2[90:96],5[31:38],6[33:42],7[10:15] @@ -489,23 +500,69 @@ req.end(); --- -```json Body mark=5 +```json Body mark=4 { - "Id": 70, - "ProductId": 42, - //Set the IsActive attribute to true - "IsActive": true, - "Name": "Size 10", - "PackagedHeight": 15.0, - "PackagedLength": 15.0, - "PackagedWidth": 15.0, - "PackagedWeightKg": 15.0, + "Id": 70, + "ProductId": 42, + "IsActive": true, + "Name": "Size 10", + "RefId": "B096QW8Y8Z", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.0, + "IsKit": false, + "CreationDate": "2020-01-25T15:51:00", + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": null, + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 1.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": [] +} +``` + +```json Response +{ + "Id": 70, + "ProductId": 42, + "IsActive": true, + "Name": "Size 10", + "RefId": "B096QW8Y8Z", + "PackagedHeight": 15.0, + "PackagedLength": 15.0, + "PackagedWidth": 15.0, + "PackagedWeightKg": 15.0, + "Height": null, + "Length": null, + "Width": null, + "WeightKg": null, + "CubicWeight": 0.0, + "IsKit": false, + "CreationDate": "2020-01-25T15:51:00", + "RewardValue": null, + "EstimatedDateArrival": null, + "ManufacturerCode": null, + "CommercialConditionId": 1, + "MeasurementUnit": "un", + "UnitMultiplier": 1.0, + "ModalType": null, + "KitItensSellApart": false, + "Videos": [] } ``` - + >❗ Note that additional configurations are necessary for a product and its SKUs to become visible in a store: > From e682429a8089ed14fa648daf8bf0f9a0ad42dc19 Mon Sep 17 00:00:00 2001 From: Carolina Menezes Date: Wed, 8 Nov 2023 13:17:47 -0300 Subject: [PATCH 11/11] review: add code reviewer suggestions --- ...-a-regular-order-with-the-checkout-api.mdx | 168 ++++++++---------- ...-a-regular-order-using-the-checkout-api.md | 3 + .../catalog-integration/skus.md | 2 + 3 files changed, 80 insertions(+), 93 deletions(-) diff --git a/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx b/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx index 57a1fce577..88880d8a69 100644 --- a/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx +++ b/docs/guides/Checkout/creating-a-regular-order-with-the-checkout-api.mdx @@ -11,15 +11,32 @@ hideTOC: true This step-by-step guide will walk you through the process of using the [Checkout API](https://developers.vtex.com/docs/api-reference/checkout-api) for handling the placement, payment, and delivery aspects of a regular order, with all responsibilities managed within the scope of a single account. This process is divided into the following steps: 1. **Assess cart requirements:** The process begins with the simulation of a cart to assess available delivery and payment options. Additionally, since indicating an email address is necessary to place an order, this step also includes verifying if the provided email is already associated with an existing customer. -2. **Assemble the cart:** After assessing the cart requirements, the next step is to assemble the cart, ensuring that all essential order information is organized according to the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) data structure. +2. **Assemble the cart:** After assessing the cart requirements, the next step is to assemble the cart, ensuring that all essential order information is organized according to the [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) data structure. 3. **Handle the order:** This step involves placing the order on the VTEX platform and sending the necessary payment data to resolve the order payment. 4. **Process and validate the order:** The process ends by processing order details and conducting a verification procedure to confirm the successful placement of the order. - +## Before you begin + +Before proceeding any further, ensure that you have a valid `appKey` and `appToken` granted with the necessary permissions to access the [Checkout](https://developers.vtex.com/docs/api-reference/checkout-api) and [Payments Gateway](https://developers.vtex.com/docs/api-reference/payments-gateway-api) APIs. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. + +> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience on the right side of the screen. + + + +## Step 1 - Assessing cart requirements + +In this step, we will verify if your store can fulfill the cart requirements and gather essential order information to ensure a smooth order placement process in the subsequent steps. + +### Simulating a cart + +This step provides essential information regarding the available delivery and payment options for the specific combination of items in the cart. + +- Send a request to the [Cart simulation](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForms/simulation) API endpoint. Specify the SKU ID (`items.id`), the number of items in the cart (`items.quantity`), the Seller's ID (`items.seller`), and the shipping address country (`country`) in the request body. Also, provide the shipping address's postal code (`postalCode`) or the geo-coordinates (`geoCoordinates`). +- Take note of the `items`, `shippingData.logisticsInfo`, and `paymentData` objects, as we will use this data in the following steps. - + -```shell Shell +```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43],7[11:138] curl --request post \ --url 'https://{accountName}.{environment}.com.br/api/checkout/pub/orderForms/simulation?RnbBehavior=0' \ --header 'Accept: application/json' \ @@ -29,7 +46,7 @@ curl --request post \ --data '{"items":[{"id":"1","quantity":1,"seller":"1"}],"country":"BRA","postalCode":"12345-000","geoCoordinates":[-47.924747467041016]}' ``` -```python Python +```python Python mark=3[37:49],3[51:63],10[25:32],11[27:36],5[12:161] import http.client conn = http.client.HTTPSConnection("{accountName}.{environment}.com.br") @@ -51,7 +68,7 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],5[29:41] +```js Node.js mark=5[15:27],5[29:41],11[25:32],12[27:36],30:33 const http = require("https"); const options = { @@ -89,7 +106,9 @@ req.write(JSON.stringify({ req.end(); ``` -```json Response +--- + +```json Response mark=13,20,25 { "allowManualPrice": boolean, "canEditData": boolean, @@ -124,87 +143,15 @@ req.end(); } ``` -```json orderForm.json -{ - "allowManualPrice": boolean, - "canEditData": boolean, - "clientPreferencesData": {}, - "clientProfileData": {}, - "commercialConditionData": {}, - "customData": {}, - "giftRegistryData": {}, - "hooksData": {}, - "ignoreProfileData": boolean, - "isCheckedIn": boolean, - "itemMetadata": {}, - "items": {}, - "itemsOrdination": {}, - "loggedIn": boolean, - "marketingData": {}, - "messages": [], - "openTextField": {}, - "orderFormId": string, - "paymentData": {}, - "ratesAndBenefitsData": {}, - "salesChannel": "1", - "selectableGifts": {}, - "sellers": {}, - "shippingData": {}, - "storeId": {}, - "storePreferencesData": {}, - "totalizers": {}, - "userProfileId": {}, - "userType": {}, - "value": number -} -``` - - - -## Before you begin - -Before proceeding any further, ensure that you have a valid `appKey` and `appToken` granted with the necessary permissions to access the [Checkout](https://developers.vtex.com/docs/api-reference/checkout-api) and [Payments Gateway](https://developers.vtex.com/docs/api-reference/payments-gateway-api) APIs. For more information, please refer to the [Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) article. - -> ✅ Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. - ---- - -## Step 1 - Assessing cart requirements - -In this step, we will verify if your store can fulfill the cart requirements and gather essential order information to ensure a smooth order placement process in the subsequent steps. - -### Simulating a cart - -This step provides essential information regarding the available delivery and payment options for the specific combination of items in the cart. - -- Send a request to the [`Cart simulation`](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForms/simulation) API endpoint. Specify the SKU ID (`items.id`), the number of items in the cart (`items.quantity`), and the Seller's ID (`items.seller`) in the request body. -- Take note of the `items`, `shippingData.logisticsInfo`, and `paymentData` objects, as we will use this data in the following steps. - - - -```shell Shell mark=2[18:30],2[32:44],5[32:39],6[34:43],7[11:138] -``` - -```python Python mark=3[37:49],3[51:63],10[25:32],11[27:36],5[12:161] -``` - -```js Node.js mark=5[15:27],5[29:41],11[25:32],12[27:36],30:33 -``` - ---- - -```json Response mark=13,20,25 -``` - --- ### Checking for existing customer -This step verifies if the email used to place the order is already related to a customer in your database. This verification serves to not only enhance operational efficiency but also proactively prevent potential permission-related issues. +Now, we will verify whether the email that will be used to place the order is already related to a customer in your database. This verification serves to not only enhance operational efficiency but also proactively prevent potential permission-related issues. -- Send a request to the [`Get client by email`](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles) endpoint to check for existing profiles associated with a specific email address. If the response to this request returns any content, it means the shopper’s information is in your database. In such cases, you can proceed using this data in subsequent steps, sparing the shopper from the need to provide their email again. +- Send a request to the [Get client by email](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles) endpoint to check for existing profiles associated with a specific email address. If the response to this request returns any content, it means the shopper’s information is in your database. In such cases, you can proceed using this data in subsequent steps, sparing the shopper from the need to provide their email again. - If applicable, take note of the `availableAddresses` and `userProfile` objects, as we will use this data in the following steps. @@ -322,9 +269,9 @@ req.end(); ## Step 2 - Assembling the cart -In this step, we will arrange the order details into the specified data format, following the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) data structure. This formatted cart data will be used as the request body in the following steps. +In this step, we will arrange the order details into the specified data format, following the [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) data structure. This formatted cart data will be used as the request body in the following steps. -Below, we will briefly examine the key elements that make up the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields), which include: +Below, we will briefly examine the key elements that make up the [orderForm](https://developers.vtex.com/docs/guides/orderform-fields), which include: - `items` - `clientProfileData` @@ -332,11 +279,43 @@ Below, we will briefly examine the key elements that make up the [`orderForm`](h - `shippingData.logisticsInfo` - `paymentData` -Note that while an `orderForm` can have various elements, a standard order typically consists of the abovementioned ones. +Note that while an `orderForm` can have multiple elements, a standard order typically consists of the ones mentioned above. ```json orderForm.json focus=5,13,25,20 +{ + "allowManualPrice": boolean, + "canEditData": boolean, + "clientPreferencesData": {}, + "clientProfileData": {}, + "commercialConditionData": {}, + "customData": {}, + "giftRegistryData": {}, + "hooksData": {}, + "ignoreProfileData": boolean, + "isCheckedIn": boolean, + "itemMetadata": {}, + "items": {}, + "itemsOrdination": {}, + "loggedIn": boolean, + "marketingData": {}, + "messages": [], + "openTextField": {}, + "orderFormId": string, + "paymentData": {}, + "ratesAndBenefitsData": {}, + "salesChannel": "1", + "selectableGifts": {}, + "sellers": {}, + "shippingData": {}, + "storeId": {}, + "storePreferencesData": {}, + "totalizers": {}, + "userProfileId": {}, + "userType": {}, + "value": number +} ``` @@ -409,7 +388,7 @@ Note that while an `orderForm` can have various elements, a standard order typic ### `clientProfileData`: Existing customers -If the customer already exists in your database, use the `userProfile.email` obtained in the [Checking for existing customer](#checking-for-existing-customer) step to build the `clientProfileData` object. Note that the email address is enough to register the order to the shopper’s existing account. +If the customer already exists in your database, use the `userProfile.email` obtained in the [Checking for existing customer](#checking-for-existing-customer) step to build the `clientProfileData` object. The email address is enough to register the order to the shopper’s existing account. @@ -467,7 +446,7 @@ If the customer already exists in your database, use the `userProfile.email` obt ### `shippingData.address`: Existing customers -If the customer already exists in your database, use the desired `addressId` obtained from the [Checking for existing customer](#checking-for-existing-customer) step to build the `shippingData.address` block. +If the customer already exists in your database, use the desired `availableAddresses[i].addressId` obtained from the [Checking for existing customer](#checking-for-existing-customer) step to build the `shippingData.address` block. @@ -686,7 +665,7 @@ For returning customers, the `orderForm` for your order should resemble this str ### Placing the order -Send a request to the [`Place order`](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) endpoint using the `orderForm` you built as the request body. +Send a request to the [Place order](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders) endpoint using the `orderForm` you built as the request body. Upon receiving a `201 Created` response, take note of these four pieces of information: @@ -855,16 +834,17 @@ In this step, we will communicate the necessary payment data to VTEX for the fin -```shell Shell mark=2[17:29],2[72:86],2[105:113],4[31:38],5[33:42],6[10:407] +```shell Shell mark=2[17:29],2[72:86],2[105:113],5[31:38],6[33:42],7[10:407] curl --request post \ --url 'https://{accountName}.vtexpayments.com.br/api/pub/transactions/{transactionId}/payments?orderId={orderId}' \ + --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-VTEX-API-AppKey: {appKey}' \ --header 'X-VTEX-API-AppToken: {appToken}' \ --data '[{"paymentSystem":4,"installments":1,"currencyCode":"BRL","value":100,"installmentsInterestRate":0,"installmentsValue":100,"referenceValue":100,"fields":{"holderName":"UserTest","cardNumber":"5378244888889174","validationCode":"231","dueDate":"10/19","document":"8041734561","accountId":"","address":null,"callbackUrl":""},"transaction":{"id":"{{transactionId}}","merchantName":"{{accountName}}"}}]' ``` -```python Python mark=3[37:49],9[25:32],10[27:36],13[45:59],13[78:86] +```python Python mark=3[37:49],10[25:32],11[27:36],14[45:59],14[78:86] import http.client conn = http.client.HTTPSConnection("{accountName}.vtexpayments.com.br") @@ -872,6 +852,7 @@ conn = http.client.HTTPSConnection("{accountName}.vtexpayments.com.br") payload = "[{\"paymentSystem\":4,\"installments\":1,\"currencyCode\":\"BRL\",\"value\":100,\"installmentsInterestRate\":0,\"installmentsValue\":100,\"referenceValue\":100,\"fields\":{\"holderName\":\"UserTest\",\"cardNumber\":\"5378244888889174\",\"validationCode\":\"231\",\"dueDate\":\"10/19\",\"document\":\"8041734561\",\"accountId\":\"\",\"address\":null,\"callbackUrl\":\"\"},\"transaction\":{\"id\":\"{{transactionId}}\",\"merchantName\":\"{{accountName}}\"}}]" headers = { + 'Accept': "application/json", 'Content-Type': "application/json", 'X-VTEX-API-AppKey': "{appKey}", 'X-VTEX-API-AppToken': "{appToken}" @@ -885,7 +866,7 @@ data = res.read() print(data.decode("utf-8")) ``` -```js Node.js mark=5[15:27],10[25:32],11[27:36],29:48,7[33:47],7[66:74] +```js Node.js mark=5[15:27],11[25:32],12[27:36],30:49,8[33:47],8[66:74] const http = require("https"); const options = { @@ -894,6 +875,7 @@ const options = { "port": null, "path": "/api/pub/transactions/{transactionId}/payments?orderId={orderId}", "headers": { + "Accept": "application/json", "Content-Type": "application/json", "X-VTEX-API-AppKey": "{appKey}", "X-VTEX-API-AppToken": "{appToken}" @@ -952,7 +934,7 @@ req.end(); In this final step, we will process the order. -- Send a request to the [Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-) endpoint. If the payment is processed without any issues, the order should be successfully placed; otherwise, a `status 500` error might occur. +- Send a request to the [Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-) endpoint. If the payment is processed without any issues, the order should be successfully placed. Otherwise, a `status 500` error might occur. > Note that this process uses the gateway connectors configured in your VTEX environment. Be careful to prevent any unwanted charges or unexpected payment denials. @@ -1034,7 +1016,7 @@ req.end(); ### Verifying the order placement -Finally, you can confirm if your order was correctly placed by checking the [Order management](https://help.vtex.com/en/tutorial/orders-list--tutorials_200#) in VTEX Admin. Alternatively, you can use the [Get order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-) and [List orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders) endpoints for this purpose. +Finally, you can confirm if your order was correctly placed by checking the [Order management](https://help.vtex.com/en/tutorial/all-orders--2QTduKHAJMFIZ3BAsi6Pi) in VTEX Admin. Alternatively, you can use the [Get order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-) and [List orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders) endpoints for this purpose. @@ -1107,4 +1089,4 @@ req.end(); - + diff --git a/docs/guides/Checkout/orders-2/create-a-regular-order-using-the-checkout-api.md b/docs/guides/Checkout/orders-2/create-a-regular-order-using-the-checkout-api.md index 971d5899c6..ca699990b3 100644 --- a/docs/guides/Checkout/orders-2/create-a-regular-order-using-the-checkout-api.md +++ b/docs/guides/Checkout/orders-2/create-a-regular-order-using-the-checkout-api.md @@ -6,8 +6,11 @@ createdAt: "2021-10-25T23:13:41.287Z" updatedAt: "2022-10-27T18:56:50.737Z" --- There are different ways of using VTEX APIs to handle shopping carts and checkout in order to place orders. For instance, you can use API requests to [create](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm) and [manage](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/shippingData) shopping carts on the VTEX platform, so as to place an order from that information later, or directly place an order with a single request containing all cart data. + > ℹ️️ The main data structure used in VTEX Checkout is the `orderForm`. It contains every piece of information pertinent to a shopping cart, including logistics, payment, products and customer profile, for instance. Learn more in the [orderForm documentation.](https://developers.vtex.com/docs/guides/orderform-fields) +> ✅ Try the interactive version of this article by accessing this [link](https://developers.vtex.com/docs/guides/creating-a-regular-order-with-the-checkout-api). Code will be highlighted and focused for your convenience. + For this tutorial, we chose one of the more objective ways to understand and use our APIs to place a regular order (placed, paid, and delivered under the liability of a single account). To do this, we will follow these steps: 1. [Simulate a cart](https://developers.vtex.com/docs/guides/create-a-regular-order-using-the-checkout-api#1-simulate-a-cart). diff --git a/docs/guides/Integration-Guides/catalog-integration/skus.md b/docs/guides/Integration-Guides/catalog-integration/skus.md index 3d5c7212bf..b8271eaf6d 100644 --- a/docs/guides/Integration-Guides/catalog-integration/skus.md +++ b/docs/guides/Integration-Guides/catalog-integration/skus.md @@ -10,6 +10,8 @@ A [Stock Keeping Unit (SKU)](https://help.vtex.com/en/tracks/catalog-101--5AF0Xf Once you have created a product, it is time to submit its respective SKUs. +> ✅ Try the interactive version of this article by accessing this [link](https://developers.vtex.com/docs/guides/managing-skus). Code will be highlighted and focused for your convenience. + ## Creating an SKU To create a new SKU, use the [Create SKU endpoint](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/stockkeepingunit).