POST /api/v1/interactions/check

Envie uma prescrição com medicamentos e, opcionalmente, contexto clínico do paciente para receber uma análise estruturada com contrato estável, rastreabilidade de fontes e política fail-safe.

Copia um prompt pronto com fluxo de integração, payload e exemplos.

dica

Sempre que possível, preencha patient_record.conditions e patient_record.current_medications. Isso melhora o contexto e reduz o risco de falso negativo.

Camada determinística de segurança

Além das fontes externas (DDInter, openFDA, DailyMed, PubMed) e da base local, a análise aplica uma base curada de interações maiores/contraindicadas que funciona offline e independe do idioma de entrada. Combinações clássicas (ex.: anticoagulante + antiagregante, nitrato + inibidor de PDE5, estatina + inibidor potente de CYP3A4) são sempre sinalizadas, mesmo que uma fonte externa esteja indisponível. Esses achados aparecem em interactions[] com evidence[].source = "safety_net". Uma interação grave/contraindicada detectada nunca é rebaixada para UNKNOWN por cobertura parcial.

Cabeçalhos

• X-API-Key: <sua-chave>
• Content-Type: application/json
• Scope exigido: interactions:check

Body

{
  "medications": [
    {"name": "Warfarina", "dose_mg": 5},
    {"name": "Omeprazol", "dose_mg": 20}
  ],
  "patient_record": {
    "patient_reference": "PRONT-12345",
    "current_medications": [
      {"name": "Dipirona", "dose_mg": 500}
    ],
    "conditions": ["diabetes", "hipertensao"],
    "notes": "Opcional. Evite PII (CPF/telefone/email)."
  },
  "language": "pt-BR"
}

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

O campo dose_mg aceita:

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

Contrato clínico estruturado (UCUM)

Além de dose_mg, cada medicamento aceita campos estruturados opcionais (compatível com o formato antigo). Quando dose + dose_unit (UCUM) são informados e dose_mg é omitido, o motor deriva os mg automaticamente:

Campo	Descrição
dose + dose_unit	Valor + unidade UCUM: mg, g, mcg, ng, mg/kg, mg/m2 (deriva mg; mg/kg usa o peso, mg/m2 usa a superfície corporal).
dose_form · concentration · duration	Forma farmacêutica, concentração/apresentação, duração.
prn · continuous · indication	Se necessário, uso contínuo, indicação clínica.
dcb · atc · rxnorm · gtin	Códigos do medicamento (quando disponíveis).

Unidades não convertíveis para massa (UI/IU, mEq, mmol, %, gotas, jatos, mL) são aceitas, mas a validação de dose máxima não é aplicada e um aviso ⓘ é emitido (transparência).

{ "medications": [
  { "name": "Paracetamol", "dose": 2, "dose_unit": "g", "frequency": "6/6h", "dose_form": "comprimido" },
  { "name": "Vancomicina", "dose": 15, "dose_unit": "mg/kg", "route": "IV" },
  { "name": "Insulina NPH", "dose": 10, "dose_unit": "UI" }
] }

Condições por código CID-10

patient_record.conditions aceita tanto texto livre ("insuficiencia renal") quanto código CID-10 ("N18.3") — ambos resolvem para a mesma tag interna e disparam as mesmas validações (ex.: renal_adjustment). A cobertura é curada para os domínios que o motor avalia (renal, hepático, IC, asma/DPOC, gravidez, lactação, sangramento GI, hipercalemia, HAS, diabetes, QT longo, Parkinson, glaucoma, HPB, epilepsia) — não é uma tabela CID-10 completa.

Farmacogenética (opcional, opt-in)

patient_context.genotype aceita um mapa gene → fenótipo (ex.: {"CYP2D6": "poor_metabolizer", "CYP2C19": "poor_metabolizer"}). Só é avaliado quando enviado explicitamente — a SauBit não infere nem armazena genótipo. Ver pharmacogenomic em Validações clínicas para os pares gene-fármaco cobertos.

Transparência de contexto (clinical_context_assessment)

A resposta inclui o bloco clinical_context_assessment, deixando explícito que "sem interação conhecida" ≠ "seguro" quando faltam dados:

"clinical_context_assessment": {
  "context_completeness": 0.5,
  "missing_clinical_context": ["weight", "renal_function", "hepatic_function"],
  "not_evaluated_domains": ["renal_adjustment", "drug_allergy"],
  "residual_risk": "UNKNOWN"
}

• context_completeness: fração dos domínios de contexto presentes (idade, peso, função renal/ hepática, alergias, condições).
• not_evaluated_domains: validações que não puderam rodar por falta de dado.
• residual_risk: escala para UNKNOWN quando a prescrição parece de baixo risco apenas porque dados relevantes não foram informados.

Contrato atual

Campos principais da resposta:

• analysis_status: complete | partial | failed
• prescription_risk_level: LOW | MODERATE | HIGH | CRITICAL | UNKNOWN
• prescription_score: 0-100 ou null
• confidence_score: 0.0-1.0
• confidence_reason: resumo textual do grau de confiança
• clinical_relevance: high | moderate | low | unknown
• recommendation_level: avoid_combination | monitor | adjust_dose | consult_professional | no_known_interaction | unknown
• normalized_medications: medicamentos considerados na análise
• interactions: lista estruturada de interações encontradas
• unverified_pairs: pares não verificados por limite, timeout ou falha
• source_coverage: status por fonte consultada ou pulada
• analysis_metadata: metadados de versão, cache e geração
• warnings: lista de avisos importantes
• safety_notice: aviso de uso clínico seguro

Regras de status

• complete: todos os pares relevantes foram verificados e não houve pendências de fonte obrigatória.
• partial: houve limitação operacional, pendência de fonte ou unverified_pairs.
• failed: a análise não pôde ser concluída com segurança.

Resposta 200 (exemplo real)

Exemplo real de varfarina + aspirina (interação grave detectada pela base curada). A resposta é sempre o mesmo contrato, independentemente da rota (check, recheck, pharmacy/check).

{
  "analysis_status": "complete",
  "prescription_risk_level": "HIGH",
  "prescription_score": 82,
  "confidence_score": 0.9,
  "confidence_reason": "Análise completa com verificação em fontes primárias e supporting obrigatórias.",
  "clinical_relevance": "high",
  "recommendation_level": "monitor",
  "summary": "Análise completa com interações e cobertura obrigatória atendida.",
  "normalized_medications": [
    {
      "original_name": "varfarina",
      "normalized_name": "warfarin",
      "active_ingredient": "warfarin",
      "source": "inn_dictionary",
      "confidence": 0.72,
      "warnings": ["cmed_not_found_used_inn_fallback"]
    },
    {
      "original_name": "aspirina",
      "normalized_name": "aspirin",
      "active_ingredient": "aspirin",
      "source": "inn_dictionary",
      "confidence": 0.72,
      "warnings": ["cmed_not_found_used_inn_fallback"]
    }
  ],
  "interactions": [
    {
      "drug_pair": ["varfarina", "aspirina"],
      "severity": "GRAVE",
      "score": 82,
      "recommendation": "Evitar a combinação. Reavaliar a necessidade terapêutica e substituir por alternativa mais segura; se já em uso, monitorar de perto e encaminhar para revisão profissional imediata.",
      "summary": "Risco importante de sangramento pela associação de anticoagulante com antiagregante plaquetário.",
      "evidence": [
        {
          "source_name": "SauBit Safety Net",
          "source": "safety_net",
          "url": null,
          "retrieved_at": null,
          "title": "Base curada de interações críticas (conhecimento clínico consolidado)",
          "setid": null,
          "section": null,
          "pmid": null,
          "doi": null
        }
      ]
    }
  ],
  "unverified_pairs": [],
  "source_coverage": {
    "ddinter":   { "status": "success", "queried": true,  "role": "primary",         "items_found": 0, "pairs_checked": 1,    "pairs_with_evidence": 0, "pairs_failed": 0, "latency_ms": 76.6,  "error": null, "reason": null, "dataset_version": "unknown", "retrieved_at": "2026-06-27T12:49:01Z" },
    "openfda":   { "status": "success", "queried": true,  "role": "primary",         "items_found": 0, "pairs_checked": 1,    "pairs_with_evidence": 0, "pairs_failed": 0, "latency_ms": 760.7, "error": null, "reason": null, "dataset_version": "2026.05.07", "retrieved_at": "2026-06-27T12:49:01Z" },
    "dailymed":  { "status": "success", "queried": true,  "role": "primary",         "items_found": 0, "pairs_checked": 1,    "pairs_with_evidence": 0, "pairs_failed": 0, "latency_ms": 638.2, "error": null, "reason": null, "dataset_version": "2026.05.07", "retrieved_at": "2026-06-27T12:49:01Z" },
    "pubmed":    { "status": "success", "queried": true,  "role": "supporting",      "items_found": 2, "pairs_checked": 1,    "pairs_with_evidence": 1, "pairs_failed": 0, "latency_ms": 894.9, "error": null, "reason": null, "dataset_version": "2026.05.07", "retrieved_at": "2026-06-27T12:49:01Z" },
    "crfmg":     { "status": "success", "queried": true,  "role": "supporting",      "items_found": 0, "pairs_checked": null, "pairs_with_evidence": null, "pairs_failed": null, "latency_ms": 938.8, "error": null, "reason": null, "dataset_version": "2026.05.07", "retrieved_at": null },
    "cmed_anvisa": { "status": "success", "queried": true, "role": "normalization",  "items_found": 0, "pairs_checked": null, "pairs_with_evidence": null, "pairs_failed": null, "latency_ms": 64.8, "error": null, "reason": null, "dataset_version": "unknown", "retrieved_at": null },
    "admin_rag": { "status": "success", "queried": true,  "role": "local_knowledge", "items_found": 3, "pairs_checked": null, "pairs_with_evidence": null, "pairs_failed": null, "latency_ms": 3759.5, "error": null, "reason": null, "dataset_version": "saubit_admin_knowledge", "retrieved_at": "2026-06-27T12:49:04Z" }
  },
  "analysis_metadata": {
    "algorithm_version": "2026.05.07",
    "prompt_version": "2026.05.07",
    "model_name": "clinical_engine_v1",
    "generated_at": "2026-06-27T12:49:05Z",
    "cache_hit": false,
    "source_versions": {
      "clinical_engine_version": "2026.05.07",
      "rules_version": "2026.05.07",
      "drug_database_version": "unknown",
      "evidence_index_version": "2026.05.07",
      "prompt_version": "2026.05.07",
      "model_version": "unknown",
      "admin_rag_table": "saubit_admin_knowledge",
      "admin_rag_embedding_model": "text-embedding-3-large"
    },
    "source_config_version": "2026.06.27"
  },
  "warnings": ["Base interna do admin consultada com 3 trecho(s) relevante(s)."],
  "safety_notice": "Esta análise é apenas informativa e não substitui julgamento clínico, avaliação do paciente, exames ou consulta a especialista. Em caso de dúvida ou risco potencial, consulte um profissional habilitado.",
  "analysis_id": "f063a5cc-cbf8-4b26-ac0e-10ca1bf9c393",
  "cached": false,
  "processing_time_ms": 5.91,
  "timestamp": "2026-06-27T12:49:05Z"
}

Resposta 200 (sem interação)

Quando nenhum par conhecido é encontrado, interactions fica vazio e o risco é LOW/0:

{
  "analysis_status": "complete",
  "prescription_risk_level": "LOW",
  "prescription_score": 0,
  "confidence_score": 0.84,
  "clinical_relevance": "low",
  "recommendation_level": "no_known_interaction",
  "summary": "Análise completa sem interações conhecidas para os pares verificados.",
  "interactions": [],
  "unverified_pairs": [],
  "cached": false
}

Validações clínicas (clinical_alerts)

Além das interações fármaco-fármaco (interactions), a resposta inclui o array clinical_alerts com validações determinísticas adicionais que consideram o contexto do paciente (patient_record.conditions):

• Fármaco × Doença (type: "drug_disease"): contraindicações/cautelas por condição (ex.: AINE em insuficiência renal, IECA/BRA na gestação, betabloqueador em asma).
• Duplicidade terapêutica (type: "duplicate_therapy"): mesmo princípio ativo ou dois fármacos da mesma classe.
• Dose máxima (type: "max_dose"): dose diária estimada (dose_mg × frequência) acima do máximo recomendado.
• Fármaco × Alergia (type: "drug_allergy"): alergia conhecida do paciente ou possível reação cruzada (ex.: penicilina × cefalosporina) — usa patient_record.allergies.
• Ajuste renal (type: "renal_adjustment"): fármaco de eliminação renal com função reduzida (condição renal ou creatinine_clearance baixo).
• Ajuste hepático (type: "hepatic_adjustment"): fármaco hepatotóxico/metabolizado no fígado em disfunção hepática (hepatic_function ou condição hepática).
• Geriatria (type: "geriatric"): cautelas em idosos ≥65 anos (critérios de Beers) — usa patient_context.age.
• Pediatria (type: "pediatric"): contraindicações por faixa etária (ex.: AAS em menores de 12 anos — Reye) — usa patient_context.age.
• Gravidez/Lactação: além das condições, aceita os fatos pregnancy_status e breastfeeding_status (booleanos) do patient_context.
• Fármaco × Laboratório (type: "drug_lab"): K⁺ elevado + fármaco hipercalemiante, INR supraterapêutico + varfarina, QTc prolongado + fármaco que prolonga QT — usa patient_context.potassium / inr / qtc (ou patient_record.labs).
• Alimento/Álcool (type: "food_alcohol"): advertências por fármaco (metronidazol + álcool, estatina + suco de toranja, IMAO + tiramina).
• Compatibilidade IV (type: "iv_compatibility"): incompatibilidades de administração simultânea (ceftriaxona + cálcio, fenitoína + glicose).
• Medicamento controlado (type: "controlled_substance"): classificação ANVISA Portaria 344/98 (lista A1-C5), forma de receituário exigida e observações de dispensação — informativo, não eleva prescription_risk_level.
• Nomes/grafias semelhantes — LASA (type: "lasa_medication"): fármaco em uma lista curada de pares frequentemente confundidos (ex.: hidralazina × hidroxizina). Severidade MODERADO quando ambos os membros do par estão na mesma prescrição; LEVE (lembrete) quando só um está presente.
• Medicamento de alta vigilância (type: "high_alert_medication"): classes ISMP de maior risco de dano em caso de erro (anticoagulantes, insulinas, opioides, eletrólitos concentrados, bloqueadores neuromusculares, sedativos/vasopressores IV, quimioterápicos) — reforça a necessidade de dupla checagem, não eleva o risco calculado.
• Farmacogenética (type: "pharmacogenomic"): só dispara quando patient_context.genotype é enviado explicitamente (ex.: {"CYP2D6": "poor_metabolizer"}); cobre pares gene-fármaco citados pelo CPIC (CYP2D6×codeína/tramadol, CYP2C19×clopidogrel, CYP2C9/VKORC1×varfarina, TPMT×azatioprina). Nenhuma inferência de genótipo é feita — é puramente opt-in.
• Alerta de tarja preta (type: "black_box_warning"): boxed warning da FDA (openFDA), quando existente para o medicamento prescrito. Depende de fonte externa — sujeito às mesmas regras de timeout/indisponibilidade das demais fontes externas (ver source_coverage.black_box).

Transparência

Quando um dado não é informado, a resposta declara em warnings (prefixo ⓘ) qual validação não foi avaliada — ex.: "Ajuste renal não avaliado: função renal não informada", "Validações de pediatria/geriatria não avaliadas: idade não informada".

Esses alertas também elevam o prescription_risk_level quando graves/contraindicados.

"clinical_alerts": [
  {
    "type": "drug_disease",
    "severity": "GRAVE",
    "score": 82,
    "title": "AINE pode agravar a função renal (nefrotoxicidade e retenção hídrica).",
    "drugs": ["ibuprofeno"],
    "condition": "renal_impairment",
    "recommendation": "Evitar o uso nesta condição; considerar alternativa mais segura sob avaliação profissional.",
    "source": "clinical_validations"
  },
  {
    "type": "duplicate_therapy",
    "severity": "MODERADO",
    "score": 62,
    "title": "Possível duplicidade terapêutica: dois fármacos da mesma classe (AINE).",
    "drugs": ["ibuprofeno", "diclofenaco"],
    "condition": null,
    "recommendation": "Revisar a necessidade de dois agentes da mesma classe; risco de efeitos aditivos.",
    "source": "clinical_validations"
  }
]

Polifarmácia agregada (polypharmacy_risks)

Checar pares não basta: uma prescrição com muitos fármacos pode ter risco cumulativo mesmo que cada par isolado pareça apenas moderado. A resposta inclui polypharmacy_risks com as cargas agregadas sobre o conjunto completo (≥ 2 fármacos contribuintes):

polypharmacy_qt (prolongamento de QT) · polypharmacy_bleeding (risco hemorrágico) · polypharmacy_anticholinergic (carga anticolinérgica) · polypharmacy_cns_depression · polypharmacy_serotonergic · polypharmacy_nephrotoxic · polypharmacy_hyperkalemia · polypharmacy_fall (quedas/hipotensão).

Fatores do paciente (QTc, potássio, idade) elevam a gravidade e essas cargas também contribuem para o prescription_risk_level.

"polypharmacy_risks": [
  {
    "type": "polypharmacy_qt",
    "load": "qt",
    "severity": "GRAVE",
    "score": 82,
    "title": "Carga de prolongamento de QT: 3 fármacos contribuintes.",
    "contributing_medications": ["amiodarona", "ondansetrona", "haloperidol"],
    "patient_factors": { "qtc": 510, "potassium": 3.1 },
    "recommendation": "Reduzir o número de fármacos que prolongam o QT; monitorar ECG/QTc..."
  }
]

Governança de alertas (alert_governance)

Para combater a fadiga de alertas, a resposta inclui o bloco alert_governance, que registra quais alertas foram exibidos, quais foram suprimidos (e por quê) e quais exigem confirmação obrigatória. A supressão é uma decisão de apresentação — ela nunca rebaixa o prescription_risk_level: um alerta crítico suprimido da lista continua contando para o risco da prescrição.

Cada item de clinical_alerts passa a expor dois campos novos:

• id — identificador estável do alerta (independente da ordem dos fármacos), usado para suprimir/justificar alertas conhecidos.
• requires_confirmation — true quando o alerta exige confirmação explícita antes de prosseguir (por padrão, alertas CONTRAINDICADO).

Visões por papel (médico × farmacêutico)

Envie o header X-SauBit-Alert-View: medico ou X-SauBit-Alert-View: farmaceutico (também aceita ?alert_view=) para receber a visão adequada ao profissional. Na visão de farmacêutico, alertas focados em raciocínio diagnóstico (ex.: drug_disease) saem da lista visível (suppression_reason: "out_of_view"), mantendo os operacionais (alergia, duplicidade, dose máxima, compatibilidade IV, fármaco × lab). Alertas críticos são sempre exibidos, independentemente da visão.

Unidade hospitalar

A unidade de internação (UTI, pediatria, oncologia…) é inferida de patient_context.setting e permite regras específicas por unidade quando uma política está configurada (ver abaixo).

"alert_governance": {
  "applied": true,
  "policy_enabled": true,
  "view": "pharmacist",
  "unit": "icu",
  "min_severity": "MODERADO",
  "confirm_min_severity": "CONTRAINDICADO",
  "requires_confirmation": true,
  "confirmation_required_ids": ["drug_allergy-1a2b3c4d5e"],
  "total_alerts": 4,
  "visible_count": 2,
  "suppressed_count": 2,
  "suppressed": [
    {
      "type": "food_alcohol",
      "severity": "LEVE",
      "id": "food_alcohol-9f8e7d6c5b",
      "suppression_reason": "below_min_severity",
      "justification": ""
    }
  ]
}

Motivos de supressão (suppression_reason): below_min_severity, suppressed_type, policy_override (com justification) e out_of_view.

A política (nível mínimo de gravidade, tipos suprimidos, regras por unidade, visões e overrides justificados) é configurada por organização/API key via endpoints de administração — veja Governança de alertas.

Respostas de erro

HTTP	Exemplo de detail
401	API key required
403	API key inválida · IP não permitido para esta API key · Scope insuficiente para esta API key
422	lista de validação (campo obrigatório ausente, tipo inválido)
429	Rate limit excedido
504	A análise excedeu o tempo limite. Tente novamente em instantes.

// 401 — sem header X-API-Key
{ "detail": "API key required" }

// 422 — body sem "medications"
{
  "detail": [
    { "type": "missing", "loc": ["body", "medications"], "msg": "Field required", "input": { "language": "pt-BR" } }
  ]
}

Veja o catálogo completo em Respostas e Códigos de Erro.

Quando unverified_pairs aparece

• Limite de medicamentos excedido
• Limite de pares excedido
• Timeout de fonte
• Falha técnica de fonte
• Falha de normalização

Sempre que houver qualquer item em unverified_pairs, o status da resposta deve ser pelo menos partial.

Como funciona

• O endpoint usa um pipeline centralizado para REST e MCP.
• A resposta é fail-safe: falha técnica nunca deve degradar para risco artificialmente baixo.
• A cobertura por fonte fica explícita em source_coverage.
• Chamadas repetidas podem retornar cached: true.

Headers de diagnóstico

• X-SafeMed-Cache: HIT | MISS
• X-SafeMed-Agent-Mode: clinical_engine_v1
• X-SafeMed-Agent-Run: 0 | 1
• X-SafeMed-Processing-Time-Ms
• Server-Timing

Regras comerciais

• Cada chamada gera 1 transação faturável.
• A cobrança usa transaction_fee_brl da organização.

Cache inteligente

Quando a mesma combinação clínica for enviada, a API pode retornar cached: true e evitar novo custo de processamento.

Por política de segurança operacional, o reaproveitamento de cache prioriza respostas complete. Resultados partial ou failed podem ser recalculados em vez de reutilizados.

Campos dinâmicos como patient_record.patient_reference e patient_record.notes não entram na chave principal de cache. O cache prioriza conteúdo clínico, medicamentos e versões do algoritmo/configuração.