{"section":"tutorials","requestedLocale":"pt","requestedSlug":"guia-de-integracao-consumir-as-informacoes-do-catalogo","locale":"pt","slug":"guia-de-integracao-consumir-as-informacoes-do-catalogo","path":"docs/pt/tutorials/integrações/visão-geral-de-integrações/guia-de-integracao-consumir-as-informacoes-do-catalogo.md","branch":"main","content":"Este documento tem por objetivo auxiliar na integração das informações existentes no Catálogo de uma loja VTEX com algum serviço externo.\n\nEntre os casos de uso mais comuns para essa integração, temos:\n\n1. Integrar o catálogo da loja VTEX com marketplaces externos.\n2. Enviar os dados de catálogo para ferramentas de BI.\n3. Gerar relatórios externos utilizando as informações do catálogo.\n\nSiga os passos abaixo para realizar a integração.\n\n## Criar um afiliado\n\nO afiliado funciona como um webhook que irá notificar o serviço externo sobre mudanças feitas nas informações de um SKU, mudanças em estoque ou mudanças em preços.\n\n1. No menu lateral do admin, clique em __Gerenciamento de pedidos__.\n2. Clique em __Configurações__.\n3. Clique na aba __Afiliados__.\n4. Clique no botão __Novo afiliado__.\n5. Preencha os campos conforme descritos abaixo.\n6. Clique em __Salvar__.\n\n### Preencher os campos do painel de Novo Afiliado\n\n- __Nome__: Preencha com o nome do sistema afiliado.\n- __ID__: Código de identificação do afiliado com 3 dígitos. O ID deve conter __apenas consoantes__.\n- __Política Comercial__: ID da política comercial que terá suas informações enviadas para o afiliado.\n- __E-mail de Follow Up__: Endereço de e-mail que receberá informações quando o afiliado for notificado.\n- __Endpoint de Search__: URL da aplicação que [receberá notificações](#atualizar-os-dados-dos-skus) sobre os SKUs, seus preços e seus estoques. Esta URL deverá ser desenvolvida pelo sistema externo para que a VTEX possa notificar as alterações nesta rota.\n- __Versão do Endpoint de Search__: Mantenha este campo preenchido com a informação __1.x.x__.\n- __Usar meu meio de pagamento__: Caso faça sentido para a sua integração que o serviço externo receba as informações de meios de pagamento da sua loja, marque esta flag. \n\n## Realizar a primeira carga com os dados dos SKUs\n\nApós ter criado o Endpoint que receberá as informações dos produtos e ter configurado corretamente o afiliado, você deverá realizar uma primeira carga para obter os dados do Catálogo e salvá-los no banco de dados do seu serviço externo. Para isso, siga as instruções abaixo.\n\n### 1 - Obter os dados de ID dos SKUs da sua loja\n\nFaça um `GET` na rota `http://{accountName}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitids?page={page}&pagesize={page_size}` para obter como resposta um array com os ids dos SKUs existentes na sua loja.\n\n__Parâmetros da API__:\n\n`{accountName}`: Nome da conta da sua loja na VTEX.\n\n`{page}`: Em qual página está sendo feita a requisição. Você deve passar por todas as páginas até que a resposta da requisição seja um array vazio (`[]`).\n\n`{page_size}`: A quantidade de ids de SKUs a ser retornada por página. Recomendamos retornar, no máximo, 1000 ids por página.\n\n__Exemplo de resposta__:\n\n```json\n[\n    1,\n    2,\n    3,\n    4,\n    5,\n    6,\n    7,\n    8,\n    9,\n    10\n]\n```\n\n### 2 - Obter os dados sobre as propriedades dos SKUs\n\nUtilizando os IDs dos SKUs obtidos na requisição anterior, você deve fazer um `GET` na rota `http://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitbyid/{{skuId}}` para obter as informações sobre as propriedades dos SKUs. A resposta deste request irá retornar as informações que caracterizam o SKU, como __Nome__, __Marca__, __Categoria__, __Coleções__, __Imagem__, se o SKU está __Ativo ou Inativo__ e __Políticas Comerciais__, por exemplo. As informações de preço e estoque ainda não são obtidas nesta etapa. \n\n__Parâmetros da API__:\n\n`{accountName}`: Nome da conta da sua loja na VTEX.\n\n`{{skuId}}`: ID do SKU a ser consultado.\n\n__Exemplo de resposta__:\n\n```\n{\n    \"Id\": 20,\n    \"ProductId\": 18,\n    \"NameComplete\": \"Newest Iron 220\",\n    \"ProductName\": \"Newest Iron\",\n    \"ProductDescription\": \"Newest iron\",\n    \"TaxCode\": \"\",\n    \"SkuName\": \"220\",\n    \"IsActive\": true,\n    \"IsTransported\": true,\n    \"IsInventoried\": true,\n    \"IsGiftCardRecharge\": false,\n    \"ImageUrl\": \"http://worldshopping.vteximg.com.br/arquivos/ids/155438-55-55/image-5a949c715cf84a7e9cac11cb745bfba9.jpg?v=636633199310730000\",\n    \"DetailUrl\": \"/newest-iron-18/p\",\n    \"CSCIdentification\": null,\n    \"BrandId\": \"2000000\",\n    \"BrandName\": \"Brand name\",\n    \"Dimension\": {\n        \"cubicweight\": 0.0002,\n        \"height\": 1,\n        \"length\": 1,\n        \"weight\": 1,\n        \"width\": 1\n    },\n    \"RealDimension\": {\n        \"realCubicWeight\": 0,\n        \"realHeight\": 0,\n        \"realLength\": 0,\n        \"realWeight\": 0,\n        \"realWidth\": 0\n    },\n    \"ManufacturerCode\": null,\n    \"IsKit\": false,\n    \"KitItems\": [],\n    \"Services\": [],\n    \"Categories\": [],\n    \"Attachments\": [],\n    \"Collections\": [],\n    \"SkuSellers\": [\n        {\n            \"SellerId\": \"1\",\n            \"StockKeepingUnitId\": 20,\n            \"SellerStockKeepingUnitId\": \"20\",\n            \"IsActive\": true,\n            \"FreightCommissionPercentage\": 0,\n            \"ProductCommissionPercentage\": 0\n        },\n        {\n            \"SellerId\": \"jbsusaqa\",\n            \"StockKeepingUnitId\": 20,\n            \"SellerStockKeepingUnitId\": \"888898\",\n            \"IsActive\": true,\n            \"FreightCommissionPercentage\": 0,\n            \"ProductCommissionPercentage\": 10\n        }\n    ],\n    \"SalesChannels\": [\n        1,\n        2,\n        3,\n        4,\n        5,\n        6\n    ],\n    \"Images\": [\n        {\n            \"ImageUrl\": \"http://worldshopping.vteximg.com.br/arquivos/ids/155438/image-5a949c715cf84a7e9cac11cb745bfba9.jpg?v=636633199310730000\",\n            \"ImageName\": null,\n            \"FileId\": 155438\n        }\n    ],\n    \"SkuSpecifications\": [],\n    \"ProductSpecifications\": [],\n    \"ProductClustersIds\": \"137,139\",\n    \"ProductCategoryIds\": \"/1/2/\",\n    \"ProductGlobalCategoryId\": 783,\n    \"ProductCategories\": {\n        \"1\": \"Choir & Voice\",\n        \"2\": \"For Men\"\n    },\n    \"CommercialConditionId\": 1,\n    \"RewardValue\": 0,\n    \"AlternateIds\": {\n        \"RefId\": \"888898\"\n    },\n    \"AlternateIdValues\": [\n        \"888898\"\n    ],\n    \"EstimatedDateArrival\": null,\n    \"MeasurementUnit\": \"un\",\n    \"UnitMultiplier\": 1,\n    \"InformationSource\": \"Indexer\",\n    \"ModalType\": null\n}\n```\n\n### 3 - Obter os dados de preço e estoque dos SKUs\n\nAinda utilizando os ids obtidos na primeira requisição, você deve fazer um `POST` na rota `https://{accountName}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={salesChannel}&affiliateId={affiliateId}` para obter os dados de __preço, estoque e SLA de entrega__ dos SKUs. Esta chamada simula um carrinho no Checkout da VTEX, retornando as informações mais atualizadas de preço, estoque e SLA de entrega.\n\n__Parâmetros da API__:\n\n`{accountName}`: Nome da conta da sua loja na VTEX.\n\n`{salesChannel}`: Política Comercial a ser considerada na simulação.\n\n`{affiliateId}`: Id do afiliado a ser considerado no contexto da simulação.\n\n__Exemplo de BODY a ser preenchido no POST__:\n\n```\n{\n    \"postalCode\":\"10019\", //required field if the country field is filled\n    \"country\":\"USA\",      //required field if postalCode is filled\n    \"items\": [            //required field: must contain at least one item\n        {\n            \"id\":\"23\",    //required field (string): SKU id you want to use in the simulation\n            \"quantity\":1, //required field (int): quantity of the item you want to simulate\n            \"seller\":\"1\"  //id of the main store: always use the value 1\n        },\n        {\n            \"id\":\"25\",\n            \"quantity\":2,\n            \"seller\":\"1\"\n        }\n    ]\n}\n```\n\n__Exemplo de resposta__:\n\n```\n{\n    \"items\": [\n        {\n            \"id\": \"23\",\n            \"requestIndex\": 0,\n            \"quantity\": 0,\n            \"seller\": \"1\",\n            \"merchantName\": null,\n            \"priceValidUntil\": \"2019-08-17T19:40:26Z\",\n            \"price\": 13900,\n            \"listPrice\": 15900,\n            \"offerings\": [],\n            \"priceTags\": [],\n            \"measurementUnit\": \"kg\",\n            \"unitMultiplier\": 1.5,\n            \"attachmentOfferings\": []\n        }\n    ],\n    \"postalCode\": \"10019\",\n    \"geoCoordinates\": [],\n    \"country\": \"USA\",\n    \"logisticsInfo\": [\n        {\n            \"itemIndex\": 0,\n            \"addressId\": null,\n            \"selectedSla\": null,\n            \"selectedDeliveryChannel\": null,\n            \"stockBalance\": 0,\n            \"quantity\": 0,\n            \"shipsTo\": [\n                \"USA\",\n                \"ROU\",\n                \"BRA\",\n                \"GBR\"\n            ],\n            \"slas\": [],\n            \"deliveryChannels\": []\n        }\n    ],\n    \"pickupPoints\": [],\n    \"messages\": []\n}\n```\n\nCombinando os três tipos de request exibidos acima, você será capaz de realizar a __primeira carga__ de dados do Catálogo da VTEX para gravar na base de dados de um serviço externo.\n\n## Atualizar os dados dos SKUs\n\nCaso ocorram mudanças em algum produto, a VTEX irá notificar o Endpoint do afiliado sobre as informações de __todos os SKUs do produto alterado, mesmo que um dos SKUs não tenha sofrido alteração,__ realizando um POST. Segue abaixo um exemplo do payload enviado pela VTEX para o Endpoint:\n\n```json\n{\n  \"IdSku\": \"15\", //Id do SKU\n  \"An\": \"accountname\", //Account Name\n  \"IdAffiliate\": \"SPT\", //Affiliate Id\n  \"DateModified\": \"2018-08-20T15:11:28.1978783Z\", //Data de modificação\n  \"IsActive\": false, //Indica o status do SKU, se está ativo ou inativo\n  \"StockModified\": false, //Indica se o estoque do SKU foi modificado\n  \"PriceModified\": false, //Indica se o preço do SKU foi modificado\n  \"HasStockKeepingUnitModified\": true, //Indica se alguma informação do SKU foi mudada (com exceção de preço e estoque)\n  \"HasStockKeepingUnitRemovedFromAffiliate\": false //Indica se o SKU foi removido do afiliado\n}\n```\n\nRecebendo este payload, o integrador deve utilizar estas informações para decidir quais chamadas deverá fazer para atualizar as informações dos SKUs:\n\n- Caso tenha ocorrido alteração de preço ou estoque, o integrador deve chamar a rota `https://{accountName}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={salesChannel}&affiliateId={affiliateId}`, conforme descrito na seção [Obter os dados de preço e estoque dos SKUs](#3-obter-os-dados-de-preco-e-estoque-dos-skus).\n- Caso tenha ocorrido uma alteração no SKU que não seja de preço ou estoque, o integrador deve chamar a rota `http://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitbyid/{{skuId}}`, conforme descrito na seção [Obter os dados sobre as propriedades dos SKUs](#2-obter-os-dados-sobre-as-propriedades-dos-skus).\n\n> ⚠️ Caso um novo SKU seja inserido no Catálogo, ele será notificado no Endpoint de cada afiliado. Por se tratar de um novo SKU, é necessário realizar o preenchimento dos dados deste novo SKU na base de dados do serviço externo. O integrador deve verificar se o SKU notificado se trata de um SKU que ainda não existe na base de dados do serviço externo. Caso se trate de um novo SKU, o integrador deve seguir os mesmos passos descritos na seção **Realizar a primeira carga com os dados dos SKUs**. Caso seja um SKU já existente, o integrador deve seguir os passos da seção **Atualizar os dados dos SKUs**\n\n> ℹ️ Caso queira integrar as formas de pagamento de um seller VTEX com um marketplace externo, [acesse nossa documentação](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-guide)."}