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

  1. No painel, abra Integrações → API e crie uma chave (só leitura ou leitura e escrita). Copie na hora: ela aparece uma vez só.
  2. Copie o endereço da API mostrado na mesma tela. Todas as rotas abaixo começam nele.
  3. Confira a chave:
curl https://<endereço da API>/eu \
  -H "Authorization: Bearer ck_live_..."

Autenticação e limites

Erros

{ "erro": { "codigo": "ETAPA_INVALIDA", "mensagem": "A etapa não existe no quadro da equipe (veja GET /conta/v1/crm/etapas)." } }
StatusCódigoQuando
400ENTRADA_INVALIDA, CURSOR_INVALIDOCampo faltando, tipo errado, valor fora da faixa ou campo desconhecido.
401NAO_AUTENTICADO, CHAVE_INVALIDASem chave, fora do formato, revogada ou inexistente.
403ESCOPO_INSUFICIENTEChave só de leitura tentando escrever.
403API_DESLIGADA, ACESSO_BLOQUEADOA API da conta foi desligada, ou o acesso da conta não está ativo.
404NAO_ENCONTRADOO recurso não existe ou não é da sua equipe (as duas respondem igual, de propósito).
404ROTA_INEXISTENTEMétodo ou endereço errado.
422ETAPA_INVALIDA, USUARIO_INVALIDOO pedido aponta para algo que não serve (etapa de fora do quadro, pessoa de fora da equipe).
429LIMITE_DE_REQUISICOESMais de 120 pedidos no minuto.
500ERRO_INTERNOFalha 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

GET/euleitura

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" }
}
GET/usuariosleitura

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.

GET/callsleitura

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.

GET/calls/{id}leitura

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.

PATCH/calls/{id}escrita

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).

GET/crm/etapasleitura

As colunas, com id, nome, posicao, tipo (entrada, negociacao, ganho, perdido...) e ganho (true na coluna de cliente fechado).

GET/crm/clientesleitura

Filtros: responsavel_id (id de /usuarios, ou nenhum), etapa_id, q (busca em nome, e-mail, telefone e empresa), desde, ate, limite, cursor.

GET/crm/clientes/{id}leitura

O cliente (nome, empresa, email, telefone, valor_centavos, observacoes, etapa, responsavel...), com as calls ligadas a ele e o historico_de_etapas.

POST/crm/clientesescrita

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 }'
PATCH/crm/clientes/{id}escrita

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.

GET/eventos/{id}leitura

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-EventoO tipo do evento.
X-Webhook-Evento-IdO id do evento (o mesmo do corpo).
X-Webhook-Tentativa1 na primeira entrega, 2 na segunda...
X-Webhook-Assinaturat=<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

Eventos

TipoQuandodados
call.finalizadaUma call terminou. Sai 2 minutos depois do fim, para o cliente do CRM já estar ligado.{ closer, call, cliente }
call.analisadaO feedback da IA ficou pronto.{ closer, call, cliente } (a call completa, com transcrição e feedback)
cliente.fechadoO 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_alteradaUm 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.criadoUm cliente novo entrou no CRM.O mesmo da troca de etapa, com de: null.
webhook.testeO botão Enviar teste. Sai na hora e não volta para a fila.{ mensagem }