FAQ Connections - Facebook

ESSE É UM FAQ PARA USO EXCLUSIVAMENTE INTERNO.

FAQ - ENGLISH VERSION

Este FAQ tem como objetivo indicar soluções para problemas que podem surgir na Integração com o Facebook.

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.

IMPORTANTE: Antes de iniciar a investigação é importante lembrar que Integração Facebook e APP FBE funcionam em conjunto, mas são aplicações diferentes, considerando este ponto, este FAQ vai abordar apenas duvidas e investigações relacionadas a integração com Facebook.

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. ERROR ANSWERS  | DOCUMENTATION FACEBOOK
4. QUESTIONS      | SETTINGS
5. QUESTIONS      | PRODUCTS
6. INVESTIGATIONS | PRODUCTS
7. QUESTIONS      | SETTINGS

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.

ERROR ANSWERS | DOCUMENTATION FACEBOOK

O documento a seguir exibe uma lista de valores de erro com um mapa para o método de resolução mais comum no Facebook - Como solucionar erros

QUESTIONS | SETTINGS

Q: É possível enviar campos personalizados via integração do Facebook?
A: Hoje (19/01/2023) em nossa integração não temos nenhuma referência para esses campos de custom_label_n. Então por mais que o Facebook aceite, a nossa integração em si parece não dar suporte para esses campos customizados. Teria que implementar esse mapeamento entre especificação do produto do seller na VTEX pra custom label no Facebook, porque só damos suporte para alguns campos pré-definidos atualmente. https://developers.facebook.com/docs/marketing-api/catalog-batch/reference#supported-fields-batch 

Q: Facebook esta preparado para sellers MultiLevel?
A: Sim, temos algumas contas como exemplo nesta arquitetura: Rihappy e Lebisqui

Q: Considerando que no momento que acontece a primeira autenticação da conta na nossa integração um catalogo é criado no facebook, é possível alterar a política comercial da configuração do conector, sem precisar excluir o catálogo antigo e enviar o novo novamente? teria algum impacto no catalogo la no facebook?
A: Não temos nada que de suporte a mudança de politica. Entre os dois fluxos (FBE/integração) a única diferença é que FBE remove o afiliado da loja. O que ocorre é que aqueles skus que já estão integrados vão se "perder na integração" (não vão ser atualizados porque não existem mais no SC).  Por isso o recomendado é deletar o catalogo sempre que mudar o SC.

Q: O seller pode vincular varias accounts usando o mesmo businessID? Neste caso, como são criados os catalogos no facebook business? 
A: Não conferimos em nenhum ponto se o businessID é o mesmo de outra conta, apenas enviamos para o catalogId que esta configurado. Então nesse cenário, pode acontecer de duas contas com o mesmo businessId, porém, nós criamos um catalogo no Facebook na primeira vez que a loja autentica na integração. A não ser que o facebook mande o mesmo catalogId para lojas diferentes, vamos sempre ter catalogId diferente para cada loja. O ponto de "como é criado", no momento que acontece a primeira autenticação da conta na nossa integração um catalogo é criado, nosso seller não consegue configurar esse calogo via admin e criamos para ele.

Q: Um cliente possui duas contas, LojaA e LojaB, a LojaA já está configurada mas quando tentaram configurar a LojaB ele acaba integrando com o catálogo de LojaA, não criou um novo (Eles têm integrações muito parecidas, acredito que até usem o mesmo ID da Loja).
A: Na VTEX nós temos 2 formas de integrar com o Facebook, pela nossa integração ou pelo app do FBE.
Nós, fazemos esse comportamento de criar o Catalogo quando você configura a conta, porém o FBE tem um comportamento um pouco diferente. Quando você configura via APP FBE ele te redireciona para o Facebook e lá você pode configurar um catalogo específico para essa integração (ou o mesmo). Nesse caso é o próprio facebook que configura isso, nós não criamos. Assim, você pode entrar nesse caso de ter duas accounts no mesmo catalogo. O que o time do FBE recomenda nestes casos desconectar a conta do Business, configurar ela e criar/selecionar outro catalogo. Os items vão começar a aparecer nesse catalogo, para excluir do catalogo antigo a integração não tem suporte ainda, portanto, teria que ser feito no próprio Facebook para fazer essa limpeza atualmente.

QUESTIONS | PRODUCTS

A: Não é possível pelo fato de a gente conseguir fazer apenas uma integração com o facebook por account. Até por isso nos cards de configuração da integrção com o Facebook ele tem que colocar uma politica comercial, que é o único canal de envio de produtos pro facebook.

Q: Bridge não exibe preço e estoque no bridge.
A: Está correto! Este é um comportamento do facebook hoje, logamos apenas informações do sku, não logamos preço/estoque no bridge. (comportamento valido apenas para Facebook)

Q: Como inativar um sku no marketplace?
A: Produto removido da política comercial: SKUs removidos do Facebook;

Q: Qual comportamento caso o seller apenas "Inative" o sku no catalogo VTEX?
A: SKU removido do Facebook;

Q: Qual comportamento caso o seller deixe o produto como "Não Visivel" no catalogo VTEX?
A:  Produto status "não visível" são removidos do Facebook.

Q: O facebook envia os preços já com imposto (Tax IVA)?
A: Hoje a integração não envia TAX IVA, não olhamos para está taxa, a nossa integração só estaria aplicando essa taxa se ela já viesse aplicada no preço do SKU na simulação de carrinho.

Q: Como funciona a arvore de categorias do facebook?
A: Facebook aceita categoria de duas formas:

- Texto string (qualquer coisa)
- id da categoria google.

Nós mandamos atualmente a categoria pai da loja.

Exemplo cadastrado na Vtex:
Moda (categoria Pai)
masculino (Categoria Filho)
camisetas (Categoria Filho)

Sku esta vinculado a Categoria "Camisetas" na VTEX que é uma sub categoria.
Mas no Facebook gravamos Sku vinculado a Categoria "Moda" que é a categoria Pai.

[Notificação - Preço]

http://{{AccountName}}.vtexcommercestable.com.br/api/notificator/changenotification/{{Idsku}}/price 

[Notificação - Estoque]

http://{{accountName}}.vtexcommercestable.com.br/api/notificator/changenotification/{{Idsku}}/stock 

[Notificação - Produto]

http://{{AccountName}}.vtexcommercestable.com.br/api/notificator/changenotification/{{Idsku}}  

Q: Em quais situações um SKU pode ser deletado do catalogo do Facebook?
A: Quando ele se torna "Inelegível" para o Facebook. O Sku vai receber status "skuMethod="DELETE" nas seguintes situações:

- Inativo (Catalogo VTEX);
- Não visível (Catalogo VTEX);
- Fora da politica comercial (VTEX).

Q: O Facebook aceita alteração no nome do SKU?
A: A integração suporta a alteração, mas ela mesmo modifica o name do SKU usando titleCase, que é basicamente deixar a primeira letra de cada palavra em maiúsculo.

Q: É possível usar a planilha de mapeamento do Facebook para enviar uma descrição diferente?
A: Não, atualmente a integração não tem suporte a substituição da descrição através da planilha de mapeamento.

Q: Gostaria de entender melhor o fluxo de atualização de preço na integração no Facebook para os produtos que são de seller NÃO VTEX, que usam HUB EXTERNO para integração de catalogo com a VTEX.
A: Quando o Marketplace é externo, o fluxo deve ser visto com o #team-marketplace. Todos os sellers externos precisam notificar o marketplace quando o preço muda, e isso precisa ser suficiente para os fluxos do próprio marketplace atualizem seus dados aonde necessário (como outras integrações externas). Para confirmar se o conector esta atualizando corretamente, é possivel forçar uma notificação, se o broadcaster for notificado, então conector esta ok.

Q: É possível alterar imagem de um sku já integrado com sucesso?
A: Sim, a integração é notificada sempre que o sku é atualizado(re-indexado)

Q: É possível definir a foto principal de um sku no Facebook?
A: Sim, a integração envia todas as imagens cadastradas no sku, a primeira imagem é enviada como principal e as outras como adicionais. (na ordem do exemplo abaixo)

Q: O que significa "fbtrace_id"e onde posso encontrar?
A: O "fbtrace_id" é o identificador de suporte interno do Facebook. Ao relatar um bug relacionado a uma chamada da Graph API, o fbtrace_id ajuda o Facebook a encontrar os dados de registro para depuração. Para encontrar estas informações, acesse o log no Splunk e realize a seguinte consulta e busque por "fbtrace_id"
Consulta: index=facebookintegration account={{Account}} workflow_type=SendProductBatchAsync type=error exception_type="Vtex.Integration.Facebook.Exceptions.ApiException" fbtrace_id

INVESTIGATIONS | PRODUCTS

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 (como investigar))

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.

Regra de preço
https://help.vtex.com/pt/tracks/precos-101--6f8pwCns3PJHqMvQSugNfP/2rBirbpB7wLnei4dQ9KGMW

Atualizar preço para marketplace
https://help.vtex.com/pt/tutorial/atualizando-preco-para-marketplace--tutorials_384

Preço Fixo - Definição de conceito
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 esta 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). Em quais itens esta regra será aplicada?  Selecione a opção "Aplicar em todos os produtos".

Para os outros campos nenhuma seleção é necessária > Clique em "Salvar". Realize o mesmo procedimento para as outras politicas comerciais. 

IMPORTANTE: Após cadastro preço fixo ou regra de preço, solicitar ao time de connections uma carga geral para integração de todos os skus.

Cenario: "Migração de integração XML -> Nativa VTEX"
Como realizar: Caso o cliente já possua integração com o Facebook via XML e queira passar a utilizar a solução nativa da VTEX, o passo a passo é:

Manter os dois ligados:
Passo 1. Deixar o feed de XML ligado;
Passo 2. Habilitar a VTEX;
Passo 3. Depois de integrado com a VTEX o feed de xml pode ser desligado.

Cenário: "Unsupported post request. Object with ID “XXXXX” does not exist...”
Como investigar:  É necessário validar com o cliente se as informações cadastradas no card de configuração do Facebook, como e-mail do afiliado ou Id do Business Manager, estão válidos. Caso o cliente confirme que está tudo correto, é necessário abrir um chamado com o time de Channels passando todo o cenário.

Cenário: “O sku não possui preço de venda cadastrado na VTEX. É um valor obrigatorio”
Como investigar: O primeiro passo a se investigar nesse cenário é se realmente o sku não possui um preço cadastrado para a política comercial do Facebook.

Caso esteja tudo correto nessa primeira validação, também é necessário verificar o status desse sku, pois esse erro também pode estar relacionado com a situação de Ativo/Inativo. A melhor forma de fazer isso é realizando uma simulação de checkout:

Nessa simulação é importante analisar os campos:

1. Message
2. Price
3. Estoque

Caso esteja tudo válido, é necessário abrir um chamado com o time de Channels enviando todas as análises e simulações verificadas.

Cenário: "Estoque/Preço não estão sendo atualizados"
Como investigar: Antes de seguir com a investigação, é necessario entender como funciona o Fluxo de atualização de preço e estoque para o Marketplace:

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. Como no Facebook não há envio de quantidade de estoque (somente sku disponível ou indisponível), só iremos tratar a parte de atualização de preço:

1. Cliente altera preço no pricing:
Verificar histórico de alteração da informação no splunk. Assim, obter a informação de data e hora da última atualização de informação.

2. 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=NotifyAffiliatesAboutStockChangeAsync

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

Se for estoque ou preço, pesquisar pela seguinte query: index=facebookintegration account={{accountName}} workflow_instance={{skuId}} workflow_type=CatalogBatchWorker

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 checkout 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 checkout para consultar os valores de estoque e preço que serão enviados ao marketplace. 

API de checkout:
POST http://{{accountName}}.vtexcommercestable.com.br/api/checkout/pvt/orderForms/simulation?sc={{políticacomercial}

1. Se a simulação de checkout 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 checkout 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: "Produtos estão chegando no Facebook mas não aparecem nos Filtros de Catalogo"
Como Investigar: Caso você esteja tentando auxiliar o cliente na integração e configuração do Facebook e ao criar um catalogo perceber que os filtros não estão exibindo todos os produtos, tente esse processo:

Vale lembrar que o Facebook não mostra produtos com fotos iguais: "Se vários itens de um conjunto tiverem a mesma imagem, apenas uma será exibida nos anúncios."

1. Verifique no Bridge a quantidade de produtos enviados e compare com os produtos ativos no painel do Facebook. Caso esse valor esteja igual, todos os produtos estão chegando na plataforma.

2. Verifique se os filtros estão corretos durante a criação do catalogo.

3. Se os filtros estiverem corretos e mesmo assim nem todos os produtos estiverem disponíveis, leia essa FAQ sobre as melhores práticas para uso do catalogo 
https://pt-br.facebook.com/business/help/741923962861190?id=725943027795860&locale=pt_BR

QUESTIONS | SETTINGS

Cenário: "Como funciona a planilha de mapeamento"
Como Investigar: A planilha de mapeamento é essa: https://docs.google.com/spreadsheets/d/1BUQZsVhiUGlqiunwzAWEQdOd8GpgM2WV/edit#gid=285886376

​

1. A coluna “ID Category” deverá ser preenchida com o Id da Categoria na VTEX que você deseja integrar com o Facebook; 
2. “VTEX attribute name” é o nome correspondente na VTEX do atributo que você deseja mapear, exemplo “cor” na sua loja pode estar cadastrado como “cores”; 
3. “Facebook attribute name” é a coluna com os valores permitidos para os atributos no Facebook, os únicos que eles aceitam são os que estão listados aqui:

- Color
- Condition
- Gender
- Size

4. “VTEX attribute value” é como o atributo está preenchido na VTEX, por exemplo, um atributo de cor pode estar preenchido com o valor de “vermelho”.
5. “Facebook attribute value” é a coluna para os valores permitidos no Facebook dos atributos de condição e gênero (condition e gender).

Para condition (condição), os valores permitidos são:

- New
- Refurbished
- Used

Para gender (gênero), os valores permitidos são:

- male
- female
- unisex

Para color (cor) e size (tamanho), qualquer valor pode ser preenchido na última coluna.

Cenário: Skus com erro "Review your account permission on Facebook"
Como investigar:  Para solução destes casos o seller deve refazer o processo de autenticação seguindo os passos do cenario "Refazer o processo de autenticação"

Cenário: Skus com erro "{"error":{"message":"(#200) Permissions error","type":"OAuthException","code":200,"
Como investigar:  Para solução destes casos o seller deve refazer o processo de autenticação seguindo os passos do cenario "Refazer o processo de autenticação"

Cenário: "Refazer o processo de autenticação"
Como investigar:  Esse processo é indicado quando a integração está com algum problema de autenticação com o Facebook, ou mesmo que autenticado com sucesso esteja apresentando erro de permissão no envio ou atualização do catálogo.

PASSOS IMPORTANTES
- Desligar app FBE (se ativo)
- Desligar card integração com o facebook 
- Importante: Usar aba anônima/sem cache de preferencia em outro navegador;
- Refazer processo de autenticação;
- IMPORTANTE: CX solicitar carga sku após finalizar processo de autenticação
caso o seller deixe ativo o ativo o FBE por exemplo e tenha desligado apenas o card da integração com o facebook, o processo de autenticação não vai funcionar.

1° - Excluir o App de integração da VTEX no Facebook 
O usuário do Facebook (dono da conta vinculado à configuração na VTEX) deve acessar o menu suspenso do Facebook na página inicial e em seguida a opção Configurações.
Acesse: Perfil do cliente no Facebook, escolha "Configurações" > Segurança e Login:

Vá até "Integrações comerciais" e clique em "Remover" no app da VTEX:

Em seguida, excluir o catálogo da VTEX no Facebook Manager:

3º Excluir a configuração de integração do Facebook na VTEX.
Depois disso, desative a integração no card do Facebook na VTEX

4° Refazer a configuração do Facebook na VTEX.
Aqui é muito importante que esta configuração seja feita sem cache/aba anonima.
Atenção após refazer a configuração, é muito importante que na etapa de autenticação com o Facebook seja concedida as permissões solicitadas pelo APP, sem exceções.

5° Solicitar ao time de connections uma carga geral para integração de todos os skus.