API Pública: integre seu agente de I.A ao North (agendamento e webhook de status) - Ajuda

Se a sua clínica já tem (ou está montando) um agente de inteligência artificial próprio — um bot, um chatbot, uma automação externa feita em n8n, Make, Python ou qualquer outra ferramenta — para atender e agendar pelo WhatsApp, o North tem uma API Pública que permite plugar esse agente na agenda do sistema.

Este guia explica o assunto inteiro: o que a API faz, o que ela não faz, como conectar o número da I.A ao North para o atendimento continuar na inbox, e como funciona o webhook que devolve eventos para o seu sistema.

Resumo em uma frase: a I.A é sua, o envio de mensagens é seu; o North recebe a consulta de horários e o agendamento, guarda o histórico do lead e devolve eventos por webhook.

Pra quem é este guia

Clínicas do plano CRM que:

Têm (ou querem ter) um agente de I.A próprio — rodando por fora do North — para qualificar e agendar pacientes pelo WhatsApp.
Já usam alguma automação externa (n8n, Make, script próprio) e querem que os agendamentos entrem direto na agenda do North, sem digitação manual.
Precisam saber, do lado do próprio sistema externo, quando um paciente agendou, confirmou, chegou, foi atendido ou faltou.

Se você só quer conectar o número de WhatsApp da clínica (sem integração de I.A própria), veja Conexões do WhatsApp — este guia é especificamente sobre a API e o webhook.

O que a API faz

A API Pública do North (não confundir com a API Oficial do WhatsApp/Meta, que é outro assunto) permite que o sistema externo:

Consulte profissionais e serviços disponíveis para agendamento.
Consulte horários disponíveis (GET /scheduling/availability) — cruzando profissional, sala, bloqueios e agendamentos existentes, do mesmo jeito que a agenda nativa calcula.
Cadastre um lead antes de agendar (POST /integration/leads) — envie nome, telefone com DDI e DDD e, opcionalmente, cpf, data_nascimento e origem. A resposta traz data.id e created: 201 quando criado, 200 quando o telefone já tem cadastro ativo na clínica. O cadastro existente é reutilizado sem alterar seus dados.
Crie um agendamento (POST /scheduling/appointments) — envie lead_id retornado no cadastro ou os dados no objeto lead (exatamente uma alternativa). Com lead, se o telefone informado já é um lead conhecido, o North reaproveita o cadastro; se não, cria um lead novo automaticamente, já vinculado ao agendamento.
Consulte o status de um agendamento (GET /scheduling/appointments/:id ou a listagem por período) — os valores possíveis são agendado, confirmado, chegou, atendido, faltou e cancelado.
Cancele um agendamento criado pela integração.
Consulte dados de leads (histórico, agendamentos, vendas) — útil para agências e integrações de relatório, não só para agentes de I.A.

A documentação técnica completa (todos os endpoints, parâmetros e formatos de resposta) fica em northcrm.com.br/developers/api. Este artigo explica o conceito e o fluxo; a doc técnica é a referência para quem vai programar a integração.

O que a API NÃO faz

Este é o ponto que mais gera dúvida: a API não envia mensagens pela estrutura do North. Não existe um endpoint “mandar mensagem” na API Pública.

O disparo das mensagens — a conversa em si, o texto que o paciente recebe da I.A — é sempre feito do lado do cliente: é a sua I.A, usando o número de WhatsApp dela (via Cloud API da Meta, Evolution API, WAHA ou qualquer outro provedor que você já usa), quem conversa com o paciente. O North não é o canal de envio dessa conversa.

Em resumo:

	Quem faz
Conversar com o paciente, enviar mensagens da I.A	Sua integração, pelo número dela
Consultar horários e criar o agendamento	API do North
Guardar o histórico do lead, o funil, a venda	North
Continuar o atendimento com um humano depois que a I.A agendou	North (inbox), se você conectar o número — veja abaixo

Conectar o número no North (o pulo do gato)

A API resolve a parte de agendar. Mas a maioria das clínicas também quer que a conversa iniciada pela I.A não se perca — que a recepção consiga ver o que já foi falado e continuar o atendimento humano a partir dali (confirmar detalhes, tirar dúvidas, cuidar do comparecimento).

Para isso, conecte o mesmo número que a I.A usa como uma conexão de WhatsApp do North (veja Conexões do WhatsApp). A partir do momento em que o número está conectado:

Toda conversa que passa por aquele número — incluindo a que a I.A começou — aparece no Inbox do CRM.
A atendente/recepção consegue abrir a conversa, ver o histórico completo (o que a I.A já perguntou e respondeu) e continuar dali, sem o paciente precisar repetir nada.
O lead tem a evolução completa registrada: do primeiro contato feito pela I.A até o comparecimento na clínica, tudo no mesmo card.

Conectar o número é opcional, mas é o que fecha o ciclo: sem conectar, o North só enxerga o que a API mandou (o agendamento em si); com o número conectado, o North também enxerga a conversa.

Autenticação: API Keys

Toda chamada à API precisa de uma API Key, gerada em Configurações → Integrações → API Keys (rota /app/configuracoes-api-keys).

Cada key tem um ou mais escopos — o que ela pode fazer:

scheduling:read — consultar profissionais, serviços, disponibilidade e agendamentos.
scheduling:write — criar e cancelar agendamentos.
leads:write — cadastrar leads, independente da agenda.
leads:read — consultar dados de leads (histórico, agendamentos, vendas).

Para um agente de I.A que agenda, use o preset “Agendamento I.A” (scheduling:read + scheduling:write) na criação da key para o fluxo com lead embutido. Para cadastrar separadamente antes de agendar, a chave também precisa de leads:write (preset Acesso Completo). A chave completa só é exibida uma vez, no momento da criação — guarde em local seguro (ela não fica visível de novo depois).

A tela de API Keys (e a de Webhooks, a seguir) só aparece para clínicas com o módulo de API Pública habilitado. Se o menu Integrações não aparece em Configurações, fale com o suporte para contratar o módulo.

Webhook: o caminho de volta

Enquanto a API é o caminho da sua I.A para o North (consultar horário, criar agendamento), o webhook é o caminho contrário: o North avisa a sua integração quando algo acontece, em vez de você ficar consultando a API de tempos em tempos.

Configure em Configurações → Integrações → Webhooks (rota /app/configuracoes-webhooks):

Informe a URL do seu sistema que vai receber os eventos (precisa ser HTTPS).
Escolha os eventos que quer receber.
O North gera um segredo (whsec_...), mostrado uma única vez — use-o para validar a assinatura dos eventos recebidos.

Se você (ou o cliente) leu uma versão antiga da documentação e não encontrou nada sobre webhook: ele existe e está disponível hoje, com CRUD completo pelo painel — use o link acima.

Eventos disponíveis hoje

Evento	O que dispara
`lead.created`	Um lead novo foi criado (por qualquer canal — API, WhatsApp, Meta etc.)
`appointment.created`	Um agendamento foi criado via API
`appointment.cancelled`	Um agendamento foi cancelado via API

Cada evento chega via POST no seu endpoint, com:

X-Webhook-Event — nome do evento.
X-Webhook-Delivery — id único da entrega (use como chave de idempotência — o mesmo evento pode chegar mais de uma vez, entregas são at-least-once).
X-Webhook-Signature: sha256=<hmac> — HMAC-SHA256 do corpo, calculado com o segredo do webhook. Valide a assinatura antes de confiar no payload.

Responda 2xx para confirmar o recebimento. Se o seu endpoint falhar, o North retenta automaticamente (com espera crescente); depois de falhas consecutivas demais, o webhook é desativado automaticamente e precisa ser reativado manualmente na tela.

E o status do paciente (compareceu / faltou)?

Hoje o webhook cobre criação e cancelamento de agendamento — ele não empurra automaticamente, por si só, cada mudança de status depois disso (confirmado, chegou, atendido, faltou). Um evento de mudança de status (appointment.status_changed) já está mapeado e é o próximo da fila para entrar em produção.

Enquanto esse evento não chega, a forma de acompanhar o status atualizado de um agendamento (agendado, confirmado, chegou, atendido/compareceu, faltou, cancelado) é consultar pela API: GET /scheduling/appointments/:id (um agendamento específico) ou GET /scheduling/appointments filtrando por período e, se quiser, por status — ambos com o escopo scheduling:read que sua key de agendamento já tem.

Se o seu caso de uso depende especificamente de saber em tempo real quando o paciente compareceu ou faltou, fale com o suporte — isso ajuda a priorizar a ativação desse evento.

Fluxo completo (passo a passo)

Habilite o módulo de API Pública (se ainda não tiver) — fale com o suporte.
Gere uma API Key com escopos leads:write, scheduling:read e scheduling:write (disponíveis no preset “Acesso Completo”). Para somente cadastrar/consultar leads, use “Cadastro de leads”, sem agenda. Chaves antigas precisam de edição explícita para receber leads:write.
Sua I.A consulta horários disponíveis (GET /scheduling/availability) para o serviço desejado.
Sua I.A cadastra o lead em POST /integration/leads, enviando nome e telefone, e usa o data.id retornado como lead_id no POST /scheduling/appointments. O cadastro pode ser feito antes de consultar horários. Também é possível enviar lead com nome e telefone direto no agendamento, mantendo o fluxo em uma chamada. Não envie lead e lead_id juntos. Um ID excluído ou de outra clínica retorna 404.
Envio de mensagens continua sendo sempre do lado do cliente — a I.A conversa com o paciente pelo número dela, usando o provedor de WhatsApp dela.
(Recomendado) Conecte esse mesmo número como conexão de WhatsApp do North — a conversa cai na inbox e a recepção assume o atendimento a partir dali, com histórico completo.
Configure o webhook para receber appointment.created e appointment.cancelled em tempo real no seu sistema, e consulte GET /scheduling/appointments/:id quando precisar do status mais recente (confirmado, chegou, atendido, faltou).

Permissões

Ver/gerenciar API Keys e Webhooks: permissão config.api (visualizar) e config.api.gerenciar (criar, revogar, ativar/desativar) — normalmente restrita a administradores.
Módulo de API Pública: precisa estar habilitado para a clínica (feature api_publica). Sem o módulo, as telas de Integrações não aparecem em Configurações.

Perguntas rápidas

Consigo enviar mensagens de forma externa pelo North? Não pela API do North — o envio (a conversa da I.A com o paciente) é sempre feito pelo seu lado, com o número e o provedor de WhatsApp da sua integração. A API do North serve para consultar horários e criar/cancelar agendamentos.

A documentação não tem webhook — vocês não têm essa funcionalidade? Tem, sim: Configurações → Integrações → Webhooks (/app/configuracoes-webhooks). O CRUD completo (criar, listar, ativar/desativar, ver entregas, excluir) já está disponível pelo painel.

Minha ideia é integrar um agente de I.A por fora — como começo? Habilite o módulo de API Pública, gere uma API Key com o preset “Agendamento I.A”, e siga o fluxo deste guia: consultar disponibilidade → criar agendamento → (opcional, mas recomendado) conectar o número na inbox → configurar o webhook.

O webhook me avisa quando o paciente compareceu ou faltou? Hoje ele avisa quando um agendamento é criado ou cancelado. Para saber o status atual (confirmado, chegou, atendido, faltou), consulte o agendamento pela API (GET /scheduling/appointments/:id) — um evento de webhook dedicado a mudanças de status está no roadmap.

Preciso conectar o número da I.A no North? Não é obrigatório para a API funcionar (consultar horário e agendar funcionam sem isso), mas é altamente recomendado: sem conectar, o North não vê a conversa — só o agendamento resultante. Conectando, a recepção consegue assumir o atendimento onde a I.A parou.

Onde acho os detalhes técnicos de cada endpoint (campos, formatos, exemplos)? northcrm.com.br/developers/api.

Dúvidas sobre como habilitar o módulo, gerar a primeira API Key ou planejar a integração da sua I.A? Chame o suporte pelo WhatsApp — a gente ajuda a desenhar o fluxo junto com você.