Este documento tiene como objetivo auxiliar en la integración de las informaciones existentes en el catálogo de una tienda VTEX con algún servicio externo.
Entre los casos de uso más comunes para esa integración, tenemos:
- Integrar el catálogo de la tienda VTEX con marketplaces externos.
- Enviar los datos de catálogo para herramientas de BI.
- Generar informes externos utilizando la información del catálogo.
Siga los pasos a continuación para realizar la integración.
Crear un afiliado
El afiliado funciona como un webhook que notificará el servicio externo sobre los cambios realizados en la información de un SKU, cambios en el inventario o cambios en los precios.
- En el menú lateral del Admin, haga clic en Gestión de pedidos.
- Haga clic en Configuración
- Haga clic en la pestaña Afiliados.
- Haga clic en el botón Nuevo afiliado.
- Rellene los campos según se describe a continuación.
- Haga clic en Guardar.
Llenar los campos del panel Nuevo Afiliado
- Nombre: Rellene con el nombre del sistema afiliado.
- ID: Código de identificación del afiliado de 3 dígitos. El ID debe contener apenas consonantes.
- Política Comercial: ID de la política comercial que tendrá su información enviada al afiliado.
- E-mail de Follow Up: Dirección de correo electrónico que recibirá información cuando el afiliado sea notificado.
- Endpoint de Search: URL de la aplicación que recibirá notificaciones sobre los SKUs, sus precios y sus stocks. Esta URL debe ser desarrollada por el sistema externo para que VTEX pueda notificar los cambios en esta ruta.
- Versión del Endpoint de Search: Mantenga este campo rellenado con la información 1.x.x
- Usar mi medio de pago: Si tiene sentido para su integración que el servicio externo reciba las informaciones de medios de pago de su tienda, marque esta flag.
Realizar la primera carga con los datos de los SKUs
Después de crear el endpoint que recibirá la información de los productos y haber configurado correctamente el afiliado, usted debe realizar una primera carga para obtener los datos del catálogo y guardarlos en la base de datos de su servicio externo. Para ello, siga las instrucciones que aparecen a continuación.
1 - Obtener los datos de ID de los SKUs de su tienda
Haga um GET en la ruta http://{accountName}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitids?page={page}&pagesize={page_size} para obtener como respuesta un array con los IDs de los SKUs existentes en su tienda.
Parámetros de la API:
{accountName}: Nombre de la cuenta de su tienda en VTEX.
{page}: En qué página se está haciendo el request. Usted debe pasar por todas las páginas hasta que la respuesta del request sea un array vacío ([]).
{page_size}: La cantidad de identificadores de SKU que se devuelven por página. Recomendamos devolver un máximo de 1000 IDs por página.
Ejemplo de respuesta:
[ 1 2 3 4, 5, 6, 7, 8, 9, 10]
2 - Obtener los datos sobre las propiedades de los SKUs
Utilizando los IDs de los SKUs obtenidos en el request anterior, usted debe hacer un GET en la ruta http://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitbyid/{{skuId}} para obtener información sobre las propiedades de los SKUs. La respuesta de este request devolverá la información que caracteriza el SKU, como Nombre, Marca, Categoría, Coleciones, Imagen, si el SKU está Activo o Inactivo y Políticas Comerciales, por ejemplo. La información de precio y de stock aún no se obtiene en esta etapa.
Parámetros de la API:
{{accountName}}: Nombre de la cuenta de su tienda en VTEX.
{{skuId}}: ID del SKU que se va a consultar.
Ejemplo de respuesta:
{ "Id": 20, "ProductId": 18, "NameComplete": "Newest Iron 220", "ProductName": "Newest Iron", "ProductDescription": "Newest iron", "TaxCode": "", "SkuName": "220", "IsActive": true, "IsTransported": true, "IsInventoried": true, "IsGiftCardRecharge": false, "ImageUrl": "http://worldshopping.vteximg.com.br/arquivos/ids/155438-55-55/image-5a949c715cf84a7e9cac11cb745bfba9.jpg?v=636633199310730000", "DetailUrl": "/newest-iron-18/p", "CSCIdentification": null, "BrandId": "2000000", "BrandName": "Brand name", "Dimension": { "cubicweight": 0.0002, "height": 1, "length": 1, "weight": 1, "width": 1 }, "RealDimension": { "realCubicWeight": 0, "realHeight": 0, "realLength": 0, "realWeight": 0, "realWidth": 0 }, "ManufacturerCode": null, "IsKit": false, "KitItems": [], "Services": [], "Categories": [], "Attachments": [], "Collections": [], "SkuSellers": [ { "SellerId": "1", "StockKeepingUnitId": 20, "SellerStockKeepingUnitId": "20", "IsActive": true, "FreightCommissionPercentage": 0, "ProductCommissionPercentage": 0 }, { "SellerId": "jbsusaqa", "StockKeepingUnitId": 20, "SellerStockKeepingUnitId": "888898", "IsActive": true, "FreightCommissionPercentage": 0, "ProductCommissionPercentage": 10 } ], "SalesChannels": [ 1, 2, 3, 4, 5, 6 ], "Images": [ { "ImageUrl": "http://worldshopping.vteximg.com.br/arquivos/ids/155438/image-5a949c715cf84a7e9cac11cb745bfba9.jpg?v=636633199310730000", "ImageName": null, "FileId": 155438 } ], "SkuSpecifications": [], "ProductSpecifications": [], "ProductClustersIds": "137,139", "ProductCategoryIds": "/1/2/", "ProductGlobalCategoryId": 783, "ProductCategories": { "1": "Choir & Voice", "2": "For Men" }, "CommercialConditionId": 1, "RewardValue": 0, "AlternateIds": { "RefId": "888898" }, "AlternateIdValues": [ "888898" ], "EstimatedDateArrival": null, "MeasurementUnit": "un", "UnitMultiplier": 1, "InformationSource": "Indexer", "ModalType": null}
3 - Obtener los datos de precio y stock de los SKUs
En el caso de que se produzca un error en el sistema, se debe hacer un POST en la ruta https://{accountName}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={salesChannel}&affiliateId={affiliateId} para obtenerse los datos de precio, stock y SLA de entrega de los SKUs. Esta llamada simula un carrito en el Checkout de VTEX, devolviendo la información más actualizada de precio, stock y SLA de entrega.
Parámetros de la API:
{accountName}: Nombre de la cuenta de su tienda en VTEX.
{salesChannel}: Política comercial a considerar en la simulación.
{afiliadoId}: ID del afiliado a ser considerado en el contexto de la simulación.
Ejemplo de BODY que se rellenará en el POST:
{ "postalCode":"10019", //required field if the country field is filled "country":"USA", //required field if postalCode is filled "items": [ //required field: must contain at least one item { "id":"23", //required field (string): SKU id you want to use in the simulation "quantity":1, //required field (int): quantity of the item you want to simulate "seller":"1" //id of the main store: always use the value 1 }, { "id":"25", "quantity":2, "seller":"1" } ]}
Ejemplo de respuesta:
{ "items": [ { "id": "23", "requestIndex": 0, "quantity": 0, "seller": "1", "merchantName": null, "priceValidUntil": "2019-08-17T19:40:26Z", "price": 13900, "listPrice": 15900, "offerings": [], "priceTags": [], "measurementUnit": "kg", "unitMultiplier": 1.5, "attachmentOfferings": [] } ], "postalCode": "10019", "geoCoordinates": [], "country": "USA", "logisticsInfo": [ { "itemIndex": 0, "addressId": null, "selectedSla": null, "selectedDeliveryChannel": null, "stockBalance": 0, "quantity": 0, "shipsTo": [ "USA", "ROU", "BRA", "GBR" ], "slas": [], "deliveryChannels": [] } ], "pickupPoints": [], "messages": []}
Combinando los tres tipos de request mostrados arriba, usted será capaz de realizar la primera carga de datos del catálogo de VTEX para grabar en la base de datos de un servicio externo.
Actualizar los datos de los SKUs
En caso de cambios en algún producto, VTEX notificará al endpoint del afiliado sobre la información de todos los SKUs del producto modificado, incluso si uno de los SKUs no ha cambiado, realizando un POST. A continuación se muestra un ejemplo del payload enviado por VTEX al endpoint:
{ "IdSku": "15", // ID de SKU "An": "accountname", // Account Name "IdAffiliate": "SPT", // Affiliate Id "DateModified": "2018-08-20T15: 11: 28.1978783Z", // Fecha de modificación "IsActive": false, // Indica el status del SKU, si está activo o inactivo "StockModified": false, // Indica si se ha modificado la acción del SKU "PriceModified": false, // Indica si se ha modificado el precio del SKU "HasStockKeepingUnitModified": true, // Indica si alguna información del SKU se ha cambiado (con excepción de precio y stock) "HasStockKeepingUnitRemovedFromAffiliate": false // Indica si el SKU se ha eliminado del afiliado}
Recibiendo este payload, el integrador debe utilizar esta información para decidir qué llamadas debe hacer para actualizar la información de los SKU:
- Si se ha producido un cambio de precio o de stock, el integrador debe llamar a la ruta
https://{accountName}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={salesChannel}&affiliateId={affiliateId}, como se describe en la sección Obtener los datos de precio y stock de los SKUs. - Si se ha producido un cambio en el SKU que no sea de precio o de stock, el integrador debe llamar a la ruta
http://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitbyid/{{skuId}}, como se describe en la sección Obtener los datos sobre las propiedades de los SKUs.
Si se inserta un nuevo SKU en el catálogo, se le notificará en el endpoint de cada afiliado. Por tratarse de un nuevo SKU, es necesario realizar el llenado de los datos de este nuevo SKU en la base de datos del servicio externo. El integrador debe comprobar si el SKU notificado aún no existe en la base de datos del servicio externo. Si se trata de un nuevo SKU, el integrador debe seguir los mismos pasos descritos en la sección Realizar la primera carga con los datos de SKUs. Si es un SKU ya existente, el integrador debe seguir los pasos de la sección Actualizar los datos de SKUs.
Si desea integrar las formas de pago de un seller VTEX con un marketplace externo, acceda a nuestra documentación.