POST /api/v1/interactions/check

Envie uma prescricao com medicamentos e, opcionalmente, contexto clinico do paciente para receber uma analise estruturada com contrato estavel, rastreabilidade de fontes e politica fail-safe.

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

dica

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

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 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 confianca
• clinical_relevance: high | moderate | low | unknown
• recommendation_level: avoid_combination | monitor | adjust_dose | consult_professional | no_known_interaction | unknown
• normalized_medications: medicamentos considerados na analise
• interactions: lista estruturada de interacoes encontradas
• unverified_pairs: pares nao verificados por limite, timeout ou falha
• source_coverage: status por fonte consultada ou pulada
• analysis_metadata: metadados de versao, cache e geracao
• warnings: lista de avisos importantes
• safety_notice: aviso de uso clinico seguro

Regras De Status

• complete: todos os pares relevantes foram verificados e nao houve pendencias de fonte obrigatoria.
• partial: houve limitacao operacional, pendencia de fonte ou unverified_pairs.
• failed: a analise nao pode ser concluida com seguranca.

Resposta 200

{
  "analysis_id": "uuid",
  "timestamp": "2026-04-28T12:34:56Z",
  "analysis_status": "partial",
  "prescription_risk_level": "UNKNOWN",
  "prescription_score": null,
  "confidence_score": 0.6,
  "confidence_reason": "Analise parcial baseada na base local; fontes externas primarias nao foram consultadas.",
  "clinical_relevance": "moderate",
  "recommendation_level": "monitor",
  "summary": "Analise parcial baseada na base local. Fontes externas primarias nao foram consultadas; revisao profissional recomendada.",
  "normalized_medications": [
    {
      "original_name": "Warfarina",
      "normalized_name": null,
      "active_ingredient": null,
      "source": "input",
      "confidence": 1.0,
      "warnings": []
    },
    {
      "original_name": "Omeprazol",
      "normalized_name": null,
      "active_ingredient": null,
      "source": "input",
      "confidence": 1.0,
      "warnings": []
    }
  ],
  "interactions": [
    {
      "drug_pair": ["Warfarina", "Omeprazol"],
      "severity": "MODERADO",
      "score": 62,
      "recommendation": "Requer avaliacao conforme contexto clinico. Considerar monitoramento e consulta a protocolo institucional.",
      "summary": "Mecanismo nao detalhado na base local.",
      "evidence": [
        {
          "source_name": "DDInter",
          "source": "ddinter",
          "url": null,
          "retrieved_at": null,
          "title": "DDInter Warfarina x Omeprazol (MODERADO)",
          "setid": null,
          "section": null,
          "pmid": null,
          "doi": null
        }
      ]
    }
  ],
  "unverified_pairs": [],
  "source_coverage": {
    "ddinter": {
      "status": "success",
      "queried": true,
      "role": "primary",
      "items_found": 1,
      "pairs_checked": 1,
      "pairs_with_evidence": 1,
      "pairs_failed": 0,
      "latency_ms": 42.1,
      "error": null,
      "reason": null,
      "dataset_version": "unknown",
      "retrieved_at": "2026-04-28T12:34:56Z"
    },
    "openfda": {
      "status": "skipped",
      "queried": false,
      "role": "primary",
      "reason": "not_implemented"
    },
    "dailymed": {
      "status": "skipped",
      "queried": false,
      "role": "primary",
      "reason": "not_implemented"
    },
    "pubmed": {
      "status": "skipped",
      "queried": false,
      "role": "supporting",
      "reason": "not_implemented"
    },
    "crfmg": {
      "status": "skipped",
      "queried": false,
      "role": "supporting",
      "reason": "not_implemented"
    },
    "cmed_anvisa": {
      "status": "skipped",
      "queried": false,
      "role": "normalization",
      "reason": "not_implemented"
    }
  },
  "analysis_metadata": {
    "algorithm_version": "2026.05.07",
    "prompt_version": "2026.05.07",
    "model_name": "clinical_engine_v1",
    "generated_at": "2026-04-28T12:34:56Z",
    "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"
    }
  },
  "warnings": [
    "Fontes externas primarias (openfda, dailymed) nao foram consultadas nesta execucao."
  ],
  "safety_notice": "Esta analise e apenas informativa e nao substitui julgamento clinico, avaliacao do paciente, exames ou consulta a especialista. Em caso de duvida ou risco potencial, consulte um profissional habilitado. A analise foi limitada e requer revisao humana.",
  "cached": false,
  "processing_time_ms": 842.3
}

Quando unverified_pairs aparece

• Limite de medicamentos excedido
• Limite de pares excedido
• Timeout de fonte
• Falha tecnica de fonte
• Falha de normalizacao

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 e fail-safe: falha tecnica nunca deve degradar para risco artificialmente baixo.
• A cobertura por fonte fica explicita em source_coverage.
• Chamadas repetidas podem retornar cached: true.

Headers De Diagnostico

• 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 transacao faturavel.
• A cobranca usa transaction_fee_brl da organizacao.

Cache Inteligente

Quando a mesma combinacao clinica for enviada, a API pode retornar cached: true e evitar novo custo de processamento.

Campos dinamicos como patient_record.patient_reference e patient_record.notes nao entram na chave principal de cache. O cache prioriza conteudo clinico, medicamentos e versoes do algoritmo/configuracao.