API e integrações 3 min de leitura

API pública e integrações

Pra que serve a API

Pra fazer tudo que gera cliente terminar no CRM: o formulário do site, o sistema de gestão, a automação montada no n8n.

Com ela você cadastra leads do site direto no funil, sincroniza contatos e empresas, cria atividades, consulta relatórios e recebe avisos automáticos (webhooks) quando uma oportunidade muda. São 38 endpoints REST sobre oportunidades, contatos, empresas, atividades, funis e relatórios.

A referência completa, com exemplos de código e a resposta de cada endpoint, fica em [Referência da API](/guia/api). Dentro do CRM, a mesma documentação está em Documentação da API (/docs/api).

Como criar uma chave de API

Vá em Configurações → Chaves de API (/settings/api-keys). Só dono ou admin acessa.
Crie uma nova chave e dê um nome que identifique o uso ("n8n produção").
Copie o token completo (formato rmk_...).

Dica do Rainmaker

O token aparece uma única vez, na criação. O sistema guarda só uma versão criptografada — se perder, revogue e crie outra. Guarde num cofre de segredos, nunca no código do site.

Cada chave pertence a um único workspace: as chamadas só enxergam e alteram dados daquele workspace. Revogar vale na hora — a próxima chamada com ela recebe 401.

Como autenticar as chamadas

Envie o token no header de cada requisição: Authorization: Bearer rmk_... (o header X-API-Key também é aceito).

Use a chave apenas em servidor — backend, função serverless, n8n, Make ou Zapier. A chave nunca deve aparecer no navegador.

Limites de uso

100 requisições por minuto por chave, com tolerância de pico de até 200.
Ao estourar, a API responde 429 com o header Retry-After dizendo quantos segundos esperar. Ferramentas como o n8n respeitam isso automaticamente.
Listagens são paginadas por cursor: use limit (até 100) e repasse o nextCursor da resposta anterior até hasMore vir false.

Como receber webhooks

Webhooks avisam o seu sistema quando algo acontece no CRM — oportunidade criada, ganha, perdida, contato atualizado, atividade concluída, entre outros.

Vá em Configurações → Webhooks (/settings/webhooks).
Cadastre a URL do seu sistema e escolha os eventos.
Valide cada entrega com o header X-Webhook-Signature (HMAC-SHA256 do corpo, usando o secret exibido no cadastro).

Entregas com falha são retentadas até 6 vezes, com intervalos crescentes (de 1 minuto a 24 horas). Depois de 50 falhas consecutivas o webhook é desativado; reative depois de corrigir a URL.

Erros comuns

401 UNAUTHORIZED: token ausente, com formato errado ou revogado. Confira o header Authorization e se a chave ainda existe.
404 NOT_FOUND: o recurso não existe ou pertence a outro workspace.
422 VALIDATION_ERROR: algum campo do body é inválido; o campo details lista o que corrigir.
429 RATE_LIMITED: limite estourado; espere o tempo do header Retry-After.

Dica do Rainmaker

Cada endpoint na Referência da API tem o cURL e o JavaScript prontos pra copiar.

O que a API não faz

Ela não dispara mensagem em massa pros seus contatos.

Você integra o que quiser e traz lead de onde quiser, mas o envio pro cliente continua passando por uma pessoa. É decisão de produto.

Esse artigo ajudou?