FAQ Connections - B2W/Skyhub

ESSE É UM FAQ PARA USO EXCLUSIVAMENTE INTERNO.

Este FAQ tem como objetivo indicar soluções para problemas e ajudar com duvidas que podem surgir na Integração com a Skyhub/B2W.

ATENÇÃO: MUDANÇAS SPLUNK PARA OPEN SEARCH 

Devido as mudanças relacionadas ao log, favor desconsiderar "queries" relacionadas ao splunk mencionadas neste FAQ, recomendamos a uitlização do seguinte arquivo como referencia, até que o FAQ seja atualizado.  (Estas novas queries tambem estão disponiveis para consulta no canal #team-connections.

O FAQ ESTÁ CLASSIFICADO DA SEGUINTE FORMA:

1. UPDATE FAQ     | ACOMPANHE AS ULTIMAS ATUALIZAÇÕES DO NOSSO FAQ
2. TICKETS        | QUAIS INFOS PODEM AJUDAR O TIME DE PRODUTO EM UMA INVESTIGAÇÃO?
3. QUESTIONS      | PRODUCTS
4. QUESTIONS      | ORDERS
5. INVESTIGATIONS | PRODUCTS
6. INVESTIGATIONS | ORDERS

UPDATE FAQ | CLIQUE AQUI E ACOMPANHE AS ULTIMAS ATUALIZAÇÕES DO NOSSO FAQ

QUAIS INFOS PODEM AJUDAR O TIME DE PRODUTO EM UMA INVESTIGAÇÃO?

Ficou com duvida na hora de criar um ticket para Connections? CLIQUE AQUI
Temos algumas dicas que podem ajudar a melhorar nossa comunicação e diminuir o "vai e vem" dos tickets, dando assim mais agilidade no atendimento/resposta do time de produto. Aqui estão algumas dicas que achamos essencial para iniciar uma investigação.

QUESTIONS | PRODUCTS

Q: O Modelo de negocio MOI, pode ser usado na B2W?
A: Hoje o MOI esta ativo para a B2W, mas só pode ser usado com "ship-from-store" (10/08/2023)

Q: É possivel enviar "assembly option" para o marketplace? [ticket referencia]
A: Hoje as integrações não estão preparadas para o envio doassembly option, e mesmo que o ajuste fosse realizado do nosso lado, não temos certeza se todas os marketplaces estão preparados para aceitar oassembly option.

Q: Como o peso de um produto é enviado para o marketplace?
A: Convertemos o peso de gramas para Kg e enviamos para o marketplace.

Q: Skus/Pedidos com erro "Usuário bloqueado ou inexistente"
A: Este erro é retornado pelo marketplace e indica que existe algum problema com as credenciais que estão sendo usadas pelo seller.

Solução
1. Seller pode confirmar se a credencial cadastrada aqui na VTEX no card da skyhub é a mesma cadastrada na skyhub;
2. Verificar no portal da skyhub se esta credencial esta ativa/valida;
3. Seguir com um chamado na skyhub para entender a situação da credencial.

Q: Skus/pedidos com erro "API rate limit exceeded"
A: Rate Limite (429 ou throttling) aqui é importante ter em mente que não se trata de um erro, ele existe para controlar as notificações, e acontece quando o seller atinge o limite de requisições no marketplace, importante saber que este limite é definido pelo prorprio marketplace.

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: Seller quer trabalhar com multi CDs na b2w, mas tem dúvidas de como fazer a integração.
A: Atualmente não damos suoprte pra múltiplos centros de distribuição através da nossa integração com a B2W. A Skyhub tem uma API disponível, mas não temos nada parecido implementado do nosso lado, continuamos apenas com suporte para envio de estoque por SKU, considerando a soma de tudo que está disponível na loja. O mais próximo que temos disso é a integração com pickup-in-point que oferecemos na integração, que aí sim possui estoque separado, mas aí por loja física.

Se o seller sentir necessidade, pode seguir com uma IDEA https://ideas.vtex.com/ideas

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: Qual comportamento caso o estoque do sku fique zerado na VTEX? stock = "0"
A: Quando o estoque do SKU é zerado enviamos pra variação o statusdisabledlá pro marketplace!

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: Pedido FOB, onde a entrega será feita pelo marketplace o OMS trará o valor do frete?
A: Sim, o fluxo certo é trazer o frete no OMS mesmo o pedido sendo FOB, visto que é um valor pago pelo cliente final.

Q: Pedido com erro "A nota fiscal não foi enviada pois existe uma instância de SAC do pedido sendo executada na B2W"
A: Nesse caso, como a própria mensagem diz, a integração bloqueia o envio dos dados de rastreio/faturamento pois existe uma instância de SAC em aberto para esse pedido. Atualmente a integração faz uma validação na skyhub no momento de atualização do tracking para verificar se o pedido possui uma instância (SAC aberto) do lado de lá. Caso o pedido possua uma instância, é logada essa mensagem de erro no bridge.

Entretanto, uma instância pode ser cancelada ou recusada do lado da Skyhub. Caso ela seja cancelada, o pedido segue com o fluxo de entrega normalmente. Caso a instância seja atendida/resolvida, a integração fará uma validação se o pedido deve ser cancelado por inteiro ou se itens específicos serão reembolsados.

Q: Pedidos com erro "item não encontrado"
A: Este erro ocorre no status "TrackingWorker", quando o ID do item enviado na NF é diferente do ID do SKU do pedido. Por exemplo, se o ID enviado na NF for o de um dos componentes do Kit vendido. O correto neste caso é enviar na NF o ID do SKU do Kit. [Ticket referencia]

Link com o tutorial para que a account crie de forma correta a invoice e o tracking :https://support.vtex.com/hc/en-us/articles/4403214538779

Q: Qual é o throttling das APIs do bridge? Qual seria o limite de requisições paralelas e/ou por minuto".
A: Atualmente as APIs do Bridge não possuem controle de throttling. A gente até tem uma configuração geral pra todas as rotas do serviço (100k requests/min por instância, sendo metade disso por account) mas ela não tá sendo aplicada no momento.

Q: Queria saber se pedidos cancelados na VTEX deveriam ser cancelados na B2W ou se esse fluxo não existe.
A: A B2W aceita cancelamento VTEX > B2W and B2W > VTEX,mas é muito importante saber que só cancelamos  VTEX > B2W se o Status do Pedido estiver menor que faturado.

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".  (KI criada para melhorar o fluxo: https://vtexhelp.zendesk.com/agent/tickets/642448)

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"

Q: A chave vtexappkey-appvtex indica seller ou marketplace?
A: Por ser tratar ser um pedido integrado usando marketplace, no OMS toda as ações feitas nesse pedidos ficam marcadas como se fosse um outro sistema fazendo essa execução, então no local do usuário vai aparecer a chave da VTEX.

Q: Pedido com status "Cancelamento Solicitado"
A: É importante entender que depois de iniciar o manuseio do pedido vai ser necessária uma confirmação no caso de solicitar o cancelamento, pois o pedido já está num momento posterior que significa ter já movimentação dos itens e qualquer outro detalhe na operação. Esta é a regra do OMS para cancelamento de pedidos após status "Carencia para Cancelamento"

INVESTIGATIONS | PRODUCTS

Cenario: Seller reclamando de divergencia no prazo para "cross-docking"
Como investigar: O Primeiro passo aqui é entender como é calculado este prazo.
Ticket referencia: https://vtexhelp.zendesk.com/agent/tickets/703396

Segundo a documentação do HELP, essa é a descrição do campo:
https://help.vtex.com/tutorial/como-funciona-a-integracao-da-skyhub--UJfYlTdmw0so2OKSie2M8?locale=pt#entrega

Tempo de preparo de envio (Cross-docking)
O tempo de preparo de envio é baseado no somatório do campo Tempo de custo no Estoque com o Tempo de Custo na Doca. A VTEX envia o mesmo tempo de preparo massivamente para todos os produtos". A Integração com a Skyhub faz a leitura do campodockEstimatena simulação de carrinho e envia junto com as propriedadesCrossDock+CDnos SKUs.

Passo 1. Verificar configuração do campo "custo de tempo" na doca vinculada a politica comercial do Marketplace

Passo 2. Faça um Get na Skyhub passando o productid na rota, busque pelo campo "CrossDock+CD" e verifiquei qual o valor para o sku informado e se está correspondendo com o valor cadastrado na doca, se o valor for o mesmo cadastrado na estrategia de envio VTEX, então o fluxo esta correto, se estiver divergente, abrir um ticket para o time de Connections.

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.