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, no Make ou no Zapier.

Com ela você cadastra leads do site direto no funil, sincroniza contatos e empresas, cria e conclui atividades, registra notas, consulta relatórios e recebe avisos automáticos (webhooks) quando algo muda.

O que dá pra fazer:

• Oportunidades: listar, criar, editar, excluir (vai pra lixeira), vincular contatos, registrar notas e criar atividades.
• Contatos e empresas: listar, criar, editar e excluir.
• Atividades: listar, editar, concluir e excluir. Pela API, atividade nova nasce dentro de uma oportunidade (POST /api/v1/deals/<id>/activities). Pra agendar pra uma pessoa sem oportunidade, use a conexão com ChatGPT ou Claude (veja "Conectar o ChatGPT ou o Claude ao CRM").
• Agenda: consultar horários livres e marcar reunião num tipo de evento da agenda própria (veja "Marcar reunião pela API").
• Só leitura: funis (já vêm com as etapas), tipos de atividade, motivos de perda, usuários, etiquetas, campos personalizados e relatórios de oportunidades, atividades e etapas.

Funis, campos personalizados, usuários e webhooks não são criados pela API; isso fica nas telas do CRM.

Não existe app oficial do Zapier, do Make ou do n8n. Nessas ferramentas use o bloco de requisição HTTP com a sua chave. Pra testar se a chave está certa, chame GET /api/v1/me.

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 Configurações → Desenvolvedores → Documentação da API (/docs/api).

Como criar uma chave de API

1. Vá em Configurações → Desenvolvedores → Chaves de API (/settings/api-keys). Esse grupo não aparece no celular; use o computador.
2. Clique em Nova chave, dê um nome que identifique o uso (ex.: "n8n produção") e clique em Criar chave.
3. Copie o token completo (formato rmk_...) em Copiar token e feche em Já copiei, fechar.

Qualquer pessoa do time vê a lista de chaves (nome, início do token e último uso). Só dono ou admin cria ou revoga.

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

As permissões que aparecem em "Permissões de IA (MCP) · opcional" valem só pra conexão de IA. Na API comum, toda chave lê e escreve.

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

• 200 requisições por minuto por chave. A conexão de IA (MCP) com a mesma chave conta no mesmo limite.
• Ao estourar, a API responde 429 com o header Retry-After dizendo quantos segundos esperar. Ferramentas como o n8n respeitam isso automaticamente.
• Listagens de oportunidades, contatos, empresas e atividades são paginadas por cursor: use limit (padrão 20, até 100) e repasse o nextCursor da resposta anterior, com os mesmos filtros, até hasMore vir false. Os relatórios usam page e per_page (até 200).

Não duplicar em retentativa

Mande o header Idempotency-Key (8 a 200 caracteres) nas criações e edições. Se a mesma chamada for repetida em até 24 horas com a mesma chave e o mesmo corpo, a API devolve a resposta da primeira vez em vez de gravar de novo. Use uma chave nova pra cada operação; mesma chave com corpo diferente dá 422 IDEMPOTENCY_CONFLICT.

Pra formulário de site, POST /api/v1/contacts e POST /api/v1/deals aceitam o header X-On-Conflict: return-existing: se o contato já existe, a API devolve o existente em vez de duplicar.

Listar e concluir atividades

Use GET /api/v1/activities?done=false para listar as atividades pendentes do workspace, inclusive as que não estão vinculadas a uma oportunidade. Aceita dealId, assigneeId, typeId, dueSince (inclusivo), dueUntil (exclusivo) e limit. Datas precisam de fuso; filtros de prazo deixam de fora atividades sem prazo.

Para concluir, envie PATCH /api/v1/activities/<id> com o corpo {"done":true}. A resposta vem com doneAt preenchido e dispara o evento activity.completed. Para reabrir, use {"done":false}. Ao criar ou editar atividade, mande dueAt em UTC, terminando em Z (ex.: 2026-10-20T13:00:00Z). O campo opcional location (texto, até 300 caracteres) guarda o endereço da atividade, pra visita presencial; na edição, null apaga. Ele volta em todas as respostas e webhooks de atividade.

Marcar reunião pela API

Pra um sistema seu (por exemplo um agente de voz que liga pro lead) marcar reunião na agenda própria do CRM, sem passar pela página de agendamento:

1. GET /api/v1/agenda/<slug>/slots?from=2026-10-20&to=2026-10-24&tz=America/Sao_Paulo devolve os horários livres por dia. O slug é o mesmo do link público /agendar/<slug> e precisa ser de um tipo de evento do seu workspace.
2. POST /api/v1/agenda/<slug>/bookings com start (um dos horários da lista), timezone, name, email, phone e utm marca a reunião. Responde 201 com a reserva.

A reserva segue o mesmo caminho da página: rodízio entre os organizadores, convite do Google e e-mail de confirmação pro convidado, aviso ao organizador e entrada no funil. O utm aparece no negócio como origem.

Se o horário foi tomado no meio do caminho, a resposta é 409: busque os horários de novo e ofereça outro. Cada chave marca até 60 reuniões por hora, e cada pessoa (e-mail ou telefone) até 3 em 24 horas. Mande Idempotency-Key pra retentativa não marcar duas vezes.

Como receber webhooks

Webhooks avisam o seu sistema quando algo acontece no CRM, seja pela tela, pela API ou pela IA.

1. Vá em Configurações → Desenvolvedores → Webhooks (/settings/webhooks). Só dono ou admin cria e edita.
2. Clique em Novo webhook, preencha Nome e URL (POST), escolha os eventos e clique em Criar webhook.
3. Pra pegar o secret, abra Editar no webhook e clique em Revelar secret.
4. Use Testar pra mandar uma entrega de exemplo.

Eventos disponíveis:

• Oportunidade: deal.created, deal.updated, deal.stage_changed, deal.won, deal.lost, deal.deleted.
• Contato: contact.created, contact.updated, contact.deleted.
• Empresa: account.created, account.updated, account.deleted.
• Nota: note.created.
• Atividade: activity.created, activity.updated, activity.completed, activity.deleted.

Cada entrega chega como { id, event, createdAt, data }. Valide com o header X-Webhook-Signature: sha256=<hex>, que é o HMAC-SHA256 do corpo cru usando o secret. A URL precisa ser pública: endereço local ou de rede interna é recusado.

Se a entrega falhar (erro, redirecionamento ou mais de 10 segundos sem resposta), o CRM tenta de novo 5 vezes: depois de 1 minuto, 5 minutos, 30 minutos, 2 horas e 8 horas. Os reenvios rodam a cada 5 minutos, então o horário real pode atrasar um pouco. Depois de 50 tentativas seguidas com falha o webhook é desativado; corrija a URL, abra Editar, marque Ativo (recebe eventos) e salve. O que ficou pendente enquanto estava desativado não é reenviado.

Erros comuns

• 401 UNAUTHORIZED: token ausente, com formato errado ou revogado. Confira o header Authorization e se a chave ainda existe.
• 403 FORBIDDEN: a chave tentou um relatório que é só da operação interna.
• 404 NOT_FOUND: o recurso não existe ou pertence a outro workspace.
• 409 CONFLICT: já existe contato com esse e-mail, ou o contato tem mais de uma oportunidade aberta e a API não sabe qual usar.
• 422 VALIDATION_ERROR: algum campo é inválido; o campo details lista o que corrigir.
• 422 IDEMPOTENCY_CONFLICT: a mesma Idempotency-Key foi usada com outro corpo.
• 429 RATE_LIMITED: limite estourado; espere o tempo do header Retry-After.
• 502 PROVIDER_ERROR: falta configuração no workspace, por exemplo nenhum funil ou nenhum tipo de atividade.

O formato do erro é sempre {"error": {"code", "message", "details"}}.

O que a API não faz

Ela não dispara mensagem em massa pros seus contatos. Nenhum endpoint envia WhatsApp, e o único e-mail que sai pela API é a confirmação da reunião pra quem foi agendado (a mesma que a página de agendamento manda).

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.