Sincronizar membros do CRM

A maioria dos parceiros já tem um CRM (HubSpot, RD Station, Pipedrive, ActiveCampaign, Salesforce) que é a fonte de verdade dos contatos. Este guia mostra como manter a comunidade Cativa em sincronia com o CRM usando a API administrativa (lookup por email, criação de usuário, vínculo de external-id, atribuição de badge) e quais as decisões de design (chave natural, conflitos, idempotência) que você precisa tomar.

Cenário

Seu time de marketing usa HubSpot. Cada vez que um lead é qualificado e ganha a tag Pago 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. Todas as chamadas abaixo usam Authorization: Bearer cativa_live_....
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 contato 1234 no HubSpot é o mesmo usuário 01HQ7Z3X4Y... na Cativa?

HubSpot	Cativa
Contact ID	User ID (ULID)
Email	Email (chave natural)
Tag `Pago Anual`	Badge `Premium`

A chave natural recomendada é o email (ela está dos dois lados desde o cadastro). Depois do primeiro casamento, cacheie o vínculo dos dois lados: guarde o Contact ID do CRM no usuário Cativa com PATCH /admin/users/{userId}/external-id e, se quiser, guarde o User ID Cativa numa propriedade custom do CRM (ex: cativa_user_id). Assim você para de depender de lookup por email a cada execução.

A Cativa tem um campo de ID externo no User, gravável via PATCH /admin/users/{userId}/external-id. Use-o como a forma canônica de vincular a chave do seu CRM ao usuário Cativa. Com o vínculo persistido no próprio usuário, a tabela de mapeamento local (descrita abaixo) vira opcional (só uma otimização de cache do seu lado).

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.

cron 15 min ─→ pull HubSpot ─→ pull Cativa ─→ diff ─→ apply

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.

Quando usar: o CRM oferece webhook quando uma propriedade muda (HubSpot Workflow, RD Station Automation), e você quer sincronia em segundos.O CRM dispara webhook pro seu servidor quando uma tag muda → seu servidor chama a API da Cativa pra atribuir/remover o badge.

HubSpot tag muda ─→ webhook seu servidor ─→ API Cativa

Prós: baixo delay, eficiente. Contras: mais código (HMAC verification do webhook do CRM, retry/backoff, dedupe), e ainda assim você quer um worker pull-based de reconciliação semanal pra cobrir webhooks perdidos.Você também pode subscrever os webhooks da Cativa (user_received_badge, user_created) pra refletir mudanças do lado da comunidade de volta no CRM. A página Cadastrando e verificando webhooks mostra como verificar a assinatura HMAC dos disparos da Cativa.

Descobrir e vincular um usuário existente

O casamento pelo email é o coração da sincronização. Faça uma vez por contato e persista o vínculo no próprio usuário Cativa.

Resolva o email para o usuário Cativa

GET /admin/users/email/{email} retorna o usuário com aquele email no tenant da sua chave. Este é o caminho canônico da sincronização CRM.

curl "https://apis.cativalab.digital/tenant/api/v2/admin/users/email/joao%40empresa.com" \
  -H "Authorization: Bearer cativa_live_..."

import requests, urllib.parse

email = urllib.parse.quote("joao@empresa.com")
res = requests.get(
    f"https://apis.cativalab.digital/tenant/api/v2/admin/users/email/{email}",
    headers={"Authorization": f"Bearer {api_key}"},
)
user = res.json() if res.status_code == 200 else None

Resposta 200 OK (ilustrativa; schema completo na API Reference, tag Users):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "joao@empresa.com",
  "firstName": "João",
  "lastName": "Silva",
  "externalId": null,
  "createdAt": "2026-07-01T14:22:03Z"
}

Se o email não existe no tenant, o endpoint responde 404 Not Found, trate esse caso como “criar usuário” (seção abaixo):

{ "error": "User.NotFound", "message": "No user with that email in this tenant" }

Grave o Contact ID do CRM no usuário Cativa

Capture o id do retorno e, logo em seguida, grave o Contact ID do seu CRM no usuário com PATCH /admin/users/{userId}/external-id:

curl -X PATCH https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7Z3X4Y.../external-id \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "1234" }'

Resposta 200 OK (ilustrativa) com o vínculo já refletido:

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "joao@empresa.com",
  "externalId": "1234"
}

Com o vínculo persistido no próprio usuário Cativa, os próximos syncs não precisam mais refazer o lookup por email.

Se sua chave é dona de um usuário e você só quer conferir a credencial e o tenant, GET /tenant/api/v2/auth/me retorna o usuário dono da chave e o customer (tenant) ao qual ela pertence:

curl https://apis.cativalab.digital/tenant/api/v2/auth/me \
  -H "Authorization: Bearer cativa_live_..."

Resposta 200 OK (ilustrativa):

{
  "user": { "id": "01HQOWNER0000000000000000", "email": "integracao@empresa.com" },
  "customer": { "id": "01HQTENANT000000000000000", "name": "makers" }
}

Opcional: tabela de mapeamento local como cache

O external-id no usuário Cativa já resolve o vínculo. Se ainda assim você quiser evitar toda ida à API da Cativa (por latência ou custo), mantenha uma tabela de cache do seu lado:

crm_cativa_mapping
─────────────────
hubspot_contact_id  TEXT
cativa_user_id      TEXT   -- ULID
email               TEXT
last_synced_at      TIMESTAMP

E popule via webhook:

Cadastre um listener Cativa pro evento user_created. Toda vez que alguém entra na comunidade, o webhook chega com User.Id e User.Email. Insere/atualiza essa linha.
Cadastre um listener pro evento user_received_badge. Toda mudança de badge atualiza a linha.

Depois disso, seu worker de sync resolve email para cativa_user_id localmente. Trate a tabela como cache: a fonte de verdade do vínculo continua sendo o external-id gravado no usuário Cativa.

Criar usuário a partir do CRM

Quando o contato do CRM ainda não existe na Cativa (o lookup por email retorna 404), crie o usuário com POST /admin/users. Aproveite e já grave o externalId no mesmo request:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/users \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@empresa.com",
    "firstName": "João",
    "lastName": "Silva",
    "externalId": "1234"
  }'

Resposta 201 Created (ilustrativa), guarde o id (e o externalId já vinculado) para os próximos syncs:

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "joao@empresa.com",
  "firstName": "João",
  "lastName": "Silva",
  "externalId": "1234",
  "createdAt": "2026-07-10T09:00:00Z"
}

O schema completo do body está na aba API Reference, tag Users. Se preferir que o próprio usuário defina a senha, envie o link de cadastro do tenant pelo seu CRM (HubSpot Email, RD Station Email) em vez de criar via API. Para grandes massas iniciais (milhares de contatos), o time da Cativa também importa uma planilha via Console. Alinhe em dev@cativa.digital.

Atribuir badge

A atribuição de badge por API Key administrativa está disponível. Há duas formas, sob /admin/membership/badges: Por email (ideal pro CRM, dispensa resolver o userId antes):

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/PREMIUM_BADGE_ID/users/by-email \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "joao@empresa.com" }'

Por id (quando você já tem o userId Cativa em cache):

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/PREMIUM_BADGE_ID/users/01HQ7Z3X4Y... \
  -H "Authorization: Bearer cativa_live_..."

Resposta 200 OK (ilustrativa; schema completo na API Reference, tag Badge):

{
  "userId": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "badgeId": "01HQBADGEPREMIUM0000000000",
  "assignedAt": "2026-07-10T09:01:12Z"
}

Para remover, use o DELETE no mesmo recurso por id:

curl -X DELETE https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/PREMIUM_BADGE_ID/users/01HQ7Z3X4Y... \
  -H "Authorization: Bearer cativa_live_..."

No worker, as funções de atribuir e remover chamam esses endpoints direto:

async function assignBadge(cativaUserId, badgeId) {
  const res = await fetch(
    `https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/${badgeId}/users/${cativaUserId}`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
    }
  );
  if (!res.ok) throw new Error(`Badge assign failed: ${res.status}`);
}

async function removeBadge(cativaUserId, badgeId) {
  const res = await fetch(
    `https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/${badgeId}/users/${cativaUserId}`,
    {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
    }
  );
  if (!res.ok) throw new Error(`Badge remove failed: ${res.status}`);
}

A Cativa garante que atribuir o mesmo badge duas vezes é idempotente, o estado final é o mesmo (a segunda chamada responde sucesso sem duplicar). Mesma coisa pra remover badge que já não está atribuído. Isso simplifica retries no seu worker (ver Badges como permissão).

Esqueleto de worker pull-based

Com os endpoints de write disponíveis, o worker abaixo roda ponta a ponta. As funções assignBadge/removeBadge (definidas acima) já batem na API real.

import { Client as HubSpotClient } from '@hubspot/api-client';

const hubspot = new HubSpotClient({ accessToken: process.env.HUBSPOT_TOKEN });
const PREMIUM_BADGE_ID = process.env.CATIVA_PREMIUM_BADGE_ID;

async function syncContact(contact) {
  const email = contact.properties.email;
  if (!email) return; // sem email, não tem como casar

  // 1. Resolve email → Cativa User ID (tabela local populada via webhook)
  const mapping = await db.crmCativaMapping.findOne({ email });
  if (!mapping) {
    // Usuário ainda não está na Cativa. Envie um convite via CRM.
    await sendInviteEmail(email);
    return;
  }

  // 2. Estado desejado (HubSpot é a fonte de verdade)
  const shouldHavePremium = (contact.properties.lifecyclestage === 'customer'
    && contact.properties.deal_status === 'paid_annual');

  // 3. Estado atual (sua tabela local, atualizada via webhook user_received_badge)
  const hasPremium = await db.userBadges.exists({
    userId: mapping.cativaUserId,
    badgeId: PREMIUM_BADGE_ID
  });

  // 4. Aplica diff
  if (shouldHavePremium && !hasPremium) {
    await assignBadge(mapping.cativaUserId, PREMIUM_BADGE_ID);
  } else if (!shouldHavePremium && hasPremium) {
    await removeBadge(mapping.cativaUserId, PREMIUM_BADGE_ID);
  }
}

async function runSync() {
  let after;
  do {
    const page = await hubspot.crm.contacts.basicApi.getPage(100, after, [
      'email', 'lifecyclestage', 'deal_status'
    ]);
    for (const contact of page.results) {
      try {
        await syncContact(contact);
      } catch (err) {
        console.error(`Failed to sync ${contact.id}`, err);
        // Não interrompa o loop, registre e siga.
      }
    }
    after = page.paging?.next?.after;
  } while (after);
}

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. Crie o usuário com `POST /admin/users` (seção acima), ou envie convite e ignore até ele se cadastrar, conforme sua política.
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

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

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

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-Id em todo webhook recebido, se faltar, dá pra abrir ticket de investigação.

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.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Cenário

Pré-requisitos

Mapeamento conceitual

Dois fluxos possíveis

Descobrir e vincular um usuário existente

Opcional: tabela de mapeamento local como cache

Criar usuário a partir do CRM

Atribuir badge

Esqueleto de worker pull-based

Tratar conflitos

Erros comuns

Próximos passos

Subscrever webhooks Cativa

Liberar acesso via compra externa

​Cenário

​Pré-requisitos

​Mapeamento conceitual

​Dois fluxos possíveis

​Descobrir e vincular um usuário existente

​Opcional: tabela de mapeamento local como cache

​Criar usuário a partir do CRM

​Atribuir badge

​Esqueleto de worker pull-based

​Tratar conflitos

​Erros comuns

​Próximos passos

Subscrever webhooks Cativa

Liberar acesso via compra externa

Cenário

Pré-requisitos

Mapeamento conceitual

Dois fluxos possíveis

Descobrir e vincular um usuário existente

Opcional: tabela de mapeamento local como cache

Criar usuário a partir do CRM

Atribuir badge

Esqueleto de worker pull-based

Tratar conflitos

Erros comuns

Próximos passos