# SmartDoctor Developers

> API REST oficial do SmartDoctor — sistema de gestão para clínicas e consultórios. Permite que sistemas externos, fluxos n8n e agentes de IA consultem horários livres, pacientes e valores, e criem, reagendem ou cancelem consultas. Autenticação por API Key no header `X-Api-Key`, com escopo automático por clínica (a clínica é derivada da chave, nunca enviada no payload).

URL base: https://api.smartdoctor.com.br — todos os endpoints ficam sob o prefixo `/integracao`.
Autenticação: header `X-Api-Key: <chave>`. Gere a chave em Perfil › Configurações › Integrações (aparece uma única vez; guardada como hash SHA-256).
Formato: JSON (UTF-8). Datas em `AAAA-MM-DD`, horas em `HH:mm`. CPF com ou sem máscara.
Erros: sempre `{"erro": "mensagem"}`. Status 400 (validação), 401 (chave inválida), 404 (não encontrado).

## Documentação
- [Guia rápido](https://www.smartdoctor.com.br/docs/#guia-rapido): primeiro request em 4 passos.
- [Autenticação](https://www.smartdoctor.com.br/docs/#autenticacao): header X-Api-Key, escopo por clínica, segurança.
- [Convenções e erros](https://www.smartdoctor.com.br/docs/#convencoes): datas, CPF, enum de situação, códigos de status.
- [Receita n8n + IA](https://www.smartdoctor.com.br/docs/#n8n): fluxo de agente virtual que marca consulta.

## Endpoints (Referência)
- POST `/integracao/agendas` — cria consulta. Body: dtAgenda, consultaValor.especialidade.nome (com preço PARTICULAR), paciente.cpf (nome/celular/dtnascimento se paciente novo); hora e medico.id opcionais (hora omitida = 1º slot livre). operador ignorado (grava "AGENTE AUTOMÁTICO"). Requer grade de agenda na data + tipo de atendimento cadastrado.
- PUT `/integracao/agendas` — reagenda (dtAgenda+hora) ou cancela (situacaoAgenda=CANCELADO). Localiza por id OU por cpf.
- GET `/integracao/agendas/{id}` — detalha uma agenda da clínica da chave.
- GET `/integracao/agendas/listar` — lista agendas. Query: pacienteCpf, dataInicio, situacaoAgenda.
- GET `/integracao/agendas/verificar` — checa conflito. Query: pacienteCpf, dataConsulta, especialidadeNome.
- POST `/integracao/controle-agendas/horarios-disponiveis` — horários livres. Body: especialidade.
- GET `/integracao/pacientes/cpf` — busca paciente por CPF. Query: cpf.
- GET `/integracao/consultas-valor` — lista valores ativos. Query: especialidadeNome (opcional).

## Recursos
- [OpenAPI 3.1](https://www.smartdoctor.com.br/docs/openapi.json): especificação máquina-legível.
- [Documentação completa para LLM](https://www.smartdoctor.com.br/docs/llms-full.txt): esta API detalhada em texto puro.

## Notas
- Situações de agenda: AGENDADO, AUSENTE, CANCELADO, EM_ATENDIMENTO, FINALIZADO, SALA_ESPERA.
- Webhooks de saída (push de eventos) estão no roadmap; hoje a integração é pull (consulta sob demanda).