FAQ Connections - Amazon

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 Amazon.

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      | ORDERS
4. QUESTIONS      | TRACKING
5. QUESTIONS      | PRODUCTS
6. QUESTIONS      | SETTINGS
7. INVESTIGATIONS | PRODUCTS

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 | ORDERS

Q: Sobre seleção SLA
A: temos uma regra dentro da reserva, onde é baseado no preço da entrega e não no prazo, ou seja, a sla selecionada vai ser a de menor preço de entrega no momento da simulação.

Q: Como acontece a reserva de estoque na Amazon?
A: O pedido só entra na VTEX de fato (criar pedido no OMS) depois que o pedido é pago na Amazon, ai já fazemos tanto a criação do pedido na VTEX quanto a aprovação (confirmando que está pago). Mas antes do pedido ser pago na Amazon, a gente tb tem o fluxo de reserva de estoque do nosso lado.

O status "Unshipped" na Amazon remete a pedidos já pagos pelo cliente, enquanto que os Pending (etapa que fazemos a reserva) é quando o pedido ainda não foi pago e por conta disso não temos todos os dados para fazer a integração do mesmo, por isso fazemos apenas a reserva dos itens

Q: Pq o pedido foi criado no OMS sem o sobrenome? Exemplo nome + Not Available [REFERENCIA]
A: Integração da VTEX chama via API os dados que são disponibilizados pelo marketplace da Amazon, somos totalmente passivos nesse fluxo, somente consumimos os dados disponibilizados por eles.

Logo, a integração fica limitada às informações que recebemos da Amazon. Esse tipo de informação no sobrenome é indicativo de que o comprador, lá na Amazon, não informou o sobrenome no cadastro do site corretamente.

O que acontece nesse casos onde entra o "Not Available" é que arrumamos uma solução paliativa para permitir que eles sejam integrados e entrem no OMS. Por questões de sistema, precisamos preencher algum valor no lugar do sobrenome, então, pedidos neste cenário entrarão na VTEX com NOT AVAILABLE no lugar do sobrenome.

Recomendo nesses caos que o comprador atualize o cadastro dele lá na Amazon com nome e sobrenome para que futuros pedidos na VTEX não sejam retornados como NOT AVAILABLE, mas os pedidos já integrados não podem ser alterados.

Resumindo, isso não indica nenhum erro da integração em si (até porque se fosse um erro deveria ocorrer com todos os pedidos) e sim demonstra uma forma que a VTEX encontrou de não perder o pedido quando não tem essa informação de sobrenome.

Q: Qual a média de tempo pra integrar um pedido na Amazon?
A: Não temos uma métrica exata de tempo de integração de pedidos na Amazon, mas é importante lembrar que só integramos pedidos na Amazon assim que o status na Amazon for "Unshipped" que seria o equivalente a Pago de fato, então digamos que um dia tenha sido criado por lá, mas levou algumas horas para ser pago de fato dependendo da forma de pagamento escolhida pelo cliente, essas horas vão naturalmente impactar no tempo de integração do pedido.

Q: Pedido com erro "item not found in order"
A: O problema é que eles estão fazendo a notificação para itens que não pertencem ao pedido. Por isso o tracking não é atualizado na Amazon"item not found in order"

Como ajustar
Para pedidos com erro de "item não encontrado", seller vai precisar enviar o ID do item correto.

Q: Quais criterios são usados para retornar "Transportadora escolhida"?
A: A integração realiza uma simulação de fulfillment e determina a transportadora com base no tempo de entrega que mais se aproxima daquele informado pela Amazon no pedido.

Q: Por que alguns pedidos não são integrados e não aparecem no bridge ou splunk?
A: Verificar com o cliente se o token cadastrado no card de configuração ainda é válido. Com o token vencido, a integração não consegue consultar os pedidos no status "unshipped" e trazer para dentro da VTEX.

Q: Como funciona o preenchimento do campo “StateInscription” no OMS?
A: Por default, se o pedido for de pessoa física, a integração preenche esse campo com a informação “Isento”. Caso não seja, a informação é preenchida com o valor repassado pela própria Amazon.

QUESTIONS | TRACKING

Q: Tipo de envio implementado hoje (10/06/2024)
A: São eles:

1. DBA: Temos implementado
2. Selfship: é a entrega pelo proprio seller, basicamente o funcionamento default
3. FBA On Site: não temos implementado
4. MFN: A Amazon é passiva neste caso, ou seja, o integrador é responsável por realizar a consulta em nosso ambiente para buscar os detalhes dos pedidos confirmados e encaminhá-los para o seu ERP para que as demais ações possam ser tomadas, como a emissão da nota fiscal, por exemplo.

Q: A integração faz o envio envio de link de Tracking?
A: Nós não enviamos o link de Tracking dos pedidos da Amazon por uma limitação do lado deles, enviamos somente o Tracking Number.

Q: Seller solicitou um exemplo prático de como a Vtex recebe e trata a etiqueta de envio da Amazon (Pedidos DBA)
A: Não logamos esta informação, mas é possivel ver na UI o formato da etiqueta acessando uma account que ja usa DBA.

COMO FUNCIONA?
Por ser DBA essa etiqueta vem da Amazon. Depois que o pedido é faturado e a gente manda o XML pra Amazon, eles devolvem pra gente uma URL pra baixar as etiquetas do pedido e tals

QUESTIONS | PRODUCTS

Q: Quais são os critérios/campos validados pela integração antes de enviar o status SHIPPED e DELIVERED para a Amazon? 

SHIPPED: Nós enviamos o SHIPPED quando recebemos a nota fiscal, em resumo, só mandamos os dados de invoice e a própria Amazon entende que é SHIPPED

DELIVERED: É automático, como integração nao alteramos nada, provavelmente a Amazon acompanha o situação do rastreamento, e quando ele é entregue atualiza o status do lado deles.

Q: Sku com erro "Existem alguns erros de mapeamento de atributos relacionados a categoria X. Por favor, mapeie os atributos faltantes/errados no Mapper para continuar a listagem do SKU:"
A: Este erro acontece quando algum atributo obrigatorio não foi preenchido, apesar de não constarem como obrigatórios na UI do mapper eles são obrigatórios. [ticket]

Q: Pq alguns skus exibem um "P" no final do id? Exemplo: "20597P"
A: Esse de final "p" só serve para agrupar as variações de SKU, não precisa ser atualizado, só criado uma vez. Por esse motivo a carga de skus nao considera eles, o sistema mesmo o sistema se encarrega de conferir isso, basta notificar os SkuIds e isso a gente ja fez com a carga sku.

Q: Integração sku com erro: SKU has not a EAN
A: Isso acontece quando o seller não possui EAN isento, neste caso o sku sempre vai precisar de um EAN valido cadastrado aqui na VTEX.

Q: Oque fazer quando o produto estiver com esse erro? Existe uma restrição vigente no nível de item (por causa de acoplamento de Item-Nível em uma oferta)
A: O produto tem uma restrição pela Amazon, orientar ao seller entrar em contato direto com a Amazon.

Q: Skus logando erroFeed Rejected
A: Geralmente esta srelacionado ao usuário e token que está configurado na integração, nestes caso solicitar ao seller que confirme com a Amazon se está tudo certo com essas chaves.

Q: Como inativar o sku no marketplace? E qual comportamento do SKU no marketplace caso o seller apenas "Inative" o sku no catalogo VTEX?
A: O Sku pode se comportar das seguintes formas:
1. Produto removido da politica comercial: zera o estoque dos SKUs que compõem o produto;
2. SKU inativo: zera o estoque do SKU.

Q: Skus logando "SKU has less than 3 images"
A: Foi criada uma nova validação, agora é necessario que um sku tenha no minimo 3 imagens ou mais. Esta nova regra começou a valer a partir do dia: 8/24/2022

QUESTIONS | SETTINGS

QUESTIONS | MATCH ANUNCIOS

SOBRE RECUSAR MATCH DE ANUNCIOS AMAZON
A ação de recusar indica que o SKU VTEX não é compatível com o ASIN apresentado, o que significa que um deles está registrado com o EAN incorreto. Essa situação requer a correção de um dos registros, seja por meio da abertura de um chamado(seller abre chamado) no suporte da Amazon ou pela alteração do cadastro no catálogo VTEX.

O problema é que, quando o registro de SKU Matching existe, ele impede qualquer alteração na integração desse produto. Portanto, para permitir o processamento de qualquer mudança, é necessário recusar (deletar o matching). Então sempre que o matching for apagado e surgir uma nova notificação do Broadcaster, o ciclo reinicia e o matching reaparece para uma nova avaliação.

Q: então tem que recusar e pedir para o seller ajustar o EAN?
A: sim, o seller precisa corrigir ou abrir chamado na Amazon

Q: Mas se o seller não quer integrar esse produto?
A: Neste caso ele precisa tirar da política comercial

QUESTIONS | MAPPER

Q: Ao fazer a migração de planilha para mapper, nós perdemos tudo que já tem Mapeado e integrado ?
A: Todo produto que é criado hoje ele olha pro xml, pega os dados configurados e manda.
Normalmente se tiver EAN, ele nunca mais vai passar por este fluxo outra vez, só vai atualizar estoque e preço, então não faz sentido ele perder nada, quando começar a usar o mapper, até pq se necessário é só reverter e desconfigurar o mapper que ele volta pro XML com tudo que tinha antes
 
Então, se tem outro produto novo daquela mesma categoria e desvinculou do mapper, ele vai igual era antes com as mesmas informações que tinha antes
 
Em resumo o mapper funciona assim:
Vc configura uma categoria, e ela é a unica categoria que vai pelo mapper, todas as outras que nao estao no mappaer vao pelo XML igual antes
 
Cenário:

1. Configurou a primeira categoria > Só aquela categoria vai pelo mapper o resto vai por fora do mapper
2. Configurou a segunda categoria > Só estas duas vão pelo mapper o resto vai por fora
3. Desconfigurou o mapper > Vai tudo pelo xml como era antes, ou seja, nada se perde

Q: Conseguimos fazer algum teste sem que impacte o restante do portfólio ?
A: O teste seria isso, pegar uma categoria com de prefrencia com pouco produto, fazer a configuração no mapper e depois reindexar o sku/produto vinculado a essa categoria que foi configurada no mapper.

Q: Ao migrar para via Admin é uma ação irreversível ?
A: Não é irreversivei, isso pq nós conseguimos apagar o vinculo entre a integração e o mapper, mas não deletamos nenhuma informação que ja foi mapeada, ou seja, se o seller quiser voltar para o mapper um dia, vai continuar de onde parou.
 

INVESTIGATIONS | PRODUCTS

Cenário: "DE-PARA Categoria Global - Amazon"
Como Investigar: A comunicação entre a integração da VTEX e o marketplace Amazon é feita através da categoria global cadastrada no produto. O preenchimento da planilha de mapeamento é feito pela categoria VTEX, mas as regras de cada uma das especificações levam em consideração a categoria global.

Para consultar onde cada categoria global está encaixada na Amazon, utilize a planilha de referência:

De-Para categoria global - Amazon

Para repassar o documento para o cliente, transformar o arquivo em excel.

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 Connections

É 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.

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://integration-amazon.vtexinternal.com/api/integration-amazon/catalog/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 Connections, 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 Amazon, é preciso verificar nos logs do splunk o envio dessa informação:

Se for estoque, pesquisar pela seguinte query: index=amazonintegration account={{accountName}} workflow_instance={{skuId}} workflow_type=FeedResultStock
Se for preço, pesquisar pela seguinte query: index=amazonintegration account={{accountName}} workflow_instance={{skuId}} workflow_type=FeedResultPrice

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: "Erro de envio de sku “Entry Department dont have a espec mapped correctly in the file”"
Como Investigar:  Esse erro mostrado no bridge indica que essa categoria exige uma especificação de departamento (gênero) para os skus. É preciso mapear essa especificação na planilha de mapeamento da Amazon e, caso o cliente ainda não possua essa especificação, é preciso criá-la e mapeá-la na planilha,

Cenário: "Erro de envio de sku “Category not available for integration”"
Como Investigar:  É preciso sempre escolher o nível mais específico da categoria global quando a mesmo possui, segundo planilha de exemplo disponível no help.

Esse erro mostrado no bridge indica também que essa categoria ainda não é contemplada pela integração da VTEX. Mesmo que ela já esteja contemplada pela Amazon (algumas ainda não são) é necessário um trabalho de integração também do lado da VTEX, para isso, é necessário solicitar essa demanda via fluxo de “feature request” para o time de Connections.

Cenário: "Fluxo de envio de sku e fluxo de match"
Como Investigar: É importante saber que o envio do sku para Amazon ocorre através da categoria global cadastrada no produto. Ou seja, as especificações precisam obedecer às regras de cada categoria.

Se dois produtos na VTEX estiverem na mesma categoria VTEX, mas em categorias globais diferentes, as especificações obrigatórias na planilha de mapeamento serão diferentes.

É importante também saber que o fluxo da integração ao enviar os produtos para Amazon é primeiramente verificar se o produto já existe do lado de lá. Para isso a integração faz uma busca utilizando o EAN do sku, caso nas suas especificações (de sku ou de produto) não exista uma especificação contendo o código ASIN.

Cenário de erro comum:
Os skus não possuíam especificações que indiquem o código ASIN do sku e ao entrar no fluxo de busca na Amazon (fluxo de match), através do EAN, foi encontrado um erro. Isso porque, segundo a Amazon, o EAN dos skus não existem na Amazon Brasil, mas existem em outros marketplaces da Amazon.
Assim não foi possível finalizar o fluxo de match e o sku ficou com a mensagem de erro.
No fim das contas temos alguns caminhos para solução do problema:

1. Cliente cadastrar especificação de ASIN (passo a passo mais abaixo)
2. Cliente solicitar isenção de EAN na Amazon e na VTEX (assim os skus não passam mais pelo fluxo de match)
3. Cliente solicitar para VTEX parar o uso do fluxo de match (assim os skus também não passam mais pelo fluxo de match)

---->Configurar especificação de ASIN<--------
Nesse caso o seller teria que criar dois campos nas especificações do SKU:

O primeiro chamado "IdType" onde ao preencher deve-se colocar o valor "ASIN"
O segundo chamado "IdTypeValue" onde ao preencher deve-se colocar o valor do código ASIN do SKU.

Cenário: "Erro de envio de sku. Mensagem de erro: The "Message/Product/DescriptionData/MerchantShippingGroupName" field contains an invalid value."
Como Investigar: O erro The "Message/Product/DescriptionData/MerchantShippingGroupName" field contains an invalid value. está associado ao campo Freight Name no cadastro da integração. Siga as orientações do artigo para mais detalhes. Este ponto está lá no final.

Freight Name: Nome do tipo de entrega cadastrado no painel da Amazon. Este nome do tipo de entrega está localizado na tela Configurações de envio na aba Modelos de Envio, embaixo da caixa Modelo padrão da Amazon.

Você deve preencher no cadastro da integração o mesmo nome indicado na imagem.

INVESTIGATIONS | ORDERS

Cenários de pedidos não integrados, devem ser analisado por meio de um novo index na integração da Amazon. "order_integration".

Exemplo:

index=order_integration account=dreamskyhub2 701-3343349-6397848

Também as rotas de GET Orders foram alteradas, nova rota conforme exemplo abaixo:
curl --location --request GET 'https://portal.vtexcommercestable.com.br/api/integration-amazon/orders/701-9810141-2937037?an=dreamskyhub2' \

Cenário: Pedido não integrado. Message":"An error has occurred.","ExceptionMessage":"could not connect to redis Instance at rediscluster.vtex.com.br:6379"
Como Investigar:  Esse erro é raro, mas pode ocorrer quando o redis fica fora do ar por um período de tempo. Assim o pedido não consegue ser inserido. Caso o pedido ainda esteja no status “unshipped” basta forçar via API que o mesmo será integrado corretamente.

API de carga de pedido:
POST https://portal.vtexcommercestable.com.br/api/integration-amazon/orders/{{orderid}}?an={{accountName}}

Cenário: "Erros nos dados de endereço do pedido"
Como Investigar: As informações de endereço no pedido preenchidas no OMS vêm diferentes do formato esperado, exemplo: O número vem junto com o logradouro e o complemento no lugar do número. Esse erro não é corrigível, entenda agora os motivos:

Veja como é a interface do pedido no lado da Amazon:

Os campos "Endereço", "Número" e "Complemento (opcional)" correspondem aos campos, na API de GET order da Amazon, "Adressline1", "Adressline2" e "Adressline3".

Veja que quando passamos o pedido para o OMS estes 3 campos são os que usamos para preencher, respectivamente, "street", "number" e "complement". 

Ou seja:

1. O campo "Endereço" na Amazon corresponde ao campo "street" na VTEX.
2. O campo "Número" na Amazon corresponde ao campo "number" na VTEX.
3. O campo "Complemento (opcional)" na Amazon corresponde ao campo "complement" na VTEX. 

Nós já tratamos as informações da maneira correta.  Esses campos são strings, ou seja, o cliente pode escrever qualquer tipo de coisa, seja texto, número, etc. Se o cliente preenche o número juntamente com a rua no campo "Endereço" e o bairro no campo "Número" nós precisamos descer o pedido para o OMS da maneira que ele vem, não há como tratar esse tipo de informação.

Cenário: "Pedidos com erro de SLA ou sku sem estoque"
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 de SLA 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. "Availability" para validar se o sku está com um status válido;
3. “Sla” para validar se há algum retorno de SLA para o sku no CEP indicado;
4. “Stockbalance” para validar se o sku possui estoque;
5. “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 Connections, sendo imprescindível constar no ticket a simulação de fullfilment realizada e os detalhes identificados na análise.
  
  
  Para os modelos logísticos Amazon (DBA, FBA e FBA Onsite), sim a Amazon atualiza o status para entregue. Porém, para pedidos MFN a última atualização do pedido é o "Enviado" / "Shipped"