API do CRM do Jordão
Integre o CRM com o seu site, n8n, planilhas ou qualquer sistema: 38 endpoints REST sobre negócios, contatos, empresas, atividades e relatórios. Toda a documentação abaixo é gerada do mesmo código que serve a API — o que está aqui é o que roda.
Autenticação
Cada request deve trazer uma API key workspace-scoped no header Authorization: Bearer rmk_... (alternativa aceita: header X-API-Key: rmk_...). Gere a key em /settings/api-keys · o token completo (formato rmk_<prefixo>_<segredo>, ~45 caracteres) aparece uma única vez — guarde como secret. O banco armazena apenas o hash SHA-256 do token; a revogação é instantânea (o próximo request com a key revogada cai em 401). Cada key pertence a um único workspace: toda chamada só enxerga e só altera dados daquele workspace. A key nunca pode aparecer no navegador — use-a apenas em ambiente servidor (backend, função serverless, n8n / Make / Zapier). A API não habilita CORS de propósito.
Gere e gerencie chaves em Configurações → Chaves de API (/settings/api-keys). A chave aparece uma única vez na criação — guarde num cofre de segredos.
Rate limit
100 requests/minuto sustentado por API key, com burst de até 200 (token bucket: o balde começa com 200 tokens e recarrega ~1,67 tokens/segundo). Ao estourar, a API responde 429 RATE_LIMITED com o header padrão Retry-After (segundos) e details.retryAfterSeconds no body do erro — clientes como n8n e axios honram o Retry-After automaticamente.
Paginação
Endpoints de listagem (GET /contacts, /accounts, /deals) usam paginação cursor-based (não offset): estável quando itens são criados/removidos entre páginas e com performance constante. Parâmetros: limit (1-100, default 20) e cursor (opaco · passe o nextCursor da resposta anterior; omita na primeira página). Ordenação fixa: createdAt DESC, id DESC. A resposta tem o envelope { "data": [...], "nextCursor": "..." | null, "hasMore": boolean } — quando hasMore é false, nextCursor vem null e você para de paginar. Cursor inválido ou expirado retorna 422 VALIDATION_ERROR. Já os endpoints de reporting/* usam paginação por página (page / per_page, max 200) com envelope próprio (pagination.has_more / next_page). Lookups (/pipelines, /users, etc.) não têm paginação.
Erros
| Código | Quando acontece |
|---|---|
| UNAUTHORIZED | 401 · Token ausente, com formato inválido, desconhecido ou revogado. |
| FORBIDDEN | 403 · Reservado no formato de erros; nenhum endpoint v1 o emite hoje. |
| NOT_FOUND | 404 · Recurso não existe ou não pertence ao seu workspace. |
| VALIDATION_ERROR | 422 · Body ou parâmetros com campos inválidos; details traz a lista de issues (path + message). |
| IDEMPOTENCY_CONFLICT | 422 · Mesma Idempotency-Key reusada com um body diferente dentro de 24h. |
| CONFLICT | 409 · Conflito de dados (ex.: email já usado por outro contato ativo). |
| RATE_LIMITED | 429 · Limite de requests excedido; header Retry-After e details.retryAfterSeconds indicam quando tentar de novo. |
| PROVIDER_ERROR | 502 · Pré-condição do workspace ausente (ex.: workspace sem pipeline ou sem tipos de atividade configurados). |
| INTERNAL_ERROR | 500 · Erro inesperado no servidor; a mensagem é genérica de propósito (detalhe fica só no log). |
Webhooks
Além de consultar a API, você pode receber eventos do CRM no seu sistema: cadastre uma URL em Configurações → Webhooks (/settings/webhooks) e escolha os eventos. Cada entrega vai assinada com HMAC-SHA256 do body no header X-Webhook-Signature: sha256=… — valide com o secret exibido no cadastro. Entregas com falha são retentadas até 6 vezes com backoff (1min → 24h); após 50 falhas consecutivas o webhook é desativado. Os eventos relevantes de cada recurso aparecem nas notas dos endpoints.
Recursos
Deals · os cards do kanban. Criação (inclusive com contato e empresa inline numa chamada só), leitura, movimentação de etapa, ganho/perda, vínculo de contatos, notas, atividades e o dossiê de IA do deal.
Pessoas (leads, decisores). CRUD completo com lookup por email e telefone, find-or-create e soft delete.
Accounts · as organizações dos seus contatos e deals. CRUD completo com busca por nome e soft delete.
Tarefas, ligações e reuniões · leitura, conclusão, reagendamento e exclusão de atividades individuais, mais o catálogo de tipos. A criação vive em `POST /deals/:id/activities` (grupo Negócios).
Catálogos do processo comercial: pipelines com seus estágios e os motivos de perda. Use pra descobrir `pipelineId`, `stageId` e `lostReasonId` antes de criar/fechar deals.
Identidade da integração (`/me`), membros do workspace e o conhecimento da empresa que alimenta as IAs.
Feed read-only pra dashboard/BI, em formato **denormalizado** (nomes de contato/empresa/etapa/dono já resolvidos, valor decimal, status minúsculo). Diferente do CRUD: usa paginação **por página** (`page` / `per_page`, max 200) e sync incremental via `updated_since`. Nos feeds, o `id` exposto é o ID externo original (ex.: Pipedrive) quando o registro foi migrado, senão o ID nativo do CRM; `crm_id` traz sempre o ID nativo.
Catálogos auxiliares do workspace: tags, custom fields e playbooks de call.