POST /api/v1/interactions/compare

Compara 2 a 5 medicamentos candidatos contra o mesmo contexto de paciente, para apoiar a escolha entre alternativas terapêuticas (ex.: "qual é mais seguro para este paciente: A ou B?").

Cada candidato é avaliado isoladamente, como se fosse adicionado à lista de patient_record.current_medications — o mesmo motor determinístico do /interactions/check, uma análise completa por candidato. Cada candidato conta como uma análise faturável independente (mesmo comportamento de /interactions/batch).

O que este endpoint NÃO faz

Não avalia interação entre os próprios candidatos — eles não seriam prescritos juntos. Cada candidato é comparado contra o regime atual do paciente, não entre si.

Headers

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

Body

{
  "candidates": ["Ibuprofeno", "Paracetamol"],
  "patient_record": {
    "current_medications": [{"name": "Varfarina"}],
    "conditions": ["fibrilacao atrial"]
  },
  "include_mild": true,
  "language": "pt-BR"
}

Campo	Obrigatório	Descrição
candidates	Sim	2 a 5 nomes de medicamentos, sem duplicatas.
patient_record	Não	Mesmo schema de /interactions/check — current_medications é usado como base para cada candidato.
patient_context	Não	Mesmo schema de /interactions/check.
include_mild	Não (default true)	Inclui alertas LEVE na análise de cada candidato.
language	Não (default pt-BR)

Resposta 200

{
  "candidates_evaluated": ["Ibuprofeno", "Paracetamol"],
  "comparisons": [
    {
      "candidate": "Ibuprofeno",
      "analysis_id": "uuid-1",
      "prescription_risk_level": "HIGH",
      "prescription_score": 82,
      "interactions_count": 0,
      "clinical_alerts_count": 1,
      "top_alerts": ["AINE aumenta o risco de sangramento gastrointestinal."],
      "summary": "Análise completa com interações e cobertura obrigatória atendida."
    },
    {
      "candidate": "Paracetamol",
      "analysis_id": "uuid-2",
      "prescription_risk_level": "LOW",
      "prescription_score": 0,
      "interactions_count": 0,
      "clinical_alerts_count": 0,
      "top_alerts": [],
      "summary": "Análise completa sem interações conhecidas para os pares verificados."
    }
  ],
  "safer_candidate": "Paracetamol",
  "recommendation": "Paracetamol apresentou o menor risco relativo (LOW) para este paciente entre os candidatos avaliados. Revisão profissional é obrigatória antes de qualquer decisão terapêutica.",
  "safety_notice": "Esta comparação é apoio à decisão, não substitui julgamento clínico. ..."
}

analysis_id de cada candidato pode ser usado depois em /interactions/recheck, /interactions/alerts/decision, /chat/message (analysis_id) e /analyses/{analysis_id}, exatamente como qualquer outra análise.

Observações

• Scope exigido: interactions:check (mesmo de /interactions/check).
• safer_candidate só é preenchido quando há diferença clara de risco entre os candidatos; em empate, vem null e a recomendação orienta considerar outros fatores clínicos.
• Cada chamada interna usa processing_options.context_mode = "stateless" — o comparador nunca atualiza o Contexto Clínico persistente do paciente, mesmo que a política da organização permita persistência.

Outras respostas de erro

HTTP	detail
401	API key required
403	Scope insuficiente para esta API key
422	menos de 2 candidatos, candidatos duplicados, ou lista com mais de 5
429	Rate limit excedido
504	Algum candidato excedeu o tempo limite de análise.

Catálogo completo: Respostas e Códigos de Erro.