API e webhooks

Com API e webhooks, os seus próprios sistemas (ERP, data warehouse, backend do site, ferramentas de automação) trabalham com o seu workspace do NextCRM:

• a API REST lê e altera leads, contatos, tarefas e notas, e lê funis, envios de formulários, campanhas e membros da equipe;
• os webhooks avisam o seu servidor assim que algo acontece, por exemplo um novo lead ou uma mudança de etapa.

Observação: Apenas Admins do Workspace podem abrir Configurações > API e webhooks. O acesso à API está incluído nos planos Business, Agency e Enterprise. Nos outros planos, chaves e endpoints existentes continuam visíveis, mas não é possível criar novos e as chamadas à API são recusadas.

Onde obter cada valor

Tudo vem do próprio NextCRM; não é preciso conta em nenhum serviço de terceiros.

Valor	Onde obter
Chave de API	Configurações > API e webhooks > Criar chave de API. A chave completa só é exibida uma vez; copie-a para a sua integração (por exemplo n8n, Zapier, Make ou o seu próprio código) como Bearer token.
Segredo de assinatura	Exibido uma vez quando você adiciona um endpoint de webhook, e de novo depois de Trocar segredo. Guarde-o no servidor que recebe os webhooks.
URL do endpoint	Vem do seu próprio sistema ou ferramenta de automação, por exemplo a URL de produção de um nó Webhook do n8n. Ela deve usar https.

Ordem de configuração: crie uma chave de API com as permissões necessárias > faça uma primeira chamada > adicione um endpoint de webhook com os seus eventos > verifique a assinatura no seu servidor > envie um evento de teste.

Criar uma chave de API

1. Clique no seu cartão de perfil, na parte de baixo da barra lateral, escolha Configurações, abra o cartão API e webhooks (abrir API e webhooks) e fique na aba Chaves de API.
2. Clique em Criar chave de API.
3. Informe um Nome que mostre onde a chave é usada, por exemplo "Sincronização ERP".
4. Em Permissões, escolha Ler e/ou Escrever por área. Escolha apenas o que a integração realmente precisa.
5. Se quiser, defina uma validade em Expira (30, 90 ou 365 dias, ou uma data).
6. Clique em Criar chave e copie a chave na hora com Copiar.

Atenção: A chave só é exibida uma vez. O NextCRM guarda apenas uma impressão digital (hash) dela, então ninguém - nem o suporte - consegue mostrá-la de novo. Se ela se perder, revogue-a e crie uma nova.

A lista mostra cada chave com o seu prefixo (por exemplo ncrm_live_1a2b3c4d), as permissões, quem a criou, quando foi usada pela última vez e quando expira. Revogar bloqueia a chave imediatamente.

O que uma chave pode fazer

Uma chave age pelo seu workspace com os direitos de um Admin do Workspace, limitada às permissões escolhidas:

Permissão	Permite
Leads (ler / escrever)	Listar e ler leads; criar, alterar, mover para uma etapa, atribuir, mover para a Lixeira e restaurar
Contatos (ler / escrever)	Listar, ler, criar, alterar e excluir contatos
Tarefas (ler / escrever)	Listar e ler tarefas; criar, alterar, concluir e arquivar
Funis e etapas (ler)	Ler funis com as suas etapas
Envios de formulários (ler)	Ler formulários e os seus envios
Campanhas (ler)	Ler campanhas e os seus resultados
Notas e atividades (ler / escrever)	Ler as notas e o histórico de um lead; adicionar notas e registrar ligações
Membros da equipe (ler)	Ler nomes, e-mails e funções dos membros (para atribuir leads e tarefas)
Webhooks (ler / escrever)	Ler, cadastrar e excluir endpoints de webhook

Valem as mesmas regras do app: limites do plano (um novo lead acima do limite de leads ativos vai para a Caixa de entrada de leads), a Lixeira (leads na Lixeira precisam ser restaurados antes de serem alterados; excluir pela API sempre move para a Lixeira) e os dados nunca passam para outro workspace. O que só pessoas podem fazer - gerenciar equipe, funções, cobrança ou chaves de API e excluir definitivamente - não é possível com uma chave. A chave também deixa de funcionar quando quem a criou não é mais Admin do Workspace.

Cada alteração feita com uma chave aparece no histórico do lead como API key <nome>.

Fazer a primeira chamada

Envie a chave no cabeçalho Authorization. A URL base é https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Criar um lead:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

A referência completa com todos os endpoints, campos e um exemplo em curl está na aba Documentação da API, publicamente em https://…/api/v1/docs e como arquivo OpenAPI 3.1 em https://…/api/v1/openapi.json.

Regras para toda integração

• Respostas têm a forma { "data": ..., "meta": { ... } }; erros, { "error": { "code", "message", "details" } }, com a lista de campos em erros de validação. Datas em ISO 8601, UTC.
• Paginação: listas retornam meta.next_cursor; envie-o como cursor para obter a próxima página (limit até 100).
• Idempotência: envie um cabeçalho Idempotency-Key em requisições POST. Uma repetição com a mesma chave devolve o primeiro resultado em vez de criar um duplicado (por 24 horas).
• Limites de requisições: 120 por minuto por chave e 600 por workspace. Acima disso a API responde 429 com o cabeçalho Retry-After - aguarde esse número de segundos.
• Manutenção: durante uma atualização do NextCRM a API responde 503 MAINTENANCE com Retry-After. Os webhooks ficam retidos e são entregues depois.
• Somente no servidor: chame a API a partir do seu servidor. Navegadores não conseguem chamá-la (sem CORS), e uma chave de API nunca deve ficar em um site ou app.

Webhooks

1. Abra a aba Webhooks e clique em Adicionar endpoint.
2. Informe a URL do endpoint do seu servidor. Ela deve começar com https:// e estar acessível pela internet; endereços internos, privados e de metadados de nuvem são recusados.
3. Escolha os Eventos desejados e clique em Salvar endpoint.
4. Copie o segredo de assinatura (exibido uma vez) e guarde-o no seu servidor.
5. Clique em Enviar evento de teste para verificar se o seu servidor responde.

Eventos disponíveis: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined e automation.webhook.

Os eventos de orçamento trazem os valores como inteiros na menor unidade da moeda (por exemplo, centavos): subtotal_minor é a soma dos itens após os descontos por item, discount_minor o desconto sobre o orçamento inteiro, tax_minor o imposto e total_minor o valor a pagar. O total_minor de cada item é o seu valor após o desconto do item, antes do desconto do orçamento e do imposto.

Leads criados por uma importação de arquivo enviam um lead.created por lead importado depois que a importação termina, com "context": { "source": "import", "import_batch_id": "..." } ao lado de data.

Cada entrega é um POST com o evento em JSON (id, type, created_at, actor, data) e estes cabeçalhos: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp e X-NextCRM-Signature.

Verificar a assinatura

X-NextCRM-Signature tem o formato t=1760860800,v1=5f2b.... Calcule o HMAC-SHA256 de <t>.<corpo bruto da requisição> com o seu segredo de assinatura e compare com v1. Rejeite requisições cujo timestamp tenha mais de 5 minutos.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Novas tentativas, histórico de entregas e troca do segredo

• Responda com qualquer status 2xx em até 10 segundos. Caso contrário, o NextCRM tenta de novo com pausas crescentes (1, 2, 4, ... minutos), até 8 tentativas.
• O Histórico de entregas mostra cada entrega com status, tentativas e código de resposta. Enviar novamente coloca a entrega na fila mais uma vez.
• Depois de muitas falhas seguidas, o endpoint é desativado automaticamente e todos os Admins do Workspace recebem uma notificação. Corrija o endpoint e clique em Ativar.
• Trocar segredo cria um novo segredo de assinatura. O antigo continua assinando por 24 horas para você trocar sem perder eventos.

A Lora e a API

A Lora pode explicar a API, abrir esta página e listar os seus endpoints de webhook. Ela nunca cria, mostra ou revoga chaves de API e nunca vê um segredo de assinatura - isso você faz nesta página.

Solução de problemas

Resposta	Significado
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	A chave está errada, revogada ou expirada. Crie uma nova.
403 INSUFFICIENT_SCOPE	A chave não tem a permissão para esta chamada. Crie uma chave com a permissão necessária.
403 API_KEY_OWNER_NOT_ADMIN	Quem criou a chave não é mais Admin do Workspace. Um admin atual precisa criar uma nova chave.
402 FEATURE_NOT_IN_PLAN	O plano não inclui acesso à API.
409 LEAD_IN_TRASH	Restaure o lead primeiro (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Veja o campo e o motivo em error.details.
429 RATE_LIMITED	Aguarde os segundos de Retry-After e continue.