Skip to main content

Events

The prescription widget communicates with your host app only via callbacks in the config — same contract as the pre-auth widget.

onReady​

Fires once after the widget is mounted and the initial resources (provider products, patient prefill, locale bundle) are loaded.

Signature: () => void

onStepChange​

Fires on every step transition. Steps:

  • resolve_patient
  • select_diagnoses
  • select_medications
  • review
  • consent_prompt (only fires when the provider is on v1.1 / v2)
  • issuing
  • outcome

Signature: (step: { name, index, total }) => void

onComplete​

Fires once, when the prescription is successfully issued. After this, no further step changes.

Signature: (outcome: PrescriptionOutcome) => void

Payload shape​

type PrescriptionOutcome = {
  prescription_id: string;         // Osigu internal UUID
  prescription_code: string;       // What the pharmacy will scan
  version: 'v1' | 'v1.1' | 'v2';   // Which endpoint was used
  status: 'PRESCRIPTION_ISSUED';
  issued_at: string;               // ISO 8601
  patient: {
    patient_id: string;
    first_name: string;
    last_name: string;
  };
  diagnoses: Array<{ diagnosis_code: string; description: string }>;
  medications: Array<{
    product_code: string;
    product_name: string;
    quantity: number;
    posology: string;
    duration_days?: number;
  }>;
  delivery: {
    channel: 'EMAIL' | 'LINK' | 'NONE';
    email?: string;                // If channel = EMAIL and delivery was attempted
    link_url?: string;             // If channel = LINK
    delivered: boolean;            // True if delivery attempt succeeded
  };
  duration_ms: number;
  telemetry_id?: string;
};

Handling the outcome​

onComplete: (outcome) => {
  persistPrescriptionMapping({
    localCaseId: myCaseId,
    osiguPrescriptionId: outcome.prescription_id,
    prescriptionCode: outcome.prescription_code,
  });

  if (outcome.delivery.channel === 'EMAIL' && !outcome.delivery.delivered) {
    showToast('Prescription issued but email delivery failed — patient can be re-sent from the details page.');
  } else if (outcome.delivery.channel === 'LINK') {
    copyToClipboard(outcome.delivery.link_url);
    showToast('Prescription link copied — share it with the patient.');
  }
}

onError​

Fires on unrecoverable errors. The widget stays mounted so the doctor can retry.

Signature: (err: PrescriptionError) => void

Payload shape​

type PrescriptionError = {
  code: string;             // Osigu error_code
  message: string;
  step: string;             // Which step raised it
  recoverable: boolean;
  cause?: unknown;
};

Common codes:

  • 071-104 — Medication not in the provider's registered products.
  • 071-301 — Diagnosis code not in the ICD-10 catalogue.
  • 071-302 — Patient-data-consent required (v1.1 / v2) but not confirmed.
  • 071-303 — v2 signed-hash validation failed (Spain repository).
  • WIDGET-NETWORK — HTTP failed after retries.
  • WIDGET-TOKEN — getToken returned invalid data or the token lacks ehr:write.

onClose​

Fires when the user closes the widget without issuing. Does not fire after onComplete.

Signature: () => void

Ordering guarantees​

  • onReady fires first, always.
  • onStepChange may fire multiple times, always after onReady.
  • Exactly one of onComplete / onError / onClose fires last. Terminal.