Boas práticas de integração

• Validar sempre status_code e tratar 429 (rate limit).
• Implementar retry com backoff exponencial para falhas de rede.
• Registrar analysis_id no contexto clínico do paciente para auditoria.
• Evitar logs com dados sensíveis de pacientes.
• Reaproveitar resultados quando o mesmo conjunto de medicamentos for repetido.

Idempotência (Idempotency-Key)

Para evitar análises/cobranças duplicadas em retentativas, envie o header Idempotency-Key (uma string única por requisição lógica, ex.: um UUID) nos endpoints POST: /interactions/check, /interactions/batch, /fhir/$check e /cds-services/{id}.

• Mesma chave + mesmo corpo → a resposta original é reexecutada do armazenamento (header de resposta Idempotent-Replayed: true); a análise não roda de novo.
• Mesma chave + corpo diferente → 409 Conflict (evita retornar o resultado errado).
• A chave vale por 24h e é isolada por organização.

Semântica transacional e faturamento

A resposta do check traz metadados para conciliação:

Campo	Significado
request_id	Correlaciona a requisição (também no header X-Request-Id).
replayed_request	true quando a resposta veio de um replay idempotente.
billing_status	charged (análise cobrada, inclusive cache hit) · replayed (replay idempotente, não cobra de novo).

Regras:

• Um replay idempotente (Idempotent-Replayed: true) não gera nova cobrança (billing_status: "replayed").
• Uma resposta de cache conta como análise (billing_status: "charged", cached: true).
• Respostas failed/partial mantêm o contrato fail-safe; trate analysis_status antes de usar.
• Consulte o estado de uma análise por id: GET /api/v1/analyses/{analysis_id}/status (status: complete | not_found), útil para reconciliação e retentativas.