Como me autentico na API do SmartDoctor?

Envie o header HTTP X-Api-Key com a chave gerada em Perfil › Configurações › Integrações. A chave é vinculada a uma clínica e todas as operações são escopadas automaticamente a ela.

Qual é a URL base da API do SmartDoctor?

A URL base é https://api.smartdoctor.com.br e todos os endpoints de integração ficam sob o prefixo /integracao.

Como integrar o SmartDoctor com n8n ou um agente de IA?

Use um nó HTTP Request (n8n) ou qualquer cliente HTTP apontando para https://api.smartdoctor.com.br/integracao/*, enviando o header X-Api-Key. Os endpoints permitem consultar horários livres, verificar pacientes por CPF, criar, reagendar e cancelar consultas.

O SmartDoctor envia webhooks de eventos?

Webhooks de saída (push de eventos como consulta criada ou cancelada) estão no roadmap. Hoje a integração é via API REST de entrada, que os sistemas externos consultam sob demanda.

API REST · v1

Conecte o SmartDoctor a qualquer sistema.

Uma API REST feita para automação. Marque, reagende e cancele consultas, consulte horários livres, pacientes e valores — direto do n8n, de agentes de IA ou do seu próprio backend. Autenticação por API Key, dados sempre escopados por clínica.

Começar em 5 minutos Ver referência

9endpoints REST

SHA-256chaves com hash

JSONrequest & response

n8n · IAprontos pra usar

exemplo — listar agendas de hoje

curl https://api.smartdoctor.com.br/integracao/agendas/listar \
  -H "X-Api-Key: sd_live_9f2c…a71b" \
  -G --data-urlencode "situacaoAgenda=AGENDADO"

# 200 OK · resposta
# [ { "id": "a1b2…", "dtAgenda": "2026-07-06",
#     "hora": "09:00", "especialidade": "CARDIOLOGIA",
#     "paciente": { "nome": "Maria Silva" } } ]

O que dá pra fazer #

A API cobre o ciclo de agendamento de ponta a ponta. Ideal para atendentes virtuais, bots de WhatsApp e fluxos de automação.

Agendar consultas

Crie agendas informando especialidade, data, hora e paciente. O sistema resolve valor e disponibilidade automaticamente.

Consultar horários livres

Descubra slots disponíveis por especialidade e médico antes de oferecer um horário ao paciente.

Localizar pacientes

Busque por CPF para saber se o paciente já é cadastrado na clínica e recuperar contato.

Reagendar e cancelar

Atualize a situação de uma agenda — CANCELADO, ou nova data/hora — em uma única chamada.

Automatizar com n8n

Um nó HTTP Request e a sua API Key bastam. Monte lembretes, confirmações e follow-ups sem escrever backend.

Dar mãos a agentes de IA

Exponha os endpoints como ferramentas (tools) do seu agente: ele marca a consulta conversando com o paciente.

Guia rápido #

Do zero à primeira consulta agendada em quatro passos.

Gere sua API Key

No SmartDoctor, vá em Perfil › Configurações › Integrações e clique em Nova chave. A chave em texto puro aparece uma única vez — copie e guarde num cofre de segredos.

Abrir tela de Integrações →

Guarde a URL base

Todas as chamadas partem de https://api.smartdoctor.com.br, sob o prefixo /integracao.

Faça o primeiro request

Envie a chave no header X-Api-Key. Este exemplo lista os valores de consulta ativos da sua clínica:

curl https://api.smartdoctor.com.br/integracao/consultas-valor \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

// Nó "HTTP Request" do n8n
{
  "method": "GET",
  "url": "https://api.smartdoctor.com.br/integracao/consultas-valor",
  "sendHeaders": true,
  "headerParameters": {
    "parameters": [
      { "name": "X-Api-Key", "value": "={{ $env.SMARTDOCTOR_API_KEY }}" }
    ]
  }
}

import requests

resp = requests.get(
    "https://api.smartdoctor.com.br/integracao/consultas-valor",
    headers={"X-Api-Key": "SUA_CHAVE_AQUI"},
)
print(resp.json())

const resp = await fetch(
  "https://api.smartdoctor.com.br/integracao/consultas-valor",
  { headers: { "X-Api-Key": "SUA_CHAVE_AQUI" } }
);
console.log(await resp.json());

Marque uma consulta

Com um horário livre em mãos (veja Horários livres), envie um POST para criar a agenda. Pronto — você automatizou o agendamento.

Autenticação #

Toda requisição à API de integração exige uma API Key no header HTTP.

Header obrigatório

X-Api-Key: SUA_CHAVE_AQUI

Como funciona o escopo por clínica

Cada API Key nasce vinculada a uma única clínica. O SmartDoctor deriva a clínica a partir da própria chave — você nunca envia o ID da clínica no corpo ou na URL. Se um payload trouxer outra clínica, ela é ignorada. Isso garante que uma chave jamais enxergue dados de outra clínica.

Segurança em primeiro lugar. A chave é armazenada apenas como hash SHA-256 — nem o SmartDoctor consegue recuperá-la depois. Se perder, revogue e gere outra.

Boas práticas

Faça	Não faça
Guarde a chave em variável de ambiente ou cofre de segredos.	Não versione a chave em repositórios ou no front-end.
Use uma chave por integração (n8n, bot, ERP) — facilita revogar.	Não reaproveite a mesma chave em vários sistemas.
Revogue chaves que não usa mais na tela de Integrações.	Não exponha a chave em URLs ou logs.

Sem o header X-Api-Key, ou com chave inválida/revogada, a API responde 401 Unauthorized: {"erro": "API Key inválida ou ausente"}.

Convenções & erros #

Padrões que valem para todos os endpoints.

Assunto	Convenção
Base URL	`https://api.smartdoctor.com.br/integracao`
Formato	Request e response em `application/json` (UTF-8).
Datas	ISO-8601 `AAAA-MM-DD` (ex.: `2026-07-15`). Horas em `HH:mm`.
CPF	Pode enviar com ou sem máscara — o sistema normaliza para só dígitos.
Situação da agenda	`AGENDADO`, `AUSENTE`, `CANCELADO`, `EM_ATENDIMENTO`, `FINALIZADO`, `SALA_ESPERA`.

Códigos de status

Código	Significado	Corpo
200 / 201	Sucesso. `201` ao criar recurso.	Objeto ou lista JSON.
400	Requisição inválida (validação de negócio).	`{"erro": "mensagem"}`
401	API Key ausente, inválida ou revogada.	`{"erro": "API Key inválida ou ausente"}`
404	Recurso não encontrado (ou de outra clínica).	`{"erro": "Agenda não encontrada"}`
500	Erro interno inesperado.	`{"erro": "detalhe"}`

Erros de negócio sempre voltam no campo erro com uma mensagem legível — trate esse campo no seu fluxo para dar feedback ao paciente.

Criar agenda #

Agenda uma nova consulta. A clínica vem da API Key; especialidade e valor são resolvidos automaticamente (convênio PARTICULAR).

POST/integracao/agendasCria uma consulta

Corpo da requisição

Campo	Tipo	Descrição
`dtAgenda` obrig.	date	Data da consulta (`AAAA-MM-DD`).
`consultaValor.especialidade.nome` obrig.	string	Nome da especialidade cadastrada na clínica (ex.: `CARDIOLOGIA`). Precisa ter preço no convênio PARTICULAR.
`paciente.cpf` obrig.	string	Se o CPF já existir, reaproveita o paciente.
`paciente` (demais) recomend.	object	`nome`, `celular`, `dtnascimento` — obrigatórios quando o paciente ainda não existe (será criado).
`hora` opcional	string	Horário `HH:mm`. Se omitido, o sistema pega o primeiro horário livre da data. Se informado, precisa estar livre.
`medico.id` opcional	string	Fixa um médico. Se omitido, usa qualquer médico com agenda na data.
`observacao` opcional	string	Nota livre (ex.: origem do agendamento).

Pré-requisitos na clínica (senão retorna 400 com a mensagem do motivo): a especialidade precisa ter preço em PARTICULAR; precisa existir grade de agenda (controle de agenda) do médico para a especialidade na data; e ao menos um tipo de atendimento cadastrado (ex.: 1ª CONSULTA). O campo operador é definido pelo sistema (AGENTE AUTOMÁTICO) — não precisa enviar.

curl -X POST https://api.smartdoctor.com.br/integracao/agendas \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "dtAgenda": "2026-07-15",
    "hora": "09:00",
    "consultaValor": { "especialidade": { "nome": "CARDIOLOGIA" } },
    "paciente": {
      "nome": "Maria Silva",
      "cpf": "123.456.789-01",
      "celular": "11999998888",
      "dtnascimento": "1990-05-20"
    },
    "observacao": "Agendado via agente de IA"
  }'

{
  "dtAgenda": "2026-07-15",
  "hora": "09:00",
  "consultaValor": { "especialidade": { "nome": "CARDIOLOGIA" } },
  "medico": { "id": "opcional-uuid-do-medico" },
  "paciente": {
    "nome": "Maria Silva",
    "cpf": "123.456.789-01",
    "celular": "11999998888",
    "dtnascimento": "1990-05-20"
  },
  "observacao": "Agendado via agente de IA"
}

import requests

payload = {
    "dtAgenda": "2026-07-15",
    "hora": "09:00",
    "consultaValor": {"especialidade": {"nome": "CARDIOLOGIA"}},
    "paciente": {
        "nome": "Maria Silva", "cpf": "12345678901",
        "celular": "11999998888", "dtnascimento": "1990-05-20",
    },
}
r = requests.post(
    "https://api.smartdoctor.com.br/integracao/agendas",
    headers={"X-Api-Key": "SUA_CHAVE_AQUI"}, json=payload,
)
print(r.status_code, r.json())

201 Created

{
  "id": "a1b2c3d4-…",
  "dtAgenda": "2026-07-15",
  "hora": "09:00",
  "situacaoAgenda": "AGENDADO",
  "especialidade": "CARDIOLOGIA",
  "medico": "Dr. João Ramos",
  "medicoId": "m-88…",
  "endereco": "Unidade Centro",
  "valorConsulta": 250.0,
  "operador": "AGENTE AUTOMÁTICO",
  "paciente": {
    "id": "p-33…", "nome": "Maria Silva", "cpf": "12345678901",
    "celular": "11999998888", "dtnascimento": "1990-05-20"
  }
}

Reagendar ou cancelar #

Atualiza uma agenda existente: mude a situação (cancelar) ou informe nova data/hora (reagendar).

PUT/integracao/agendasAtualiza situação ou data

Campo	Tipo	Descrição
`id` recomend.	string	ID da agenda a atualizar. Se você não tiver o `id`, envie `cpf`.
`cpf` alt.	string	Localiza a única agenda ativa do paciente na clínica (fallback quando não há `id`). Com várias, refine por `dtAgenda`.
`situacaoAgenda` condic.	enum	Para cancelar: `CANCELADO`.
`dtAgenda` + `hora` condic.	date+string	Para reagendar: nova data e horário (o horário precisa estar livre).

curl -X PUT https://api.smartdoctor.com.br/integracao/agendas \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "id": "a1b2c3d4-…", "situacaoAgenda": "CANCELADO" }'

curl -X PUT https://api.smartdoctor.com.br/integracao/agendas \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "id": "a1b2c3d4-…", "dtAgenda": "2026-07-18", "hora": "14:30" }'

200 OK — devolve a agenda atualizada (mesmo formato do POST).

Buscar agenda por ID #

GET/integracao/agendas/{id}Detalha uma agenda

Retorna a agenda se ela pertencer à clínica da sua chave. Caso contrário, responde 404 — sem vazar a existência de agendas de outras clínicas.

curl https://api.smartdoctor.com.br/integracao/agendas/a1b2c3d4-… \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

Listar agendas #

Lista agendas a partir de uma data (padrão: hoje), com filtros opcionais de paciente e situação.

GET/integracao/agendas/listarConsulta com filtros

Parâmetro (query)	Tipo	Descrição
`pacienteCpf` opcional	string	Filtra pelas agendas do paciente.
`dataInicio` opcional	date	Data mínima (`AAAA-MM-DD`). Padrão: hoje.
`situacaoAgenda` opcional	enum	Ex.: `AGENDADO`.

curl -G https://api.smartdoctor.com.br/integracao/agendas/listar \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-urlencode "pacienteCpf=12345678901" \
  --data-urlencode "situacaoAgenda=AGENDADO"

200 OK — array de agendas.

Verificar conflito #

Checa se o paciente já tem agenda numa data e especialidade — útil para evitar duplicidade antes de agendar.

GET/integracao/agendas/verificarAntiduplicidade

Parâmetro (query)	Tipo	Descrição
`pacienteCpf` obrig.	string	CPF do paciente.
`dataConsulta` obrig.	date	Data a verificar.
`especialidadeNome` obrig.	string	Especialidade a verificar.

curl -G https://api.smartdoctor.com.br/integracao/agendas/verificar \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-urlencode "pacienteCpf=12345678901" \
  --data-urlencode "dataConsulta=2026-07-15" \
  --data-urlencode "especialidadeNome=CARDIOLOGIA"

Retorna um array — vazio se não houver conflito, ou com as agendas encontradas.

Horários livres #

Retorna os slots disponíveis por especialidade — a base para oferecer horários reais ao paciente.

POST/integracao/controle-agendas/horarios-disponiveisDisponibilidade

Campo (body)	Tipo	Descrição
`especialidade` obrig.	string	Nome da especialidade (ex.: `CARDIOLOGIA`).

curl -X POST https://api.smartdoctor.com.br/integracao/controle-agendas/horarios-disponiveis \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "especialidade": "CARDIOLOGIA" }'

200 OK

[
  {
    "especialidade": "CARDIOLOGIA",
    "medico": "Dr. João Ramos",
    "medicoId": "m-88…",
    "data": "2026-07-15",
    "horariosDisponiveis": ["08:00", "08:30", "09:00"],
    "totalPossivel": 10,
    "totalOcupado": 7,
    "totalDisponivel": 3,
    "horaInicio": "08:00",
    "horaFim": "13:00",
    "tempoAtendimento": 30
  }
]

Paciente por CPF #

Descobre se o CPF já é paciente da clínica e recupera o contato.

GET/integracao/pacientes/cpfLookup por CPF

Parâmetro (query)	Tipo	Descrição
`cpf` obrig.	string	CPF com ou sem máscara.

curl -G https://api.smartdoctor.com.br/integracao/pacientes/cpf \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-urlencode "cpf=123.456.789-01"

200 OK — encontrado

{
  "encontrado": true,
  "id": "p-33…",
  "nome": "Maria Silva",
  "cpf": "12345678901",
  "celular": "11999998888",
  "dtnascimento": "1990-05-20"
}

{ "encontrado": false, "mensagem": "Paciente não cadastrado nesta clínica" }

Valores de consulta #

Lista as especialidades ativas e seus valores — útil para informar preços ao paciente.

GET/integracao/consultas-valorTabela de preços

Parâmetro (query)	Tipo	Descrição
`especialidadeNome` opcional	string	Filtra por uma especialidade.

curl https://api.smartdoctor.com.br/integracao/consultas-valor \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

[
  { "id": "cv-1…", "especialidade": "CARDIOLOGIA", "convenio": "PARTICULAR", "valor": 250.0 },
  { "id": "cv-2…", "especialidade": "DERMATOLOGIA", "convenio": "PARTICULAR", "valor": 200.0 }
]

Receita: agente de IA que agenda no n8n #

Um fluxo típico de atendente virtual que conversa no WhatsApp e marca a consulta sozinho.

1 · Paciente

Pede horário no WhatsApp

→

2 · Agente IA

Interpreta a intenção

→

3 · Horários

GET horários livres

→

4 · Agenda

POST cria consulta

Guarde a chave como credencial

No n8n, salve a API Key em uma variável de ambiente (SMARTDOCTOR_API_KEY) ou credencial de Header Auth. Nunca cole a chave direto no nó.

Consulte horários livres

Nó HTTP Request → POST /integracao/controle-agendas/horarios-disponiveis com o header X-Api-Key e body { "especialidade": "CARDIOLOGIA" }. O agente oferece os horários retornados ao paciente.

Verifique duplicidade (opcional)

Antes de gravar, chame GET /integracao/agendas/verificar para não marcar a mesma consulta duas vezes.

Crie a agenda

Nó HTTP Request → POST /integracao/agendas com o horário escolhido e os dados do paciente. Responda a confirmação no WhatsApp com o id retornado.

Dica de agente de IA: exponha cada endpoint como uma tool do modelo. Descreva os parâmetros exatamente como nesta página — o LLM monta o JSON e chama a API sozinho.

Webhooks Em breve #

Hoje a integração é pull: seu sistema consulta a API quando precisa. Estamos construindo o push.

Em breve você poderá registrar uma URL e receber eventos em tempo real, sem ficar consultando:

Evento (planejado)	Dispara quando
`agenda.criada`	Uma nova consulta é marcada.
`agenda.reagendada`	Data ou hora de uma consulta muda.
`agenda.cancelada`	Uma consulta é cancelada.
`agenda.confirmada`	O paciente confirma presença.

Cada entrega virá assinada com HMAC (para você validar a origem) e terá reenvio automático em caso de falha. Quer ser avisado no lançamento? Fale com o suporte.

OpenAPI & ferramentas #

Consuma a especificação legível por máquina — ideal para gerar clientes e para ferramentas de IA.

openapi.json →

Spec OpenAPI 3.1 completa. Importe no Postman, Insomnia ou gere um SDK.

llms.txt →

Índice pensado para modelos de linguagem entenderem a API rapidamente.

Suporte #

Dúvidas de integração, aumento de limites ou acesso antecipado a webhooks?

Fale com a gente pelo canal de suporte da sua conta SmartDoctor, ou pelo site smartdoctor.com.br. Traga sua API Key (apenas o ID/descrição, nunca o segredo) e o endpoint envolvido para agilizar.