Skip to main content
O conector Brevo lê, pela API REST v3 da Brevo, a base de marketing (contatos, listas, atributos, campanhas de e-mail e de SMS com estatísticas) e o CRM (empresas, negócios, funis, tarefas e notas), além dos usuários da conta. Cada registro chega com a lista de pessoas que a Brevo libera para ele, calculada pelo módulo a que o registro pertence.

​
Capacidades

  • Lê contatos, listas de contatos, campanhas de e-mail e campanhas de SMS, com as estatísticas globais de cada campanha.
  • Lê empresas, negócios, os funis com seus estágios, tarefas, tipos de tarefa e notas do CRM.
  • Lê os usuários da conta, de onde sai a permissão de todos os outros recursos.
  • Separa os atributos de contatos, empresas e negócios: os atributos padrão viram colunas e os atributos que você criou na Brevo, como um CPF, viram linhas em tabelas próprias de valores.
  • Instala 23 tabelas clean prontas, com datas em UTC, e-mails em minúsculas, domínio de empresa normalizado e tabelas de ligação entre contato e lista, negócio e contato, negócio e empresa, empresa e contato, tarefa e entidade, nota e entidade, e campanha enviada e lista.
  • Alimenta o Memory com os nós Customer (contatos), Company, Agent (usuários), Deal, Stage, Task, Note, Audience (listas) e Campaign (campanhas de e-mail). Customer casa com nós de outros conectores pelo e-mail, Company pelo domínio e Agent pelo e-mail. Os nós só entram no grafo depois que a ontologia unificada é aplicada.
  • Aplica a permissão de cada usuário da Brevo por módulo, marketing ou CRM. Veja Permissões (ACL).

​
Recursos disponíveis

Todo recurso nasce desligado no Data Catalog e você escolhe quais carregar depois de conectar. As exceções:
  • users é carregado sempre, mesmo sem seleção, porque a permissão de todos os outros recursos é calculada a partir dele.
  • Os recursos de dicionário e de valores de atributo não têm opção própria: entram e saem junto com a entidade deles. contact_attribute_values e contact_attributes seguem contacts, company_attribute_values e company_attributes seguem companies, deal_attribute_values e deal_pipelines seguem deals, e task_types segue tasks.
As 23 tabelas clean da Brevo são instaladas quando você cria o conector, fora do contexto. Ligue no Data Catalog as que você quer usar. Cada uma é atualizada depois de cada sincronização. As colunas que ligam um recurso a outro (ids, listas de ids e o sent_date das campanhas de e-mail) ficam bloqueadas no Data Catalog: sem elas, as tabelas de ligação e as arestas do grafo sairiam vazias.

​
Como ler os dados

  • Toda data das tabelas clean é TIMESTAMPTZ em UTC. A Brevo entrega as datas com o fuso da conta, e o conector as converte.
  • brevo_contacts.email e o e-mail de brevo_users saem em minúsculas, sem espaços nas pontas. Um contato só com telefone fica com email NULL. phone é o número de SMS.
  • brevo_companies.domain é só o host do domínio: em minúsculas, sem http://, sem www. e sem caminho.
  • brevo_deals guarda o funil, o estágio e o responsável como ids. O nome do estágio e do funil está em brevo_deal_stages: junte stage_key (<funil>:<estágio>) com o external_id dela. O nome do responsável está em brevo_users: junte owner_id com o external_id dela. O valor em amount está na moeda do CRM da conta, que a API não informa.
  • brevo_notes.text é o HTML da nota, e text_plain é o mesmo texto sem tags.
  • brevo_contact_list_memberships tem uma linha por contato e lista, incluindo as listas de que o contato se descadastrou, com unsubscribed verdadeiro nesses casos.
  • brevo_email_campaign_sends só tem campanhas com data de envio.

​
Atributos e idioma da conta

A Brevo nomeia os atributos padrão de contato no idioma da conta. Uma conta em português tem NOME e SOBRENOME, e não FIRSTNAME e LASTNAME. O conector reconhece os nomes em inglês, português, francês, espanhol e alemão e os coloca nas colunas firstname e lastname. Em outro idioma, o nome e o sobrenome não ganham coluna e aparecem em contact_attribute_values. O valor de todo atributo que não é padrão é marcado como dado pessoal a mascarar, porque o nome do atributo é escolhido por você e pode guardar, por exemplo, um CPF. Veja dados pessoais.

​
Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em Comportamento dos dados, você escolhe entre dois modos: No modo “Espelhar a fonte”, a Strattum reconhece cada pessoa pelo e-mail. A Brevo não oferece login de terceiros, então não há vínculo de conta: assumimos que a pessoa usa na Brevo o mesmo e-mail que usa na Strattum.

​
Como a fonte define acesso

A Brevo dá acesso por usuário e por módulo da conta, nunca por registro. Cada usuário tem, por módulo, um nível: dono, acesso total, acesso personalizado ou nenhum. Responsável, autor e atribuído de um negócio, tarefa ou nota são dados do registro, não permissões.

​
Como a Strattum traduz o acesso

A cada execução, o conector lê os usuários da conta e decide, para cada um, se ele tem acesso ao marketing e ao CRM. Cada linha recebe as pessoas com acesso ao módulo do recurso dela: A decisão por usuário e módulo segue esta regra, sempre para o lado mais restrito: O usuário é gravado pelo e-mail, em minúsculas. Nenhum grupo ou time é gravado.

​
Quando a identidade não é encontrada

Quem usa na Brevo um e-mail diferente do da Strattum não vê nada desta conexão no modo “Espelhar a fonte”. O usuário recusado pela regra acima, por exemplo um acesso personalizado cuja consulta falhou, também fica sem acesso, e a sincronização registra no log quantos usuários foram recusados. Se nenhum usuário com acesso a um módulo for reconhecido, os registros desse módulo não aparecem para ninguém nesse modo.

​
Quando a permissão é atualizada

Todo recurso é relido por inteiro a cada execução, e a permissão de toda linha é recalculada junto. Uma mudança de acesso na Brevo vale a partir da próxima sincronização. A associação do e-mail da Brevo com a conta da Strattum é feita por uma rotina própria, a cada 10 minutos por padrão.

​
Pré-requisitos

  • Uma conta Brevo. Os recursos de CRM exigem o módulo CRM ativo na conta.
  • Uma chave de API REST da Brevo, que começa com xkeysib-, criada por um usuário com acesso à gestão de usuários da organização. Sem esse acesso, o teste de conexão falha, porque a permissão de todos os recursos depende da lista de usuários.
  • O IP de saída da VM da Strattum autorizado na Brevo, se a conta bloqueia IPs desconhecidos.
  • Uma só conexão Brevo por instalação da Strattum, com uma conta Brevo por conexão. Sub-contas não são lidas.

​
Autenticação e escopos

A autenticação é por chave de API, enviada no header api-key. A chave da Brevo não tem escopo: ela alcança a conta inteira. O que pode faltar é o módulo CRM na conta e a autorização do IP.
1

Crie a chave de API

Na Brevo, abra SMTP & API e vá em API Keys. Crie uma chave com um nome como strattum-sync e copie o valor que começa com xkeysib-.
2

Autorize o IP de saída

Clique no seu nome, no canto superior direito, e abra Security e depois Authorised IPs. Adicione o IP de saída da VM onde a Strattum roda. Na conta usada para construir o conector, o bloqueio de IPs desconhecidos já vinha ligado, e toda chamada de outro IP era recusada.
A Brevo responde com o mesmo código para chave inválida e para IP não autorizado. O teste de conexão do Console lê a mensagem e mostra cada caso separado. Se o teste disser que o IP foi recusado, a chave está certa: autorize o IP em vez de trocar a chave.
A chave dá acesso à conta Brevo inteira. Guarde-a em local seguro e nunca a comite em repositórios.

​
Configuração no Console

1

Abra o assistente

Em Conectores, clique em + Nova Conexão e selecione Brevo.
2

Preencha a conexão

Nome do Conector (Opcional): como a conexão aparece na lista. O padrão é Brevo.Chave de API (Obrigatório): a chave xkeysib-.... O Console recusa uma chave com outro prefixo e avisa quando você cola a chave SMTP.
3

Teste a conexão

Clique em Testar Conexão. Você só avança depois de um teste com sucesso ou com ressalvas. O teste faz três chamadas: valida a chave, lê a lista de usuários e lê um negócio. Se o CRM não estiver disponível, o resultado é “Conectado à Brevo, mas o CRM não está acessível.” e você pode seguir só com os recursos de marketing.
4

Escolha a frequência

Em Sincronização (Obrigatório), escolha a frequência. Veja Rate limits antes de escolher uma frequência alta.
5

Defina o acesso

Em Permissionamento:Quem pode usar este conector (Obrigatório): “Todos os usuários”, o padrão, ou “Apenas times específicos”. Com times específicos, escolha ao menos um time.Comportamento dos dados (Obrigatório): o assistente começa em “Aberto”. Escolha “Espelhar a fonte” para que cada pessoa veja só o que a Brevo libera para ela.
6

Revise e salve

Em Revisão, confira os dados e salve. A chave não aparece.
7

Ligue os recursos no Data Catalog

No Data Catalog, ligue os recursos e as tabelas clean que você quer carregar. Todos rodam em full refresh.
Para trocar a chave depois, abra o conector em Conectores e cole a nova chave. O campo em branco mantém a chave guardada.

​
Como a sincronização funciona

A frequência vem do passo Sincronização. Cada execução segue esta ordem:
  1. Lê os usuários da conta e calcula quem tem acesso ao marketing e ao CRM. Se a lista de usuários não puder ser lida, a execução falha antes de gravar qualquer dado.
  2. Lê cada recurso ligado no Data Catalog, um por vez, na ordem da tabela de recursos.
  3. Monta as tabelas clean.
Leitura completa antes de gravar. Cada recurso é lido por inteiro e só então gravado, substituindo a tabela anterior. Durante a leitura, os registros ficam num arquivo temporário no disco do worker, que é apagado ao fim. Se uma página falha no meio, a tabela anterior do recurso fica como estava. A leitura falha, em vez de gravar uma tabela incompleta, quando a Brevo devolve uma página vazia antes do total anunciado ou uma página fora de sequência. Paginação. Contatos, empresas, negócios, tarefas, notas e campanhas de SMS são lidos de 1.000 em 1.000, campanhas de e-mail de 100 em 100 e listas de 50 em 50. Toda listagem paginada é lida em ordem crescente, para que um registro criado durante a leitura entre depois da última página em vez de duplicar uma linha. Os dicionários, os funis e os usuários vêm numa chamada só. Atributos. contact_attribute_values, company_attribute_values e deal_attribute_values saem da mesma listagem da entidade, que é lida de novo para eles. Por isso contatos, empresas e negócios são lidos duas vezes por execução. Remoção. Todo recurso é full refresh, então um registro apagado na Brevo some da tabela na execução seguinte. Falhas.

​
API da fonte

Todas as chamadas só leem dados. O host da API é https://api.brevo.com/v3. O conector envia um User-Agent próprio, porque a Brevo bloqueia o User-Agent padrão de algumas bibliotecas HTTP em alguns endpoints, e não segue redirecionamentos, para que a chave não seja enviada a outro host. Rate limits. A Brevo define limites por plano. Em todos os planos, os endpoints de contatos aceitam 36.000 chamadas por hora e 10 por segundo, e os demais endpoints, 100 por hora. Nos planos Professional e Enterprise, os contatos sobem para 72.000 por hora e 20 por segundo, e os demais para 200 por hora. No Enterprise, até 60 por segundo nos contatos e 600 por hora nos demais. Passando do limite, a API responde 429 e informa no header x-sib-ratelimit-reset quantos segundos faltam para a janela reiniciar. Na conta usada para construir o conector, medimos 20 chamadas por segundo em /contacts e /contacts/lists, e 100 por hora para cada um de /emailCampaigns, /smsCampaigns e /organization/invited/users, em contadores separados. Os endpoints de CRM não devolveram header de limite. O conector envia uma chamada por vez, com tempo limite de 60 segundos. Diante de um 429, espera o tempo do header x-sib-ratelimit-reset, com mínimo de 1 segundo e máximo de 15 minutos. Sem o header, espera 2, 4, 8 e 16 segundos. Depois de 4 esperas, o recurso falha. Erros 5xx e quedas de conexão têm até 4 novas tentativas, com espera de 1, 2, 4 e 8 segundos. Um bloqueio da Cloudflare da Brevo (403) não é repetido. Cada execução lê a lista de usuários duas vezes, uma para a permissão e outra para o recurso users, e faz uma chamada a mais por usuário com acesso personalizado. Cada teste de conexão gasta mais uma chamada nesse limite de 100 por hora. Campanhas de e-mail custam uma chamada a cada 100 campanhas. Uma frequência de uma hora cabe nesses limites com menos de 100 campanhas e poucos usuários com acesso personalizado. Referência oficial: Brevo, API rate limits

​
Limitações conhecidas

  • Todo recurso é full refresh. Não há carga incremental: a Brevo não tem endpoint de registros apagados, e as estatísticas de campanha continuam mudando depois do envio.
  • A permissão é por usuário e módulo. Se o acesso personalizado da Brevo restringir um usuário a parte dos registros de um módulo, como os próprios negócios, essa restrição não é representada.
  • O formato das permissões de acesso personalizado não foi conferido com dado real. Se a Brevo listar as permissões por funcionalidade em vez de por módulo, todo usuário com acesso personalizado fica sem acesso no modo “Espelhar a fonte”. Donos e usuários com acesso total não são afetados.
  • No modo “Espelhar a fonte”, a pessoa só é reconhecida se usar na Brevo o mesmo e-mail que usa na Strattum. Não há vínculo de conta.
  • O dicionário de atributos de negócio fica de fora, porque a Brevo responde com erro 500 permanente nesse endpoint numa conta nova. Os valores dos atributos de negócio são lidos normalmente.
  • E-mail transacional (envios e eventos), remetentes, pastas, segmentos, conversas e sub-contas ficam de fora. O HTML das campanhas e das notas não vai para o Knowledge: o HTML das campanhas não é lido, e o das notas fica como texto na tabela.
  • O nome e o sobrenome de contatos só viram coluna nos idiomas de conta inglês, português, francês, espanhol e alemão.
  • Os campos de campanhas de SMS seguem a documentação da Brevo e não foram conferidos com dado real.
  • Um registro apagado na Brevo durante a leitura pode fazer o conector pular um registro naquela execução. A execução seguinte o recupera.
  • Durante a gravação de cada recurso, os registros ficam num arquivo temporário no disco do worker, antes de os dados pessoais serem mascarados. Ocupa cerca de 1 KiB por contato e é apagado ao fim da gravação. Esse disco é compartilhado com outros serviços da Strattum na mesma VM. Se o worker for interrompido à força, o arquivo fica no disco até a próxima sincronização da Brevo.
  • As colunas que ligam os recursos ficam bloqueadas no Data Catalog, e uma política de dados pessoais não pode ser aplicada a elas.
  • Um atributo que você criou na Brevo nunca serve para casar registros com outros conectores.
  • Uma conexão Brevo por instalação da Strattum, e uma conta Brevo por conexão.

​
Troubleshooting

​
Próximos passos

Data Catalog

Ligue os recursos e as tabelas clean da Brevo e acompanhe a carga.

Memory

Veja como contatos, empresas, negócios e usuários viram nós do grafo de conhecimento.
A sincronização lê a chave só da conexão cadastrada pelo Console, que a guarda no cofre de credenciais com o nome BREVO_API_KEY. Não há variável de ambiente para a chave.O arquivo temporário de cada recurso vai para a pasta brevo dentro de DUCKDB_TEMP_DIRECTORY quando a variável existe, e para a pasta temporária do sistema quando não existe.Na Brevo, autorize o IP de saída da sua máquina ou da stack local. Os containers podem sair por IPv4 mesmo quando a máquina tem IPv6.Veja o guia de configuração local para subir o Prefect e o worker.