API pública & integrações

A página Integrações externas gerencia as chaves da API pública v1 — acesso READ-ONLY de sistemas externos (BI, ERP contábil, parceiros) aos dados da unidade — e os webhooks de saída (avisos HTTP para eventos do sistema). A chave completa (orn_…) aparece uma única vez na criação; guarde-a com segurança.

• Autenticação: header Authorization: Bearer orn_… em /api/v1/*. No banco fica só o hash — chave perdida = criar outra.
• Escopos (read-only): patients:read (pacientes/tutores — base org-global da rede), appointments:read e billing:read (agendamentos e contas médicas da unidade da chave).
• Endpoints v1: GET /api/v1/patients (+/{id}, ?search&limit&cursor), GET /api/v1/appointments?from&to&status, GET /api/v1/medical-accounts?status (+/{id} com itens). Paginação por cursor; datas em ISO-8601; valores em centavos.
• Rate limit: 120 req/min por chave (HTTP 429 ao exceder).
• Revogação: imediata — a chave revogada passa a receber 401.
• Webhooks de saída: POST JSON no seu endpoint a cada evento — account.closed, tiss.guide.returned, appointment.created, patient.created — assinado com HMAC-SHA256 do corpo (header X-Orion-Signature: sha256=<hex>, secret exibido 1× na criação). Entrega com retry/backoff (1min → 24h, 7 tentativas) por fila durável; falhas aparecem no log com botão Reenviar. Valide sempre a assinatura antes de confiar no payload.

• BI da rede: dashboard externo lendo contas médicas fechadas por período.
• ERP contábil: conciliação lendo o faturamento da unidade.
• Parceiro de confirmação: leitura da agenda do dia.

Complementa os webhooks de saída (push de eventos) — juntos formam a integração bidirecional; o acesso é auditado por chave (último uso).

Integrações externas (api.manage) — restrita ao administrador por padrão.