CDS Hooks

Integrate SauBit into the EHR prescribing workflow via CDS Hooks: when prescribing, the EHR calls the service and shows alert cards (interactions, contraindications, clinical alerts) at the point of decision.

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

Discovery

GET /api/v1/cds-services (no authentication, per the spec). Returns the available services:

{
  "services": [
    {
      "hook": "medication-prescribe",
      "title": "SauBit — análise de segurança da prescrição",
      "description": "Verifica interações, contraindicações e alertas clínicos da prescrição.",
      "id": "saubit-medication-safety"
    },
    {
      "hook": "order-select",
      "title": "SauBit — análise de segurança ao selecionar o pedido",
      "id": "saubit-order-select"
    }
  ]
}

Configure the base URL https://api.saubit.com.br/api/v1 in the EHR.

Invocation

POST /api/v1/cds-services/{service_id} (API key auth, scope interactions:check).

The body is a CDS Hooks request. Medications come from context.medications (a FHIR Bundle of MedicationRequest) or context.draftOrders; conditions, allergies, observations and the Patient arrive via prefetch.

curl -X POST https://api.saubit.com.br/api/v1/cds-services/saubit-medication-safety \
  -H "X-API-Key: sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "hookInstance": "d1577c69-...",
    "hook": "medication-prescribe",
    "context": {
      "patientId": "Patient/123",
      "medications": {
        "resourceType": "Bundle",
        "entry": [
          { "resource": { "resourceType": "MedicationRequest", "status": "active",
            "medicationCodeableConcept": { "text": "Ibuprofeno" } } },
          { "resource": { "resourceType": "MedicationRequest", "status": "active",
            "medicationCodeableConcept": { "text": "Naproxeno" } } }
        ]
      }
    },
    "prefetch": {
      "conditions": { "resourceType": "Bundle", "entry": [
        { "resource": { "resourceType": "Condition", "code": { "text": "Insuficiência renal" } } }
      ] }
    }
  }'

Response (cards)

{
  "cards": [
    {
      "summary": "Interação GRAVE: Ibuprofeno + Naproxeno",
      "indicator": "critical",
      "detail": "Revisar a necessidade de dois AINEs; risco de efeitos aditivos.",
      "source": { "label": "SauBit", "url": "https://saubit.com.br" }
    }
  ]
}

Severity → indicator mapping: CONTRAINDICADO/GRAVE → critical, MODERADO → warning, LEVE → info. When there are no findings, a single reassuring info card is returned. With no analyzable medication in the context, it returns {"cards": []} (a valid CDS Hooks response).

Each card carries a uuid (analysis_id|alert_id) so feedback can reference the alert.

Feedback (closing the loop)

POST /api/v1/cds-services/{service_id}/feedback (API key) — record whether the clinician accepted or overrode the alert. Feeds the "alerts that changed conduct" metric. The actor role comes from identity (the role bound to the API key), not from a header.

{
  "feedback": [
    {
      "card": "a1b2c3|drug_disease-1a2b3c4d5e",
      "outcome": "overridden",
      "overrideReasons": [ { "reason": { "code": "benefit", "display": "Benefit outweighs risk" } } ]
    }
  ]
}

outcome: accepted (→ acknowledged) or overridden. Response: { "recorded": n }.

The analysis is the same as /interactions/check and the FHIR integration — same clinical rules and fail-safe policy.