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: Como criar pontos de retirada na Skyhub/B2W a partir dos pontos de retirada cadastrados nas contas franquias?
A: Passo a passo na seguinte documentação
Q: É possivel realizar uma migração na B2W?
A: Hoje na B2W não possuímos a feature para realizar uma migração
Possíveis Soluções:
1. Seller verificar com a B2W se tem algo do lado deles com a possibilidade de migrar por lá sem perder a relevância;
2. Se forem exatamente os mesmos IDs skus aqui na VTEX e na B2W não precisa migrar, vai ser meio que automática a sincronização;
3. Skus diferentes, deletar tudo e começar do zero subindo da VTEX.
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: Pq alguns pedidos tem o prazo de entrega diferente entre VTEX e B2W?
A: Isso pode acontecer pq na VTEX o prazo de entrega é contado de forma corrida, não como dias úteis, Já na B2W o total considera apenas dias uteis, ou seja, se existir algum feriado, ou final de semana vai considerar mais dias no "estimated_delivery".
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}}
- 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.
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
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:
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.
Comentários