Documentação da API
Para outros sistemas (o seu CRM, uma planilha, o Zapier, o n8n, um BI) lerem as calls da sua equipe e cuidarem dos clientes do seu CRM, e para receber avisos (webhooks) quando uma call termina ou um cliente muda de etapa.
A API da sua conta é liberada por quem fornece o seu acesso. Se a tela Integrações → API disser que ela ainda não foi liberada, peça a liberação. Só o titular da conta cria chaves e webhooks.
Começo rápido
- No painel, abra Integrações → API e crie uma chave (só leitura ou leitura e escrita). Copie na hora: ela aparece uma vez só.
- Copie o endereço da API mostrado na mesma tela. Todas as rotas abaixo começam nele.
- Confira a chave:
curl https://<endereço da API>/eu \
-H "Authorization: Bearer ck_live_..."
Autenticação e limites
- Envie a chave em todo pedido:
Authorization: Bearer <chave>(ouX-Api-Key: <chave>). - A chave vale para a equipe inteira da conta: as calls e os clientes do titular e de todos os membros. Trate como uma senha e nunca coloque em código que roda no navegador.
- Revogar corta a chave na hora. A API também para (
403) se o acesso da conta deixar de estar ativo ou se a API da conta for desligada. - Limite: 120 pedidos por minuto por chave. Passou disso,
429: espere alguns segundos. Para acompanhar o que acontece, prefira os webhooks. - Pela API não se cria, tira nem suspende pessoa da equipe, e não se muda plano, créditos ou acesso: isso é com quem fornece o seu acesso.
Erros
{ "erro": { "codigo": "ETAPA_INVALIDA", "mensagem": "A etapa não existe no quadro da equipe (veja GET /conta/v1/crm/etapas)." } }
| Status | Código | Quando |
|---|---|---|
| 400 | ENTRADA_INVALIDA, CURSOR_INVALIDO | Campo faltando, tipo errado, valor fora da faixa ou campo desconhecido. |
| 401 | NAO_AUTENTICADO, CHAVE_INVALIDA | Sem chave, fora do formato, revogada ou inexistente. |
| 403 | ESCOPO_INSUFICIENTE | Chave só de leitura tentando escrever. |
| 403 | API_DESLIGADA, ACESSO_BLOQUEADO | A API da conta foi desligada, ou o acesso da conta não está ativo. |
| 404 | NAO_ENCONTRADO | O recurso não existe ou não é da sua equipe (as duas respondem igual, de propósito). |
| 404 | ROTA_INEXISTENTE | Método ou endereço errado. |
| 422 | ETAPA_INVALIDA, USUARIO_INVALIDO | O pedido aponta para algo que não serve (etapa de fora do quadro, pessoa de fora da equipe). |
| 429 | LIMITE_DE_REQUISICOES | Mais de 120 pedidos no minuto. |
| 500 | ERRO_INTERNO | Falha nossa. A resposta traz um id: mande para o suporte. |
Paginação e datas
As listas vêm do mais novo para o mais antigo: { "dados": [ ... ], "proximo_cursor": "..." }. Para a página seguinte, repita a chamada com ?cursor= igual ao proximo_cursor; quando ele vier null, acabou. ?limite= vai de 1 a 100 (padrão 50). Filtros de período: ?desde= e ?ate=, em ISO 8601 (ex.: 2026-10-01T00:00:00-03:00). Toda data sai em UTC; os campos terminados em _brasilia trazem o mesmo instante no horário de Brasília.
Conta e usuários
A conta, o plano, os créditos do mês e o uso do mês corrente, e a chave em uso:
{
"conta": { "id": "cm1abc", "nome": "Ana Souza", "email": "ana@empresa.com" },
"plano": "Scale",
"creditos_mes": 100,
"limite_membros": 3,
"membros_ativos": 2,
"acesso_ate": "2027-01-15T03:00:00.000Z",
"uso_do_mes": { "mes": "2026-10", "creditos": 12, "reunioes": 11 },
"chave": { "nome": "n8n", "escopo": "escrita" }
}
O titular e os membros da equipe, com id, nome, email, cargo, ativo e suspenso_em. Use o id nos filtros ?usuario= e no responsavel_id do CRM. Só leitura.
Calls
Cada call é uma reunião gravada pela extensão: o que a IA entendeu do cliente, a transcrição, as falas separadas (vendedor e cliente), o feedback e a nota do Ranking de atendimento.
A lista, em resumo (sem a transcrição). Filtros: usuario (id de /usuarios), status (Fechada, Perdida ou Em andamento), cliente_id (cliente do CRM), finalizadas=true, e desde, ate, limite, cursor.
A call completa: closer, modo, status, avaliacao, inicio, fim, duracao_segundos, nome_do_cliente, crm_cliente_id, notas, dados_do_lead, pontos_chave_do_vendedor, transcricao, falas ({ canais, falas: [ { quem, texto, inicio_ms, fim_ms } ] }), feedback, ranking e gravacao (o link do Google Drive). falas, ranking e gravacao vêm null quando a call não tem esses dados.
Atualiza o resultado. Todos opcionais; null limpa: status (Fechada, Perdida ou Em andamento; marcar Fechada dispara o webhook cliente.fechado), avaliacao (1 a 5) e notas (até 5.000 caracteres).
curl -X PATCH https://<endereço da API>/calls/cmupfirqp000ill089iykyn95 \
-H "Authorization: Bearer ck_live_..." \
-H "Content-Type: application/json" \
-d '{ "status": "Fechada", "notas": "Contrato assinado." }'
CRM
O quadro da equipe: as colunas (etapas) são as do titular, e cada cliente tem um responsável (null = sem responsável).
As colunas, com id, nome, posicao, tipo (entrada, negociacao, ganho, perdido...) e ganho (true na coluna de cliente fechado).
Filtros: responsavel_id (id de /usuarios, ou nenhum), etapa_id, q (busca em nome, e-mail, telefone e empresa), desde, ate, limite, cursor.
O cliente (nome, empresa, email, telefone, valor_centavos, observacoes, etapa, responsavel...), com as calls ligadas a ele e o historico_de_etapas.
Cria um cliente no quadro. Só nome é obrigatório. responsavel_id precisa ser uma pessoa ativa da equipe; etapa_id, uma coluna do quadro (sem ela, o cliente entra na coluna de entrada). Dispara o webhook lead.criado.
curl -X POST https://<endereço da API>/crm/clientes \
-H "Authorization: Bearer ck_live_..." \
-H "Content-Type: application/json" \
-d '{ "nome": "Marina Alves", "email": "marina@x.com", "telefone": "11988887777", "valor_centavos": 500000 }'
Edita e/ou troca a etapa: nome, empresa, email, telefone, valor_centavos, observacoes, etapa_id e responsavel_id. Trocar a etapa dispara lead.etapa_alterada e, se a coluna for de ganho, cliente.fechado.
Rever um aviso de webhook já emitido: { id, tipo, criado_em, payload, entregas: [ { destino, status, tentativas, http_status, enviado_em, erro } ] }.
Webhooks
Cadastre em Integrações → Webhooks a URL (https) que vai receber os avisos e escolha os eventos. Na troca de etapa dá para escolher só algumas etapas de destino. Cada aviso é um POST com este corpo:
{
"id": "cev_8f1c...",
"tipo": "lead.etapa_alterada",
"criado_em": "2026-10-30T15:00:00.000Z",
"criado_em_brasilia": "2026-10-30T12:00:00.000-03:00",
"ambiente": "producao",
"conta_id": "cm1abc",
"versao": 1,
"dados": { "crm": "antigo", "cliente": { ... }, "mudanca_de_etapa": { "de": { ... }, "para": { ... } }, "closer": { ... }, "ultima_call": { ... } }
}
E com estes cabeçalhos:
X-Webhook-Evento | O tipo do evento. |
X-Webhook-Evento-Id | O id do evento (o mesmo do corpo). |
X-Webhook-Tentativa | 1 na primeira entrega, 2 na segunda... |
X-Webhook-Assinatura | t=<segundos unix>,v1=<HMAC-SHA256 em hexadecimal> |
Conferir a assinatura
Calcule o HMAC-SHA256 do texto <t>.<corpo exatamente como chegou> com o segredo do webhook (o botão Segredo na tela) e compare com o v1. Recuse se não bater ou se o t tiver mais de 5 minutos. Em Node.js:
import crypto from 'node:crypto';
function avisoVerdadeiro(segredo, corpoCru, cabecalho) {
const partes = Object.fromEntries(cabecalho.split(',').map((p) => p.trim().split('=')));
const t = Number(partes.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const esperado = crypto.createHmac('sha256', segredo).update(t + '.' + corpoCru).digest('hex');
const a = Buffer.from(esperado, 'hex');
const b = Buffer.from(partes.v1 || '', 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Respostas, novas tentativas e repetidos
- Responda com qualquer status 2xx em até 10 segundos. Redirecionamento não é seguido.
- Sem 2xx, tentamos de novo depois de 1 min, 5 min, 15 min, 1 h e 6 h (6 tentativas no total). No Histórico do webhook dá para ver cada entrega e reenviar.
- Com 20 falhas seguidas o webhook desliga sozinho. Corrija, use Enviar teste e religue.
- O mesmo evento pode chegar mais de uma vez. Guarde o
ide ignore o que já tratou. A ordem de chegada não é garantida. - Os avisos de troca de etapa chegam em até uns 30 segundos depois da troca.
Eventos
| Tipo | Quando | dados |
|---|---|---|
call.finalizada | Uma call terminou. Sai 2 minutos depois do fim, para o cliente do CRM já estar ligado. | { closer, call, cliente } |
call.analisada | O feedback da IA ficou pronto. | { closer, call, cliente } (a call completa, com transcrição e feedback) |
cliente.fechado | O cliente foi para a coluna de ganho, ou a call foi marcada Fechada. | O mesmo da troca de etapa, ou o da call (com origem: "status_da_call"). |
lead.etapa_alterada | Um cliente mudou de etapa no CRM (pelo painel, pelo pós-call ou pela API). | { crm, cliente, mudanca_de_etapa: { de, para }, closer, ultima_call } |
lead.criado | Um cliente novo entrou no CRM. | O mesmo da troca de etapa, com de: null. |
webhook.teste | O botão Enviar teste. Sai na hora e não volta para a fila. | { mensagem } |