Cenário
Cliente compra “Curso Premium” na Hotmart. Em segundos, ele recebe acesso ao grupo “Alunos Premium” e ao curso na sua comunidade Cativa. A ponte entre os dois lados é o conceito de badge como permissão: o badgePremium é configurado no Console como requisito de acesso ao grupo e ao curso. Quando o usuário ganha o badge, o acesso aparece automaticamente. Quando perde, some.
Pré-requisitos
- API Key da Cativa: gerada no Console (Developers > API Keys). Veja Quick Start: API Key. Todas as chamadas usam
Authorization: Bearer cativa_live_.... - Badge configurado no Console: crie o badge
Premium(ou o nome do seu produto) e configure-o como requisito de acesso no grupo/curso correspondente. Veja Badges como permissão. - Webhook de compra do seu gateway: Hotmart, Kiwify, Eduzz e Stripe disparam webhook pra um endpoint do seu servidor quando uma compra é confirmada. Não aponte o webhook do gateway diretamente pra Cativa, você precisa de um servidor proxy que recebe, valida e traduz o evento.
- Email confiável do comprador: todos os gateways enviam o email no payload da compra. Esse é o ponto-de-junção com o usuário Cativa.
Arquitetura do fluxo
- Validar o webhook do gateway (cada um tem assinatura própria, confira a doc do gateway).
- Tratar idempotência (Hotmart pode disparar o mesmo webhook duas vezes).
- Logar o purchase ID do gateway pra auditoria/conciliação.
- Decidir o badge correto baseado em qual produto foi comprado.
user_received_badge pra disparar email de boas-vindas, atualizar CRM, ou registrar evento no analytics.
Implementação
Receber o webhook do gateway
https://meuapp.com/webhooks/hotmart).A Cativa não documenta o formato do webhook desses gateways, consulte a doc oficial:Esqueleto do receiver (Express, exemplo Hotmart):Resolver ou criar o usuário na Cativa pelo email
User.Id dele pelo email com GET /admin/users/email/{email}.200 OK (ilustrativa; schema completo na API Reference, tag Users):email → cativa_user_id populada pelo webhook user_created da Cativa e faça o lookup local:404. Você tem duas opções:- Criar direto via API com
POST /admin/users(schema na API Reference, tag Users): cria a conta na hora e devolve oid, que você já usa pra atribuir o badge. - Convidar e completar depois: registre a intenção em
pendingGrants, envie o link de cadastro do tenant e complete a atribuição quando o webhookuser_createdchegar (ver step 4).
Atribuir o badge
productId do gateway pro badgeId da Cativa configurado no Console.A atribuição de badge via API Key de parceiro está disponível. Você tem duas opções:- Atribuir por email (
POST /admin/membership/badges/{badgeId}/users/by-email): não precisa resolver ouserIdantes; a Cativa faz o match pelo email do comprador. Ideal pro webhook, onde você só tem o email. - Atribuir por id (
POST /admin/membership/badges/{badgeId}/users/{userId}): quando você já tem ouserId(ex: veio do webhookuser_created).
200 OK (ilustrativa; schema completo na API Reference, tag Badge):userId já resolvido:purchaseId acima evita chamadas redundantes e ajuda na conciliação.(Opcional) Reagir ao webhook user_received_badge
user_received_badge toda vez que um badge é atribuído (não importa se foi via API, Console, ou outro fluxo). Cadastre um listener para ele se você quer:- Mandar email de boas-vindas com link pra comunidade
- Atualizar o status do contato no CRM
- Registrar conversão no analytics
Cancelamento e chargeback
Quando o gateway cancela ou faz chargeback, você quer remover o badge pra revogar o acesso.DELETE /admin/membership/badges/{badgeId}/users/{userId}. Veja o schema na aba API Reference (tag Badge). A remoção também é idempotente: remover um badge que já não está atribuído responde sucesso sem erro.Erros comuns
Comprador não tem cadastro Cativa, ficou com a compra paga e sem acesso
Comprador não tem cadastro Cativa, ficou com a compra paga e sem acesso
pendingGrants e dispare o convite. Subscreva o webhook user_created e, quando o cadastro acontecer, complete a atribuição:Email diferente entre o gateway e a Cativa do mesmo usuário
Email diferente entre o gateway e a Cativa do mesmo usuário
Webhook do gateway disparou duas vezes, usuário ganhou o badge duas vezes?
Webhook do gateway disparou duas vezes, usuário ganhou o badge duas vezes?
purchaseId do gateway numa tabela local e cheque antes:Gateway oferece assinatura recorrente, como tratar renovação mensal?
Gateway oferece assinatura recorrente, como tratar renovação mensal?
SUBSCRIPTION_CHARGE_SUCCESS). Trate como um handlePurchase idempotente, re-aplica o badge (sem efeito se já está). Se a renovação falha (ex: cartão recusado), trate como handleCancellation.Cliente reembolsou mas continuou usando a comunidade
Cliente reembolsou mas continuou usando a comunidade
Múltiplos badges para um mesmo produto (curso + bônus)
Múltiplos badges para um mesmo produto (curso + bônus)
Curso Premium libera tanto Premium (acesso ao curso) quanto Mentoria-2026 (acesso ao grupo de mentoria). Faça duas atribuições no handlePurchase.Próximos passos
Webhooks da Cativa
user_created (cobrir caso “comprou antes de cadastrar”) e user_received_badge (disparar ações pós-acesso).