Pular para o conteúdo
API v1 em produçãoOpenAPI 3.0

Integre sua operação ao North Clinic CRM

Cadastre e consulte leads, encontre horários e crie agendamentos com uma API previsível, autenticada por chave e isolada por clínica.

Visão geral

Dois grupos de uso, limites independentes

A mesma chave pode combinar escopos de integração e agenda. Cada grupo tem seu próprio contador, evitando que a sincronização de leads bloqueie um agendamento.

01

Integração

Cadastro geral de leads e leitura paginada da timeline para BI, mídia e automações.

listas 300/min · detalhe 60/min
02

Agendamento

Profissionais, serviços, disponibilidade e criação de agendamentos.

scheduling:* · 60 req/min

Início rápido

Sua primeira requisição

Terminal
curl --request GET \
  --url 'https://api.northcliniccrm.com.br/api/v1/integration/leads?limit=20' \
  --header 'X-API-Key: ncrm_live_sua_chave'
Crie a chave em Configurações → API Keys. Ela é exibida uma única vez; guarde-a em um cofre de segredos e nunca em código do navegador.

Do cadastro ao agendamento

Cadastre o lead e agende pelo ID

Com o escopo leads:write, envie nome etelefone com DDI e DDD para POST /integration/leads. A resposta retorna data.id: status 201 para um novo cadastro ou 200 para um lead ativo já existente pelo telefone na clínica.

Para agendar, use também o escopo scheduling:write e envie esse ID no campo lead_id dePOST /scheduling/appointments, junto ao serviço, profissional, sala, data e horários consultados. O fluxo em uma chamada continua disponível: envie o objeto lead com nome e telefone no agendamento. Use exatamente uma alternativa: lead_id ou lead.

POST /integration/leads
curl --request POST \
  --url 'https://api.northcliniccrm.com.br/api/v1/integration/leads' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ncrm_live_sua_chave' \
  --data '{
    "nome": "Maria Santos",
    "telefone": "5511999998888",
    "origem": "Google Ads",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "avaliacao_outubro",
    "utm_content": "video_1",
    "utm_term": "emagrecimento",
    "referencia_externa": "integrador:registro-123"
  }'

Mapeamentos prontos

Conecte n8n, Make, Zapier ou RD Station

Cada integrador transforma seus campos para o contrato acima. Guarde a API Key no cofre de credenciais da plataforma, normalize o telefone com DDI e DDD e preserve umareferencia_externa estável nos retries.

n8n

HTTP Request

name → nome, phone → telefone, UTMs homônimas e n8n:{{$json.id}} como referência.

POST · JSON · X-API-Key
Make

HTTP → Make a request

Body Raw/JSON, campos mapeados do bundle e make:ID_DO_EVENTO como referência estável.

POST · application/json
Zap

Webhooks → Custom Request

Desative Data Pass-Through, envie apenas o contrato do North e use o ID do registro de origem na referência.

Retry 429/503 com backoff
RD

Webhook de conversão

name, personal_phone/mobile_phone e traffic_* viram nome, telefone e UTMs.

referencia_externa: rdstation:ID
Em 429 ou 503, aguarde Retry-After e repita o mesmo evento. Respostas 201/created: true e 200/created: false indicam captação aceita; o segundo caso mantém a etapa atual e acrescenta um novo touchpoint.

Autenticação

Uma chave por clínica e finalidade

Envie a chave no header X-API-Key. Prefira chaves separadas para cada integrador, conceda apenas os escopos necessários e revogue a chave ao encerrar o acesso.

HTTPSobrigatório
SHA-256chave armazenada como hash
Escopos por operaçãopermissão mínima

Limites e desempenho

Capacidade sem polling desperdiçado

Os limites protegem todas as clínicas contra rajadas e consultas repetidas. Eles são suficientes para sincronização incremental; excedê-los continuamente indica que o fluxo deve usar paginação, backoff ou webhooks.

Listas de integração300/min por chave
Detalhe de lead e timeline60/min por chave
Cadastro de leads60/min por chave
Rotas de agendamento60/min por chave
Teto agregado de proteção600/min por IP
Timeout / corpo30 s / 1 MB

Em uma resposta 429, aguarde o número de segundos de Retry-After. Os headers X-RateLimit-* mostram o saldo e o reinício da janela.

Boas práticas

Integrações que escalam bem

✓

Use webhooks

Receba eventos e consulte detalhes somente quando houver mudança.

✓

Respeite o cursor

Pagine listas e persista o último cursor processado.

✓

Implemente backoff

Em 429 ou 5xx, aguarde e aumente progressivamente o intervalo.

✓

Deduplicate eventos

Use X-Webhook-Delivery como chave idempotente.

OpenAPI

Referência completa

Carregando contrato