ESSE É UM FAQ PARA USO EXCLUSIVAMENTE INTERNO.
Este guia tem como objetivo indicar soluções para problemas que podem surgir na Integração com a B2W. Este artigo é dividido em 2 seções "Anúncios/Produtos" e "Pedidos"
Anúncios/Produtos
Estoque/Preço não estão sendo atualizados (como investigar)
O Fluxo de atualização de preço e estoque nos marketplaces é:
Cliente altera estoque/preço no catálogo/pricing -> catálogo/pricing notifica o Broadcaster -> Broadcaster notifica a integração -> integração altera o estoque/preço no marketplace.
- Primeira metade do fluxo = Merch
- Segunda metade = Channels
É necessário investigar cada passo para identificar a falha no fluxo.
- Cliente altera estoque/preço no catálogo/pricing:
Se for estoque, verificar histórico de alteração da informação no admin.
Se for preço, verificar histórico de alteração da informação no splunk:
Assim, obter a informação de data e hora da última atualização de informação.
2. Catálogo/Pricing notifica o Broadcaster:
O Broadcaster (ou ccnotificator) é o sub-sistema responsável por distribuir e disparar notificações sobre alguma alteração de produto, preço ou estoque à cada um dos afiliados. Para que ele dispare essas informações, é necessário que ele seja notificado de alguma alteração ocorreu.
Sendo assim, é necessário pesquisar pelo log de notificação no splunk.
Se for estoque, pesquisar pela seguinte query:
index=ccnotificator account={{accountName}} workflow_instance={{idSku}} workflow_type=EnqueueStockChangeNotification
Se for preço, pesquisar pela seguinte query:
index=ccnotificator account={{accountName}} workflow_instance={{idSku}} workflow_type=EnqueuePriceChangeNotification
- Caso na data e hora em que houve a última alteração da informação (passo 1) não houver um log de notificação, a falha no fluxo deve ser tratada com o time de Merch.
3. Broadcaster notifica a integração:
Após o broadcaster ser notificado de que houve uma alteração de informação, é necessário que ele repasse essa informação para todos os afiliados.
Portanto, é preciso verificar se há logs no splunk de que essa informação foi repassada.
Se for estoque, pesquisar pela seguinte query:
index=ccnotificator account={{accountName}} {{affiliateID}} workflow_instance={{idSku}} workflow_type=NotifyAffiliatesAboutInventoryChangeAsync
Se for preço, pesquisar pela seguinte query:
index=ccnotificator account={{accountName}} workflow_instance={{idSku}} workflow_type=NotifyAffiliatesAboutPriceChangeAsync
- Caso esse log esteja com a mensagem de erro “Ocorreu um erro de comunicação com o catálogo de produtos. Acesso não autorizado do seller 1 para o sales channel “x”.” é necessário verificar o binding para a política comercial cadastrada no marketplace (tanto da account quanto da subaccount).
- Caso esse log esteja apontando para um endpoint diferente de “http://skyhubintegration.vtexinternal.com/api/skyhubintegration/commercialcondition?an={{accountName}} é necessário ajustar para esse endpoint, provavelmente o cliente fez alguma alteração manual.
- Caso esse log esteja com algum erro não identificável, a falha no fluxo deve ser tratada com o time de Channels, sendo imprescindível constar no ticket a query utilizada no splunk e o erro identificado
4. Integração altera o estoque/preço no marketplace:
Considerando que o passo 3 tenha sido realizado com sucesso no fluxo, é necessário verificar agora se a integração realizou a alteração necessária no marketplace.
Para o caso da Skyhub, é preciso verificar nos logs do splunk o envio dessa informação:
Se for estoque ou preço, pesquisar pela seguinte query:
index=skyhubintegration account={{accountName}} workflow_instance={{skuId}} workflow_type=ExportProductAsync
- Caso esse log não exista ou esteja com um erro não identificável, a falha no fluxo deve ser tratada com o time de Channels, sendo imprescindível constar no ticket a query utilizada no splunk
- Caso esse log esteja com um valor diferente do cadastrado no admin da VTEX ou no módulo de Pricing, é necessário realizar uma simulação de fulfillment para analisar quais as informações de estoque e preço estão sendo repassadas para a integração , pois a integração utiliza a informação retornada pela simulação de fullfilment para consultar os valores de estoque e preço que serão enviados ao marketplace.
API de fulfillment:
- Se a simulação de fulfillment retornar o valor que a integração enviou, então esse é o valor realmente cadastrado no sku. É necessário entender com o time de Checkout o motivo da divergência de valores.
- Se a simulação de fulfillment retornar um valor diferente do que a integração enviou, então é porque houve uma mudança recente nos valores do sku. Para atualizar a informação, basta realizar uma mudança no sku para que ele seja atualizado novamente no marketplace.
Skus não são enviados. Mensagem de erro no splunk: “O usuário não pertence a conta informada”.
Verificar com o cliente se todas as informações cadastradas no card bridge estão em conformidade com a Skyhub. Exemplos: E-mail de Acesso da Skyhub e Chave de Acesso da Skyhub (Access_token).
Skus não são enviados. Mensagem de erro no splunk: “Ocorreu um erro de comunicação com o catálogo de produtos. Acesso não autorizado do seller 1 para o sales channel “x”.”
É necessário verificar o binding para a política comercial cadastrada no marketplace (tanto da account quanto da subaccount).
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Pedidos
Erro de atualização de Tracking. Mensagem de erro: “Pedido {Númerodopedido} com chave da nota inválida…”
A chave da nota corresponde ao campo InvoiceKey na API de Get order do OMS. Esse campo é preenchido pelo próprio cliente e o pedido só segue o fluxo se estiver com esse valor válido. Esse valor deve conter 44 caracteres.
Erro de atualização de Tracking. Mensagem de erro: “Order skipped all the possible flux”.
Essa mensagem ocorre quando o cliente segue com a atualização de forma manual do lado da própria B2W. Dessa forma, ao fazer um GET do pedido, quando recebe as informações do OMS para atualização de status, a integração entende que não há mais status para ser atualizado, logando a mensagem de que o pedido já seguiu todo seu fluxo.
Algumas vezes a integração recebe duas vezes (quase ao mesmo tempo) a notificação de invoice do OMS, fazendo com que tenha dois logs seguidos de invoice, shipped e delivered. Isso também é motivo para aparecer essa mensagem de erro, mas não necessariamente o pedido estará com o status errado no marketplace, pois o primeiro log irá atualizar o status e na consulta do segundo log a integração recebe que o status já está "o mais atualizado possível" para o momento.
Pedido não integra. Mensagem de erro: “O item {{NomedoSku}} não está mais disponível” OU “O SLA não está disponível”.
A integração sempre que identifica um novo pedido no marketplace que deve ser integrado para a loja realiza uma simulação de fulfillment, com o objetivo de selecionar o SLA do pedido, antes de efetivamente criar o pedido. Nesse momento, se a simulação retornar que o sku não possui estoque, está indisponível ou que não há SLA disponível para aquele item naquele CEP o pedido não será criado na loja e a integração irá logar um erro no bridge.
Para validar se o erro persiste, é necessário clicar em “Reprocessar pedido”. Caso o erro continue, para analisar o motivo específico (preço, estoque, SLA ou disponibilidade do item) é preciso realizar uma simulação de fulfillment.
cURL
curl --location --request POST 'https://.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={{Pol%C3%ADticaComercial}}&affiliateId={{Afiliado}}' \
--header 'Content-Type: application/json' \ --data-raw '{ "items": [{ "id": "32309", "quantity": 1, "seller": "1" }], "marketingData": null, "postalCode": "22250040", "country": "BRA", "selectedSla": null, "clientProfileData": null, "geoCoordinates": [], "isCheckedIn": false, "storeId": null }' |
No resultado dessa simulação, é necessário analisar os campos:
- “Price” para validar seo sku possui preço válido;
- “Sla” para validar se há algum retorno de SLA para o sku no CEP indicado;
- “Stockbalance” para validar se o sku possui estoque;
- “Message” para validar a disponibilidade do sku.
- Caso alguma das informações acima não esteja válida, o pedido continuará com erro no Bridge. Neste caso deve-se analisar as configurações da loja ou verificar com o time de Checkout o motivo da informação não estar válida.
- Após a correção, basta reprocessar o pedido. Caso o erro permaneça, a falha deverá ser tratada com o time de Channels, sendo imprescindível constar no ticket a simulação de fullfilment realizada e os detalhes identificados na análise.
Pedido com log de sucesso no Bridge, não integrado. Mensagem: “Pedido fora do status para integrar…”
Os pedidos da Skyhub só serão integrados se estiverem com o status “New” ou “Approved”. Qualquer outro status resulta na mensagem acima. A documentação a seguir explica as etapas do pedido na B2W:
https://help.vtex.com/tutorial/como-funciona-a-integracao-da-skyhub--UJfYlTdmw0so2OKSie2M8
Não atualiza o status de tracking do pedido. Mensagem “Pedido não encontrado”
Esse erro ocorre quando a integração tenta atualizar o tracking do pedido. Nesta etapa, antes de atualizar as informações do pedido conforme o que foi enviado pelo OMS, a integração realiza um GET order do pedido na skyhub. Nesse momento, se por algum tipo de intermitência a Skyhub retorna que o pedido não existe (ou seja retorna um 404 Not Found) o processo de tracking fica com erro. Após isso, a integração retorna erro no bridge de Rastreamento do pedido.
Para corrigir, Realize uma chamada de GET order para verificar se a conexão com a Skyhub já se estabeleceu:
API: GET https://{{accountName}}.vtexcommercestable.com.br/api/skyhubintegration/order/{{orderId}}
Se o retorno for 200, basta reprocessar o pedido na aba de Rastreamento do Bridge.
Valor do pedido diferente do pretendido pela loja/ Valor assumido pelo Marketplace
O pedido fica com essa mensagem de erro no bridge quando a configuração da taxa de divergência não abrange a divergência de preço do pedido. Para entender esse processo leia o seguinte artigo:
https://help.vtex.com/faq/por-que-o-pedido-foi-fechado-com-um-preco-errado?locale=pt
Pedido com Kit não faturado
Em pedidos que os itens são Kits, algumas accounts ficam com erro de tracking no pedido. Isso ocorre porque seus ERPs retornam o id errado do sku no momento do faturamento do pedido.
- A integração só "conhece" o ID do kit em si (que é o que está no pedido), não dos componentes.
- O ERP lê do OMS o ID do kit e destrincha nos componentes. Porém, quando ele for faturar, ele deve devolver como ID do kit também. Dessa forma, quando a integração receber o ID do kit no invoice, ela vai entender e conseguir repassar ao marketplace.
- Isso não impede ele de faturar os componentes no ERP, que é algo fiscal e de negócio. Mas na integração com o OMS, que é algo sistêmico, ele deve passar o ID do kit.
OBS: reprocessar o pedido funciona porque a integração recebe o invoice notification do OMS com os componentes descriminados no body no primeiro momento. Mas quando o pedido é reprocessado, a integração faz apenas um GET no pedido para ver o array de packages e lá encontra o ID do item do pedido direto.
Em outras palavras:
- Não é um bug.
- O cliente deve adaptar a integração de ERP dele para faturar o pedido na VTEX exatamente de acordo com o ID do item, e não com o ID dos componentes.
Pedido preso no status “Aguardando autorização para despachar”.
Na VTEX os pedidos da Skyhub ficam nesse status quando o pagamento ainda não foi aprovado e estamos esperando que a Skyhub nos envie a informação de que o pedido entrou no status Approved. Enquanto não houver esse envio de informação por parte deles, o pedido não muda de status.
Caso não haja logs no splunk de que o pedido entrou no status “Approved” mesmo estando assim na API de GET order da Skyhub, é possível forçar o fluxo do pedido na VTEX. Para isso, utilize a API:
PUT https://portal.vtexcommercestable.com.br/api/skyhubintegration/order/{{orderId}}?an={{account}}
Transportadora divergente (como investigar)
Cliente alega que o pedido possui a transportadora errada no pedido. A escolha do courrier ocorre no momento do fechamento de compra conforme as variáveis entregues, sendo sempre escolhido o com menor tempo e custo do retorno da simulação de fulfillment.
Analisar se a evidência do log de PlaceOrder bate com a simulação de fulfillment atual, exemplo:
Caso esteja divergente, o cliente fez alguma alteração logística.
Pedido incompleto (como investigar)
O pedido está com status de sucesso no bridge, mas foi criado como pedido incompleto no OMS.
Procurar pelo primeiro log de PlaceOrderAsync no splunk da integração:
index=skyhubintegration account={{accountName}} workflow_instance={{orderId}}
Na evidência desse log existe um campo chamado "Key": "x-vtex-operation-id".
É preciso procurar no splunk o que ocorreu no checkout no momento que a integração estava tentando inserir esse pedido na VTEX, para isso você deve usar o valor que estiver nessa chave:
index=checkout operation_id={{operationId}}
Ao fazer isso, você vai ter a mensagem de erro do checkout e o motivo para o pedido ter sido criado incompleto.
Pedido não integra. Mensagem de erro: A compra não pode ser finalizada pois existem dados inconsistentes ou inválidos
Esse erro ocorre quando um item do pedido não possui availability e o checkout retorna o erro.
Para validar esse campo, é preciso realizar uma simulação de fulfillment para os itens do pedido.
cURL
curl --location --request POST 'https://.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={{Pol%C3%ADticaComercial}}&affiliateId={{Afiliado}}' \
--header 'Content-Type: application/json' \ --data-raw '{ "items": [{ "id": "32309", "quantity": 1, "seller": "1" }], "marketingData": null, "postalCode": "22250040", "country": "BRA", "selectedSla": null, "clientProfileData": null, "geoCoordinates": [], "isCheckedIn": false, "storeId": null }' |
No resultado dessa simulação, é verificar se o campo "availability" está correto ou com alguma mensagem.
Exemplo de erro:
Comentários