Resumo de endpoints

Legenda

Escopo

Permissão exigida pelo handler, configurada na sua chave pela Sivoe. Chave sem o escopo recebe 403 AUTH_INSUFFICIENT_SCOPE — nesse caso, solicite o ajuste em contato@roomtec.com.br.

• pacientes:read — listar e detalhar pacientes.
• exames:read — listar/detalhar exames e baixar PDFs.
• exames:write — criar exame (POST) com metadados + arquivos inline em base64. Fase 6 — mesmo contrato de idempotência da agenda.
• laudos:read — listar/detalhar laudos e baixar o PDF do laudo.
• laudos:write — ingerir laudo já assinado (POST /v1/exames/{id}/laudo): a API apenas armazena o PDF e marca como assinado — não assina nem gera PDF. Fase 6 — laudo imutável (exame aceita 1 laudo).
• agenda:read — listar/detalhar agendamentos do paciente, listar slots e agendas configuradas.
• agenda:write — criar, cancelar e reagendar agendamentos. Exige Idempotency-Key obrigatório em todo POST (ver § Idempotência).
• pacientes:write — criar (POST), atualizar (PATCH) e unificar duplicados (POST /v1/pacientes/unificar) pacientes. Fase 3* — mesmo contrato de idempotência da agenda. Liberado em piloto em 2026-05-20.
• medicos:write — criar (POST) e atualizar (PATCH) médicos. O médico é um usuário do sistema: usuario e senha são obrigatórios na criação; saudacao e grupo_permissao aceitam texto (resolvido no gateway) ou id. O detalhe (GET /v1/medicos/{id}, escopo catalogos:read) mascara cpf/rg. Mesmo contrato de idempotência da agenda.
• prontuarios:read — listar prontuários (mensagens) do paciente e os metadados dos anexos; obter a URL (302 presigned) de um anexo. Fase 7 — a listagem de anexos nunca expõe URL/chave S3.
• prontuarios:write — criar prontuário (POST /v1/pacientes/{id}/prontuarios) com mensagem HTML e/ou anexos[] em base64. Fase 7 — mesmo contrato de idempotência da agenda.
• — /v1/ping aceita qualquer chave válida.

Auto-filtro de médico

Quando a chave (api_chaves.medico_id) está associada a um médico específico, o gateway injeta um predicado SQL no payload enviado ao backend. Parâmetros medico_*_id na query string são ignorados silenciosamente (evita enumeração). Recursos fora do filtro retornam 404 RES_NOT_FOUND — mesma mensagem de ID inexistente, para não vazar existência.

• N/A — endpoint sem relação direta com médico (pacientes, prontuários do paciente).
• SIMPLES — para exames, o exame é visível quando o médico da chave é o médico do exame, o médico do laudo ou o solicitante. Para agenda, agendamentos cuja agenda está associada ao médico da chave; em POSTs (cancelar/reagendar), o gateway também bloqueia operações sobre agendamentos de outro médico.
• AMPLIADO — laudo é visível quando o médico-laudo bate com a chave, ou quando o exame vinculado satisfaz a regra SIMPLES.
• — — ping (não consulta dados clínicos).

Idempotência nos POST e PATCH

Os endpoints de escrita (3 de agenda, 3 de paciente — criar, atualizar e unificar, criação de exame, ingestão de laudo e criação de prontuário) exigem o header Idempotency-Key (1–64 chars, regex ^[A-Za-z0-9_-]+$; UUID v4 recomendado). Contrato é o mesmo entre Agenda e Pacientes — sem diferenças de comportamento. TTL de 24 horas. Replay com mesmo body devolve a resposta original (status preservado: 201 replay = 201); mesmo header com body diferente devolve 422 IDEMPOTENCY_CONFLICT; outra request em flight devolve 409 CONCURRENT_REQUEST com Retry-After: 2. Detalhes completos em referência § Idempotência.

Badges de método (cores semânticas)

Os badges GET (azul), POST (verde) e PATCH (laranja) seguem a convenção semântica do Bootstrap / Postman / Insomnia — não são branding do produto. O branding Sivoe permanece azul (#015BB5) em hero, navegação e títulos. Códigos de retorno: 201 Created com header Location: nos endpoints de criar (agendamento, paciente); 200 OK em cancelar, reagendar e PATCH.

302 S3 (endpoints /arquivo)

Os endpoints de arquivo respondem com 302 Found e header Location: apontando para uma URL pré-assinada do S3 válida por 300 segundos (5 min). A API não streama bytes — o cliente segue o redirect direto para o S3.

• cURL: use -L para seguir automaticamente.
• Python requests: segue por padrão.
• Node fetch: segue por padrão.
• PHP cURL: mantenha CURLOPT_FOLLOWLOCATION = false para inspecionar a URL antes; ao reusá-la, não reassine com seu HMAC — a presigned já autentica contra o S3 (ver FAQ Q12).

Resolução por identificadores de negócio (POST /v1/exames — 1.1.0)

Desde a release 1.1.0 (X-Api-Release: 1.1.0; X-Api-Version continua v1), o POST /v1/exames aceita 8 aliases opcionais — paciente_cpf, procedimento_codigo_tuss, procedimento_abreviacao, convenio_codigo_ans (só casa convênios com ANS preenchido), convenio_nome, medico_exame_crm, medico_laudo_crm e unidade_nome — que o gateway resolve para o *_id correspondente. São aditivos: payloads legados com os *_id continuam válidos. Precedência: o *_id vence (conflito com alias da mesma FK → 422 PARAM_CONFLICT); sem id, o alias resolve (0 exatos → 422 RESOLUTION_NOT_FOUND, 2+ → 422 RESOLUTION_AMBIGUOUS com candidatos[]); CPF mal formado → 400 VAL_INVALID_PARAM. Campos unidade_id, medico_exame_id, medico_laudo_id e convenio_id são omitíveis quando o tenant tem default — consulte GET /v1/config para descobrir o que pode ser omitido. A resposta 201 documenta a origem dos ids em meta.resolvido (de alias) e meta.defaults_aplicados (de default). Detalhes em referência § Resolução.

Códigos de erro

Toda resposta de erro segue o envelope padrão { data: null, meta, error }. Para o catálogo completo de error.code (HTTP, AUTH_*, VAL_*, RES_*, BACKEND_*), veja códigos de erro.