API REST

O Clinicar expõe uma API REST para integrar o prontuário e a operação da clínica com ferramentas externas — automações, BI, WhatsApp, sistemas financeiros e outros softwares. A base da API é /api/v1. A documentação interativa (OpenAPI via Scalar) fica em:

https://clinicar.app/api/v1/docs

Nessa página você encontra a lista de endpoints, schemas, exemplos e um ambiente para testar chamadas.

Pré-requisito: módulo API Keys

A seção Chaves de API em Configurações > Minhas conexões só aparece se um administrador ligar o módulo API Keys em Configurações > Integrações e comunicação.

1. Abra Configurações > Integrações e comunicação. Se a área estiver oculta, habilite a categoria em Configurações > Ativar módulos.
2. Ative API Keys.
3. A alteração salva ao alternar (não há botão separado de salvar).

Com o módulo desligado, a UI de chaves some de Minhas conexões — não há como criar ou listar chaves por ali.

Detalhes do módulo: Módulos da clínica.
Veja também o guia de Conta e conexões.

Criar e guardar a chave

Com o módulo ligado:

1. Vá em Configurações > Minhas conexões.
2. Na seção Chaves de API, clique em Nova chave.
3. Informe um nome que identifique a integração (ex.: n8n produção, BI interno).
4. Clique em Criar chave.
5. Copie o valor completo exibido (prefixo típico clk_live_…) e guarde em local seguro (cofre de senhas, variáveis de ambiente do integrador, etc.).

Limites e gestão

• Até 10 chaves ativas por vínculo do usuário com a clínica.
• Filtros da lista: Todas, Ativas e Revogadas.
• Revogar — desativa a chave na hora; integrações que a usam param de autenticar; o registro permanece no histórico.
• Excluir — remove o registro definitivamente.

Consulte também Conta e conexões para gerenciar credenciais pessoais.

Autenticação

A API aceita três esquemas de autenticação (registrados no OpenAPI: cookieAuth, bearerAuth e xApiKeyAuth):

A chave de API amarra o usuário que a criou e a clínica em que a chave foi criada. As chamadas respeitam as permissões do perfil desse usuário na clínica — a API não eleva privilégios além do que a conta teria na interface.

Exemplo com Bearer (recomendado para integrações)

curl -X GET https://clinicar.app/api/v1/patients \
  -H "Authorization: Bearer clk_live_SUA_CHAVE_AQUI" \
  -H "Accept: application/json"

Equivalente com header dedicado:

curl -X GET https://clinicar.app/api/v1/patients \
  -H "x-api-key: clk_live_SUA_CHAVE_AQUI" \
  -H "Accept: application/json"

Testar no Scalar

1. Gere e copie uma chave (passos acima).
2. Abra /api/v1/docs.
3. Configure a autenticação Bearer com a chave (esquema preferido na documentação interativa).
4. Execute os endpoints desejados.

Se você já estiver logado no navegador na mesma origem, o cookie de sessão também pode autenticar chamadas no Scalar — útil para explorar, mas não substitui a chave em automações e serviços externos.

Recursos disponíveis

Abaixo, em linguagem de clínica, os grupos alinhados às tags da API (OpenAPI). A superfície exata de cada endpoint está sempre em /api/v1/docs.

Plataforma

• Health — verificação de disponibilidade da API
• API Keys — gestão programática de chaves (além da tela Minhas conexões)

Clínico

• Pacientes — cadastro e consulta de pacientes
• Prontuário — leitura de registros clínicos (somente leitura, dados sanitizados)
• Duplicados — detecção e mescla de pacientes duplicados
• Agendamentos — agenda e status de consultas
• Atendimentos — consultas clínicas e competência de cobrança
• Agendas / slots — grades e horários disponíveis
• Workflows / Flows — pipelines, estágios e cards de fluxo

Faturamento

• Convênios / planos — consultas de planos de saúde no fluxo de cobrança
• Profissionais — lookups de profissionais para faturamento
• Ordens de serviço — itens, preços, ciclo de vida e ajustes financeiros
• Faturas — faturas, cobranças e recebíveis de paciente
• Pagamentos — registros de pagamento, formas de quitação e estornos
• Lotes — lotes de faturamento de convênio e acertos
• Caixa — abertura e fechamento de caixa
• Configurações de recebimento — conta de recebimento da clínica
• Relatórios — relatórios de caixa e recebíveis de convênio

Financeiro

• Contas — contas financeiras e saldos
• Transações — lançamentos do livro e estornos
• Importações — extratos/importações bancárias e conciliação
• Favorecidos (counterparties) — beneficiários genéricos de contas a pagar
• Centros de custo — catálogo usado em contas a pagar
• Contas a pagar — documentos a pagar, liquidações e anexos

Padrões técnicos

• Base URL: /api/v1
• Formato: JSON
• IDs: UUIDv7
• Validação: entradas inválidas retornam erro com detalhes dos campos
• Especificação: OpenAPI 3.1, em /api/v1/docs e /api/v1/openapi.json

Casos de uso comuns

• Automações com chave — n8n, Make, scripts ou serviços da clínica chamando a API com Bearer ou x-api-key, sem depender de sessão de navegador
• BI e dashboards — extrair agendamentos, pacientes, caixa e relatórios para ferramentas de análise
• WhatsApp e comunicação — ler agenda e dados de paciente para lembretes, confirmações e filas de mensagem
• Financeiro e ordens de serviço — integrar faturas, pagamentos, lotes, caixa e contas a pagar com ERP ou contabilidade
• Flows / CRM clínico — sincronizar ou alimentar cards e estágios de workflow a partir de sistemas externos
• Sistemas legados — migrar ou espelhar pacientes e agenda via API

Dicas

• Comece sempre por /api/v1/docs — a referência é gerada a partir do código e acompanha o produto.
• Prefira Bearer nas integrações; use cookie só para exploração manual logada.
• Revogue chaves comprometidas ou de integrações desativadas; exclua só quando o histórico não for mais necessário.
• Lembre: sem o módulo API Keys ligado, a seção de chaves não aparece em Minhas conexões.
• As permissões da API seguem o perfil do usuário dono da chave na clínica vinculada à chave.