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 Magazine Luiza. Este artigo está dividido em 2 seções: "Questions" e "Investigations"
QUESTIONS | PRODUCTS
Q: É possível excluir um SKU na Magalu?
A: Excluir não, mas é possível inativar um sku removendo ele da politica comercial da Magalu. A Integração basicamente joga para um método que vai trocar a flag de SKU ativado de "true" pra "false" e ai vai fazer o update de SKU normal só que desativando o SKU la na Magalu.
Q: Quando inativo um SKU na VTEX ele fica inativo na Magalu?
A: Não, para inativar um sku na Magalu é necessario remover da politica comercial, se inativar na VTEX o SKU continuará ativo e disponivel na Magalu.
QUESTIONS | ORDERS
Q: Por que alguns pedidos são criados no OMS com o telefone "11999999999"?
A: A integração realiza algumas validações antes de criar um pedido no OMS, quando a Magalu envia o campo "telefone=null/vazio" para evitar erros na criação do pedido, preenchemos com "11999999999" e criamos o pedido no OMS.
Q: Notas divergentes na Magalu, existe um juro que aparece na interface gráfica da VTEX e da MGL, mas não é informado no JSON.
A: Diferente de outros marketplaces, a Magazine Luiza exige que seus sellers faturem os pedidos levando em consideração o valor dos juros, quando os mesmos existem no pedido. Esta documentação vai orientar e ajudar com todo o contexto.
Q: Existe algum controle por parte da VTEX quanto a data de emissão do pedido no Marketplace no momento da integração?
A: Não, a integração olha sempre o "status" do pedido, se o pedido estiver no status correto, a integração vai integrar o pedido independente da data. (por exemplo Status: NEW)
Q: Qual status o pedido vai integrar?
A: Para que um pedido seja integrado, ele precisa estar nos status NEW ou APPROVED, caso contrário ele não será importado pela integração e o pedido deverá ser manipulado manualmente pela interface do próprio marketplace.
Q: Qual o significado do erro: "pedido não está no status de Aprovado ou Processando no Marketplace"
A: Isso significa que o pedido esta fora do status aceito pela integração, onde provavelmente o seller manipulou o pedido "manualmente" no portal da Magalu, lembrando que um pedido só pode ser integrado no status NEW ou APPROVED, para confirmar realize um get no pedido na Magalu e confirme o status do pedido. Exemplo pedido fora do Status:
Q: Como funciona a reserva de estoque quando um pedido é integrado no status NEW?
A: Vai funcionar da seguinte forma:
- No status NEW é feito um pedido e reservado o estoque;
- Quando recebemos o APPROVED nós fazemos a baixa do estoque;
- Caso contrário cancelamos o pedido e excluímos a reserva do estoque.
Q: Por que existem alguns pedidos integrados da Magazine Luiza onde os juros são exibidos na UI do OMS mas não temos aquela CustomTax populada no pedido?
A: Esta documentação explica todo o contexto e soluções para este cenário: https://docs.google.com/document/d/1ItRhrZGUf5OW35kDEDWhy4P5rreLGOA1ydjfk7M9KdA/edit#
QUESTIONS | SETTINGS
Q: Como funciona o mapeamento de transportadora na Magalu?
A: O conector com Magalu permite um De/Para das transportadoras cadastradas na Magalu com as transportadoras cadastradas na VTEX, ou seja, o mapeamento seja Transportadora do tipo X na Magazine Luiza é na verdade a Transportadora Y na VTEX, logo um pedido que tenha sido feito com a transportadora X na Magalu, será integrado com a transportadora Y na VTEX. Mais detalhes sobre o mapeamento acesso nosso Notion.
Q: Como funciona a feature de delivery de contas franquias na Magalu?
A: Esta feature permite que os sellers possam se utilizar de seus diversos inventários configurados na VTEX, de forma que seja possível despachar produtos que estão localizados mais próximos aos clientes, diminuindo o custo de frete e o tempo de entrega e aumentando assim sua competitividade dentro do marketplace.
1. Explicação sobre contas franquias e white labels: https://help.vtex.com/tutorial/what-are-franchise-account-and-seller-white-label?locale=en
2. Documentação falando um pouco sobre contas franquias e sobre as rotas utilizadas pra mexer com pedido de conta franquia: https://help.vtex.com/business-guides/offer-the-products-from-your-physical-stores-in-external-marketplaces--6s64bV8Dqb5QN6sqIfPzcA
Q: Como Funciona cotação de frete na Magalu?
A: Na integração da Magazine Luiza, nem todos os sellers fazem a cotação de frete na integração. Para os que fazem, a cotação funciona da seguinte maneira:
1. A Magalu chama a integração na rota: /api/magazineluizaintegration/freight/fulfillment/pvt/orderForms/simulation passando um payload exatamente igual ao de uma simulação de carrinho;
2. É feito a simulação de frete utilizando o payload enviado pela Magalu;
- Se o seller estiver com a feature de conta franquia ativa, a simulação de frete segue a lógica apresentada na seção Conta Franquia.
3. É retornado a resposta da simulação de carrinho.
Nesse caso, a integração funciona mais como um intermediador entre Magalu e fulfillment/checkout, só repassando as resposta de um para o outro (passa o payload da Magalu para fulfillment/checkout e depois repassa a resposta para a Magalu).
Isso acontece porque antigamente a Magalu fazia a consulta de frete diretamente com o fulfillment (não fazia com o checkout porque não tinha a feature de conta franquia antes). O problema da Magalu consultar diretamente o fulfillment para consultar o frete era que, para cada seller novo que fosse se integrar com a Magalu, teria que gerar um app-key e app-token para a Magalu, dando permissão para fazer a simulação de carrinho para aquele seller e então configurar esse app-key e app-token lá na Magalu, para que eles pudessem utilizar isso para fazer a chamada diretamente no fulfillment.
Para resolver esse problema, foi feito a consulta de frete como é feita hoje, com a Magalu chamando a integração e então a integração repassando para o fulfillment/checkout. Dessa forma, a Magalu só precisa se comunicar com a integração e a integração se encarrega de fazer a simulação de carrinho utilizando o token VTEX. Assim, um seller não precisa mais gerar um app-key e app-token e depois registrar isso no sistema da Magalu, acelerando o processo de integração com o marketplace.
INVESTIGATIONS | PRODUCTS
Cenário: "Sku não integra: Mensagem de erro: “Não é permitido alteração do campo IdSkuErp.”
Como investigar: O campo “IdSkuErp” na Magalu corresponde ao “código de referência” na VTEX. Uma vez que o sku foi integrado não é mais permitido fazer uma alteração dessa informação. Caso o cliente realize uma alteração, essa mensagem será logada no bridge.
Cenário: "Sku não integra: Mensagem de erro: “Sku não está na política comercial XX.”
Como Investigar: Para enviar o sku, a integração faz validação se o sku está na política comercial, se possui estoque e se possui preço. Para validar todas as configurações do sku, o ideal é realizar uma simulação de fulfillment para o sku na política comercial da Magalu.
API de fulfillment:
POST https://{{accountName}}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={{PolíticaComercial}}&affiliateId={{Afiliado}}
Cenário: Preço do sku não foi atualizado no Marketplace.
Como Investigar: Primeiro passo avaliar se o sku possui preço fixo cadastrado no catalogo e se foi atualizado.
Sim, preço fixo foi atualizado > Pular este passo e seguir com a próxima analise (Estoque/Preço não estão sendo atualizados)
Não, não possui preço fixo > Neste caso a integração não é notificada sobre alteração de preço. Somente alterações de "Preço Fixo geram notificações ao broadcaster.
Ainda tenho duvidas sobre atualização do preço fixo
Esta é a documentção do time de Merch que explica como funciona atualização preço fixo.
https://help.vtex.com/pt/tracks/precos-101--6f8pwCns3PJHqMvQSugNfP/3HxF2u5VwidqnUGnFoKdDy?locale=pt
Mas o Seller não usa "Preço Fixo" o que fazer neste caso?
Caso o seller queira que os preços notifiquem para atualizações de preços não fixos, ele pode definir uma regra de preço, mesmo que vazia para essa política específica e o workflow do pricing de notificação de preços irá chamar o broadcaster.
Como configurar uma regra de preço?
Acesse o Admin > Produtos > Preços > Regras de Preço > Nova Regra
Nova Regra: Quais os dados gerais dessa regra? Selecione a politica comercial (recomendamos criar uma regra para cada politica comercial existente na loja). Quais itens esta regra será aplicada? Selecione a opção "Aplicar em todos os produtos"
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 da seguinte forma: 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: 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://magazineluizaintegration.vtexinternal.com.br/api/magazineluizaintegration/indexedstockkeepingunit?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 Magalu, é preciso verificar nos logs do splunk o envio dessa informação:
Se for estoque, pesquisar pela seguinte query:
index=magazineluizaintegration account={{accountName}} workflow_instance={{skuId}} workflow_type=UpdateStockAsync
Se for preço, pesquisar pela seguinte query:
index=magazineluizaintegration account={{accountName}} workflow_instance={{skuId}} workflow_type=UpdatePriceAsync
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:
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.
INVESTIGATIONS | ORDERS
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
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: "Pedidos com erro: "Mensagem de erro: “Há produtos desse pedido que não podem ser entregues com o Sla Normal”".
Como Investigar: Geralmente, esse erro está ligado com o tipo de entrega mapeamento do cliente. É necessário olhar as configurações de “Mapeamento de SLA Customizável” no card de config.
OBS: Valores aceitos pela Magalu:
1 - "NORMAL
2 - "EXPRESSA
3 - "Convencional"
Se o mapeamento no Card não estiver exatamente como acima, a configuração não entende que existe o mapeamento. Caso, após a correção, o reprocessamento do pedido não funcionar é necessário fazer as validações explicadas no ponto anterior.
INVESTIGATIONS | SETTINGS
Cenário: "Erro ao salvar configuração. Mensagem de erro: “Erro! Ação com erro”".
Como Investigar: Esses casos são mais comuns na Magazine luiza quando se trata da configuração de uma loja que é uma migração (account já estava na Magalu por outro integrador e quer utilizar VTEX).
Esse tipo de configuração deve ser feita diretamente pelo time de Connections, por isso é necessário abrir um ticket enviando as seguintes informações no formato Json:
OBS: Não repassar o modelo pois se trata de um cliente real
{
"accountName": "moikana",
"invoiceSeriesNumber": 1,
"isActive": true,
"affiliateId": "MGZ",
"saleChannelId": "2",
"orderAllowanceRate": 60.0,
"user": "",
"password": "",
"minStock": 1,
"slaMap": {},
"creationDate": "",
"companyName": "MK E-store Comercio Eletronico LTDA",
"cnpj": "14146448000122",
"corporateName": "Moikana",
"distributionCenterZipcode": "87050220",
"soldAndDeliveredBy": "moikana1",
"paydayFrequency": "monthly",
"dayOfPayday": 1,
"maxNumberOfInstallmentsForClients": 6,
"sellsToALegalPerson": false,
"contactName": "Marcos Barreto",
"contactEmail": "marcos.barreto@moikana.com.br",
"contactPhone": "4430328900",
"bankCode": "341",
"bankName": "341 - Itaú Unibanco S.A.",
"bankBranch": "3739",
"bankBranchDigit": null,
"bankAccount": "18658",
"bankAccountDigit": "7",
"siteUrl": "https://www.moikana.com.br",
"isPriceIntegrationBlocked": false,
"isInventoryIntegrationBlocked": false,
"isCatalogIntegrationBlocked": false
}
Comentários