FAQ Connections - B2W/Skyhub

ESSE É UM FAQ PARA USO EXCLUSIVAMENTE INTERNO.

Este FAQ tem como objetivo indicar soluções para problemas que podem surgir na Integração com a BW2. Este artigo está dividido em 2 seções: "Questions" e "Investigations"

QUESTIONS | PRODUCTS

Q: Por que mesmo com Estoque mínimo configurado = "0" e com a simualçao retornando estoque positivo a conta esta recebendo a seguinte msg para atualização de estoque de todos os skus?
"O estoque disponível na VTEX é de: 0. Este valor é igual ou está abaixo do estoque mínimo configurado no app de integração que é de 0. Por este motivo o valor enviado ao marketplace foi 0. Para enviar o estoque desejado do produto, a quantidade deve estar acima do estoque mínimo configurado no APP".
A: Como a configuração “Ativar estoque para entrega e cotação de frete para contas franquias *“ está selecionada como não, somente o estoque do delivery channel "pickup-in-point“ será enviado, como nesse caso não há nenhum delivery channel desse tipo, o estoque é enviado como 0. Para que seja enviado o estoque para o delivery channel "delivery", é necessário alterar a configuração já citada acima para Sim

Q: Como inativar o sku no marketplace?
A: Produto removido da politica comercial: variation disabled na B2W e seus estoques zerados

Q: Qual comportamento caso o seller apenas "Inative um sku sem estoque: " no catalogo VTEX?
A: Variation disabled na B2W;

Q: Qual comportamento caso o seller apenas "Inative um sku com estoque: " no catalogo VTEX?
A: Produto inativo: produto disabled na B2W.

Q: O que pode causar divergência no frete e escolha de transportadora na B2W?
A: Uma das causas pode estar relacionada ao mapeamento, neste caso é importante verificar se o seller esta usando API de frete ou está passando o preço utilizando uma planilha. Em casos que o seller utiliza a panilha, este valor pode ter sido cadastrado com divergencia. Para confirmar se o seller utiliza API utilize a query: index=skyhubintegration account={{accountname}}" *SimulateFreightAsync*"

Q: Queria entender um pouco mais sobre como funciona a questão da categorização dos produtos na SkyHub?
A: Quem faz a categorização é a própria B2W, com base na logica criada por eles como titulo, descrição entre outros. 

QUESTIONS | ORDERS

Q: Como funciona integração de um pedido na B2W?
A: Com a autenticação e nome da loja nós (conector) pedimos todos os pedidos disponíveis lá na B2W, independente do status NEW, Approved, cancelled;
2. Pedido recebido com o status | OrderFeedWorker | Exemplo = NEW
Então a B2W notifica a integração com os pedidos disponíveis;
3. Pedido adicionado na fila NewOrder.
Depois disso, jogamos estes pedidos em nossas filas dependendo do status;
4. Então os pedidos são consumidos de acordo com seu status.

Q: Qual o significado do erro: "Pedido não integra. Mensagem de erro: A compra não pode ser finalizada pois existem dados inconsistentes ou inválidos."
A: 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 checkout para os itens do pedido. Exemplo de erro retornado na simulação: "withoutPriceFulfillment"

INVESTIGATIONS | PRODUCTS

Cenário: "Estoque/Preço não estão sendo atualizados"
Como investigar: O Fluxo de atualização de preço e estoque nos marketplaces funciona assim:
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.

1. Primeira metade do fluxo = Time Merch
2. Segunda metade = Time Connection

É necessário investigar cada passo para identificar a falha no fluxo.

1. 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: link do 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

1. 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).

2. 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 Connections, 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:
POST https://{{accountName}}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={{PolíticaComercial}}&affiliateId={{Afiliado}}

1. 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.
2. 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.

Cenário: "Skus não são enviados. Mensagem de erro no splunk: “O usuário não pertence a conta informada”.
Como investigar: 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).

Cenário: "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”."
Como Investigar: É necessário verificar o binding para a política comercial cadastrada no marketplace (tanto da account quanto da subaccount).

INVESTIGATIONS | ORDERS

Cenário: "Erro de atualização de Tracking. Mensagem de erro: “Pedido {Númerodopedido} com chave da nota inválida…”
Como investigar: 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.

Cenário: "Erro de atualização de Tracking. Mensagem de erro: “Order skipped all the possible flux”.
Como Investigar: 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.

Cenário: "Pedido não integra. Mensagem de erro: “O item {{NomedoSku}} não está mais disponível” OU “O SLA não está disponível”.
Como investigar: 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

No resultado dessa simulação, é necessário analisar os campos: 

1. “Price” para validar seo sku possui preço válido;
2. “Sla” para validar se há algum retorno de SLA para o sku no CEP indicado;
3. “Stockbalance” para validar se o sku possui estoque;
4. “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.

Cenário: "Pedido com log de sucesso no Bridge, não integrado. Mensagem: “Pedido fora do status para integrar…”
Como investigar: 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 

Cenário: "Não atualiza o status de tracking do pedido. Mensagem “Pedido não encontrado”"
Como investigar: 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.

Cenário: "Valor do pedido diferente do pretendido pela loja/ Valor assumido pelo Marketplace"
Como Investigar: 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

Centauro: "Pedido com Kit não faturado"
Como Investigar: 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.

1. A integração só "conhece" o ID do kit em si (que é o que está no pedido), não dos componentes;
2. 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.
3. 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.

Cenário: Pedido preso no status “Aguardando autorização para despachar”.
Como Investigar: 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}}

Cenário: "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.

Cenário: "Pedido incompleto" 
Como Investigar: Artigo bem legal do time de Orders que ajuda a investigar um pedido nesta situação:
https://support.vtex.com/hc/en-us/articles/360060106912-How-to-investigate-incomplete-orders

Complementando:
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.

Cenário: "PLP não foi gerada B2W"
Como Investigar: Isso acontece em casos raros, pois foram feitas correções nesse fluxo da integração, muitas vezes devido a PLP na B2W ainda não ter sido gerada. Desta forma temos uma rota que reprocessa a PLP, que pode ser usada em casos pontuais. (se o erro estiver ocorrendo muitas vezes o time de produto precisa ser acionado para verificar alguma solução)

curl --location --request POST 'https://portal.vtexcommercestable.com.br/api/skyhubintegration/plp/IdPedido?an=account' \
A API acima deve ser usada apenas em casos onde realmente a PLP não foi gerada, e deve ser ter cuidado com a chamada contendo muitos pedidos.