Entendendo a sincronização de dados do Shopify com a Brevo

O Tajo move dados do Shopify para a Brevo de duas formas. O app Shopify do Tajo processa os webhooks do Shopify assim que chegam. As regras de sincronização são aprovadas por humanos, unidirecionais, executadas em lotes e registradas do início ao fim. Este artigo explica as duas, o que elas não incluem e as poucas coisas que o app Shopify do Tajo grava de volta no Shopify.

Verificação rápida Este artigo pressupõe que você já conectou o Shopify e a Brevo e publicou pelo menos uma regra de sincronização. Se ainda não fez isso, comece por conectar o Tajo ao Shopify.

À medida que os eventos acontecem: o app Shopify do Tajo

O app Shopify do Tajo se inscreve nos webhooks do Shopify e processa cada um assim que chega. As mudanças de clientes e produtos aguardam cerca de quatro segundos antes. Clientes, pedidos, checkouts, produtos, coleções e níveis de estoque chegam à Brevo dessa forma, junto com eventos como order_paid e cart_abandoned. O guia de integração com Shopify lista cada tópico e o que ele grava na Brevo.

O formato de uma regra de sincronização

Uma regra de sincronização é uma definição revisada e aprovada de exatamente o que se move e como. Um agente a cria a partir da sua descrição, e uma pessoa a aprova. Uma regra tem quatro partes que você pode inspecionar na sua página, em Connections > Syncs and mappings:

Parte	O que faz
Mapeamento de campos	Cada campo de origem, o campo da Brevo em que ele grava e qualquer transformação intermediária
Expressão de filtro	Avaliada por registro; registros que não correspondem são ignorados
Cursor	Rastreia até onde a sincronização avançou, para que cada execução continue de onde a última parou
Histórico de execuções	Cada execução, com registros lidos, gravados e com falha, além de duração e status

Uma regra de sincronização move dados em uma única direção: da sua fonte para a Brevo. Ela nunca grava no Shopify. O app Shopify do Tajo, porém, grava de volta no Shopify algumas coisas, como descadastramentos e tags de nível de fidelidade. Permissões do Shopify explicadas lista cada gravação e quando ela acontece.

Quando uma regra de sincronização roda

As regras de sincronização rodam em lotes. As regras de sincronização de contatos rodam a cada 15 minutos por padrão. Uma regra Shopify orders → Brevo orders ativa e publicada também roda a cada 15 minutos, mas só com o filtro de opt-in de marketing do comprador do template. Uma regra cujo filtro foi editado só roda quando você a inicia. A primeira execução agendada de uma regra de pedidos começa alguns minutos antes desse momento e não envia pedidos mais antigos. Cada execução seguinte envia os pedidos atualizados desde a anterior. Pedidos antigos só chegam à Brevo quando você mesmo executa a regra. A página de uma regra ativa tem um botão Test run (1 batch), e o agente Sync Operator executa as regras ativas quando você pede. Execuções em lote são o que torna cada gravação revisável, sujeita a orçamento e atribuível a uma execução específica.

Cada execução lê registros novos e alterados desde o cursor, aplica o filtro, mapeia os campos e grava na Brevo. O registro da execução mostra exatamente quantos registros foram lidos, gravados e com falha.

As garantias de governança

O consentimento falha fechado

Uma regra que grava dados pessoais na Brevo não pode ser publicada sem o filtro de consentimento e supressão. Em tempo de execução, um contato gravado em um público de marketing sem consentimento comprovável é recusado. Quando o consentimento não pode ser estabelecido, o Tajo recusa a gravação em vez de adivinhar. O modo de falha é sempre “cauteloso demais”, nunca “enviado demais”.

As execuções são idempotentes

Toda gravação carrega uma chave derivada do registro de origem. A chave é um hash, então não contém dados pessoais. Executar a sincronização novamente sobre os mesmos registros, depois de uma falha, de uma pausa ou manualmente, não cria gravações duplicadas.

Tudo é auditado

A publicação de uma regra, as aprovações invalidadas e as pausas automáticas são registradas em Activity. Cada decisão de aprovação traz uma justificativa escrita. Cada execução é registrada no histórico de execuções da regra. A aprovação que autorizou uma publicação fica vinculada a um digest da regra exata que passou pela pré-visualização. Editar a regra faz com que ela volte a ser rascunho e invalida a aprovação, então o que roda é sempre o que foi autorizado.

Falhas pausam a regra

Se cinco execuções seguidas falharem, um circuit breaker pausa a regra automaticamente e mostra o último erro na página da regra. Corrija a causa e publique novamente para retomar. Uma execução parcialmente falha reporta sua contagem de falhas, para que você veja exatamente o que não chegou ao destino.

Como os descadastramentos são respeitados

Quando um contato se descadastra pelo link no rodapé de um e-mail da Brevo, esse opt-out é registrado no contato e a Brevo o exclui de campanhas futuras.
Na sincronização de clientes em lote, o app Shopify do Tajo compara o momento do consentimento no Shopify com o momento do descadastramento na Brevo e mantém o mais recente.
Uma mudança de consentimento que chega do Shopify como webhook é gravada na Brevo do jeito que o Shopify a informa.
Se o contato estava inscrito no Shopify, o app Shopify do Tajo também o marca como descadastrado lá. Um evento da Brevo só move um cliente de inscrito para descadastrado. Ele nunca inscreve ninguém, então uma inscrição na Brevo não muda nada no Shopify.

Quais dados estão disponíveis

O app Shopify do Tajo envia contatos, pedidos, eventos de pedidos e de carrinho, o catálogo de produtos e o estoque. O que uma regra de sincronização envia depende do seu mapeamento de campos. Para clientes do Shopify, o modelo mapeia campos de identidade, total gasto, número de pedidos, tags e o opt-in para atributos de contato da Brevo que você pode usar em segmentos e campanhas. O mapeamento exato para o seu workspace não fica escondido em uma descrição: abra a regra de sincronização e leia a tabela de mapeamento de campos. Essa tabela é a resposta definitiva para “o que sincroniza”.

O que o Tajo não faz hoje

Ser preciso sobre os limites importa mais do que uma longa lista de recursos:

Nenhuma regra de sincronização bidirecional. Uma regra de sincronização só grava na Brevo. As gravações próprias do app Shopify no Shopify (descadastramentos, metacampos de engajamento e fidelidade da Brevo, tags de nível de fidelidade) estão listadas em Permissões do Shopify explicadas.
Nenhuma regra de sincronização em tempo real. As regras de sincronização rodam em lotes. Só a sincronização por webhooks do app Shopify do Tajo funciona à medida que os eventos chegam.
Nenhum botão de volta ao estoque. O app mantém o estoque dos produtos atualizado na Brevo e envia um evento back_in_stock aos compradores que pediram para ser avisados. O pedido precisa vir da sua vitrine: o app não adiciona um botão “Avise-me” ao seu tema.

Se um desses limites bloqueia um caso de uso para você, avise a equipe: as prioridades do acesso antecipado são moldadas exatamente por esse tipo de feedback.

Onde ver seus dados

No Tajo: abra a regra de sincronização em Connections > Syncs and mappings para ver histórico de execuções, posição do cursor e contagens por execução. Activity registra publicações e pausas automáticas.
Na Brevo: abra Contatos e inspecione os atributos de qualquer contato para confirmar que os campos mapeados estão sendo preenchidos. Construa segmentos sobre esses atributos para segmentação de público.

Solução de problemas

Contatos não aparecendo na Brevo: verifique a execução mais recente da regra em busca de falhas e o seu status (uma regra pausada não está em execução). Veja contatos ausentes na Brevo.
Execuções falhando repetidamente: o circuit breaker vai pausar a regra e mostrar o último erro. Veja dados não sincronizando.
Contatos duplicados: as gravações são idempotentes por registro de origem, mas duplicatas já existentes na Brevo permanecem. Veja contatos duplicados.

Perguntas frequentes

Posso deixar a sincronização mais rápida? A página de uma regra ativa tem um botão Test run (1 batch). Para mudanças à medida que acontecem, a sincronização por webhooks do app Shopify do Tajo já cobre clientes, pedidos, checkouts, produtos e estoque.

O que acontece se uma execução falhar no meio do caminho? A execução reporta sua contagem de falhas, o cursor avança apenas sobre o que foi processado, e a próxima execução recobre o terreno com segurança: as chaves de idempotência evitam duplicatas.

Posso mudar o que sincroniza? Sim. Peça ao agente para alterar o mapeamento de campos ou o filtro da regra. A edição faz com que a regra volte a ser rascunho, e ela precisa passar novamente pela pré-visualização e pela aprovação antes de rodar outra vez.

Por que minha regra se pausou sozinha? Falhas consecutivas de execução acionam o circuit breaker. A página da regra mostra a contagem de falhas e o último erro; corrija o problema e publique novamente.

Obtenha ajuda

Fale com a equipe.