Cenário
Seu time de marketing usa HubSpot. Cada vez que um lead é qualificado e ganha a tagPago Anual lá, você quer que essa pessoa apareça na sua comunidade Cativa com o badge Premium (que dá acesso ao grupo VIP, ao curso pago, etc.). Quando a tag é removida (ou o cliente cancela), o badge precisa sair.
A Cativa é a fonte de verdade da comunidade (quem está no grupo, quem completou qual lição, quem postou o quê). O CRM é a fonte de verdade da relação comercial (lead, oportunidade, cliente, churn). A integração faz a ponte entre os dois.
Pré-requisitos
- API Key da Cativa — gerada no Console (Developers > API Keys). Veja Quick Start: API Key.
- Acesso de API ao seu CRM — token do HubSpot, da RD Station, etc. A Cativa não fornece SDK pra esses CRMs; use os SDKs oficiais (
@hubspot/api-client,pipedrive-node-sdk, etc.). - Um servidor de integração rodando do seu lado — pode ser um worker Node, um Cloud Function/Lambda, um job no Airflow, qualquer coisa que execute código com acesso aos dois lados.
Mapeamento conceitual
A pergunta central é: como reconhecer que o contato1234 no HubSpot é o mesmo usuário 01HQ7Z3X4Y... na Cativa?
| HubSpot | Cativa |
|---|---|
| Contact ID | User ID |
| Email (chave natural) | |
Tag Pago Anual | Badge Premium |
email — ela está dos dois lados desde o cadastro. Você pode opcionalmente criar uma propriedade custom no HubSpot chamada cativa_user_id pra cachear o User ID Cativa após o primeiro casamento e evitar lookup por email a cada execução.
A Cativa não tem hoje um campo
external_id no User que permita associar diretamente a chave do seu CRM. A chave natural é o email. Quando esse campo for adicionado ao modelo público, esta página será atualizada com a opção de upsert por external_id.Dois fluxos possíveis
- Pull-based (worker periódico)
- Webhook-based (event-driven)
Quando usar: você não tem webhook do CRM disponível, ou os volumes são pequenos (até alguns milhares de contatos), ou um delay de minutos/horas é aceitável.Um worker do seu lado roda numa frequência (ex: a cada 15 minutos), lê o estado do CRM, lê o estado da Cativa, calcula o diff e aplica.Prós: simples de implementar, fácil de debugar, fácil de fazer backfill.
Contras: delay (não é real-time), gasto desnecessário de API calls quando nada mudou.
Descobrir um usuário existente na Cativa
Hoje há um endpoint público que você pode chamar com sua API Key:GET /social/v1/auth/me — retorna o usuário dono da chave (não busca usuário arbitrário). Use isso para sanity-check da sua credencial e descobrir o customer (tenant) ao qual a chave pertence.
Para buscar um usuário arbitrário pelo email (que é o caso da sincronização CRM), o endpoint público usando API Key está em desenvolvimento. Hoje, esse lookup usa um endpoint admin (
/social/v1/admin/users/email/{email}) que não está disponível para API Keys de parceiro — apenas para o admin do tenant logado no Console.Workaround atual: alinhe com o time da Cativa em dev@cativa.digital para liberar o lookup do seu cenário, ou use o evento de webhook user_created (vide abaixo) para popular sua própria tabela de mapeamento email → Cativa User ID conforme novos usuários entram.Estratégia recomendada hoje: tabela de mapeamento populada via webhook
Em vez de fazer lookup por email a cada sync, mantenha uma tabela do seu lado:- Cadastre um listener Cativa pro evento
user_created— toda vez que alguém entra na comunidade, o webhook chega comUser.IdeUser.Email. Insere/atualiza essa linha. - Cadastre um listener pro evento
user_received_badge— toda mudança de badge atualiza a linha.
email → cativa_user_id localmente, sem precisar bater na API da Cativa.
Criar usuário a partir do CRM
O endpoint público para parceiros criarem usuários via API Key está em desenvolvimento. Hoje, a criação acontece quando o próprio usuário se cadastra na comunidade (via Login com a Cativa, convite, ou link público de cadastro do tenant).Workarounds atuais:
- Convite por email — gere um link de cadastro do tenant e envie via seu CRM (HubSpot Email, RD Station Email). Quando o lead clica e completa o cadastro, o evento
user_createdchega no seu webhook e você consegue dar o badge logo em seguida. - Importação em lote — para grandes massas iniciais (milhares de contatos), o time da Cativa consegue importar uma planilha via Console. Alinhe em dev@cativa.digital.
Atribuir badge
A atribuição de badge via API Key de parceiro está em desenvolvimento. Hoje, atribuição/remoção de badges é feita:
- Manualmente no Console do tenant (admin), ou
- Via importação em massa (planilha), ou
- Em produção, via fluxos automáticos da plataforma (compra paywall, conclusão de curso) — não via API direta de parceiro.
Esqueleto de worker pull-based
Mesmo com os endpoints de write em desenvolvimento, vale modelar o worker hoje. O que está dentro deassignBadge/removeBadge é o que precisa esperar.
Tratar conflitos
| Cenário | O que fazer |
|---|---|
| Email mudou no CRM, ainda não mudou na Cativa | Cativa é fonte do cativa_user_id. Se o email do contato HubSpot mudou e você não consegue mais casar pelo novo email, mantenha o cativa_user_id cacheado (no crm_cativa_mapping) e atualize a coluna email quando for diferente. O usuário Cativa ainda existe — o que mudou foi o ângulo do CRM. |
| Email do CRM nunca apareceu na Cativa | O contato HubSpot não tem (ainda) um usuário Cativa correspondente. Envie convite ou ignore até ele se cadastrar. Não tente “criar” forçadamente até o endpoint público estar disponível. |
| Mesmo email aparece em dois contatos no CRM | Decisão do seu lado de qual contato é canônico (geralmente o mais recente, ou o que tem lifecyclestage mais avançado). Trate antes de chamar a Cativa. |
| Cliente cancelou no CRM mas tem badge ativo na Cativa | Esse é o caso que o sync de remoção resolve. O fluxo runSync acima cobre. |
| Badge atribuído por outra fonte (compra paywall) e CRM não sabe | A Cativa pode atribuir badges por outros caminhos (compra paywall, conclusão de curso). Se seu CRM não for fonte de verdade pra esse badge específico, não remova o badge no diff — adicione um filtro do lado seu (ex: só sincronize badges que vieram via tag CRM). |
Erros comuns
O sync derrubou badges atribuídos por outras fontes
O sync derrubou badges atribuídos por outras fontes
Quando o seu worker é a única autoridade sobre um badge e ele não vê motivo no CRM, ele remove. Mas se o badge foi atribuído por outra fonte (compra paywall, importação manual), o sync apaga indevidamente.Solução: mantenha uma lista de “badges gerenciados pelo CRM” no seu worker. Só atribua e remova esses. Badges fora da lista são ignorados pelo diff.
Rate limit ao processar muitos contatos
Rate limit ao processar muitos contatos
Em syncs grandes (milhares de contatos), você pode bater rate limit no CRM ou na Cativa. Implemente:
- Backoff exponencial em 429 (a Cativa respeita
Retry-After). - Paginação no CRM (ex:
getPage(100, after, ...)no HubSpot). - Paralelismo controlado (ex:
p-limit(5)no Node).
Webhook do user_created não chegou — usuário ficou fora da tabela de mapeamento
Webhook do user_created não chegou — usuário ficou fora da tabela de mapeamento
Se você só popula
crm_cativa_mapping via webhook, qualquer disparo perdido vira lacuna. Por isso recomendamos:- Um reconcile job semanal que pega todos os contatos do CRM com email e tenta dar match com os usuários conhecidos.
- Logging do
X-Cativa-Execution-Idem todo webhook recebido — se faltar, dá pra abrir ticket de investigação.
Email diferente entre CRM e Cativa do mesmo usuário
Email diferente entre CRM e Cativa do mesmo usuário
Acontece quando o usuário usa email pessoal pra comprar e email corporativo pra entrar na comunidade (ou vice-versa). Não tem solução automática — você precisa uma propriedade adicional no CRM (ex:
community_email) e usar essa pro lookup em vez do email principal.Próximos passos
Subscrever webhooks Cativa
Configure listeners para
user_created e user_received_badge para manter sua tabela de mapeamento atualizada.Liberar acesso via compra externa
O caso específico de “compra externa → badge” tem padrões e cuidados próprios.
