Prontuário (CRUD)

O módulo de Prontuário é opcional e fica disponível apenas para API Keys com escopos habilitados. Ele permite armazenar contexto clínico mínimo (sem PII) para ser reutilizado:

• diretamente pelo cliente (CRUD)
• indiretamente pelo Agente de Interações, via patient_reference na rota de checagem (quando o escopo de leitura estiver ativo)

Escopos

• Leitura: prontuario:read
• Escrita: prontuario:write

Cabeçalhos

• X-API-Key: sm_live_...
• Content-Type: application/json

POST /api/v1/prontuario

Cria um prontuário para um patient_reference dentro da organização da API Key.

Body

{
  "patient_reference": "PRONT-12345",
  "current_medications": [
    {"name": "Metformina", "dose_mg": "850", "frequency": "12/12h", "route": "VO"},
    {"name": "Losartana", "dose_mg": "50"}
  ],
  "conditions": ["diabetes", "hipertensao"],
  "allergies": ["penicilina"],
  "notes": "Sem PII. Apenas contexto clinico relevante.",
  "patient_context": {
    "renal_function": "DRC estagio 3",
    "pregnancy": false
  }
}

Dose com decimais (ex.: 2,5 mg)

O campo current_medications[].dose_mg aceita:

• número (2.5)
• string com vírgula ou ponto (\"2,5\", \"2.5\", \"2,5mg\")

Resposta 200

{
  "id": "uuid",
  "patient_reference": "PRONT-12345",
  "current_medications": [
    {"name": "Metformina", "dose_mg": 850.0, "frequency": "12/12h", "route": "VO"}
  ],
  "conditions": ["diabetes", "hipertensao"],
  "allergies": ["penicilina"],
  "notes": "Sem PII. Apenas contexto clinico relevante.",
  "patient_context": {"renal_function": "DRC estagio 3", "pregnancy": false},
  "created_at": "2026-04-23T00:00:00Z",
  "updated_at": "2026-04-23T00:00:00Z"
}

Erros comuns

• 403 se a API Key não tiver prontuario:write
• 409 se já existir prontuário para o mesmo patient_reference
• 422 se patient_reference parecer PII (CPF/e-mail/telefone) ou se notes exceder o limite

GET /api/v1/prontuario

Lista prontuários (soft-deleted não aparecem).

Query params

• limit (default: 50)
• offset (default: 0)
• patient_reference (opcional; filtro exato)

GET /api/v1/prontuario/{record_id}

Retorna um prontuário por id.

GET /api/v1/prontuario/by-reference/{patient_reference}

Retorna um prontuário pelo patient_reference.

PATCH /api/v1/prontuario/{record_id}

Atualização parcial. Campos omitidos não são alterados.

Body (exemplo)

{
  "notes": "Atualizado",
  "current_medications": []
}

DELETE /api/v1/prontuario/{record_id}

Soft delete (o registro deixa de aparecer em listagens e retornos).

Integração com Interações (enrichment por escopo)

Na rota POST /api/v1/interactions/check, envie patient_record.patient_reference. Quando a API Key tiver prontuario:read, a API pode preencher automaticamente campos faltantes a partir do prontuário salvo (por exemplo, conditions e current_medications), mantendo a requisição compatível com o contrato da checagem.