Skip to main content

Ghasi e-Prescribing Gateway Service — Sync Contract

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

Per-Aggregate Conflict Policy​

AggregatePolicyRationale
PrescriptionRecord (MedicationRequest)server_authoritative + ETagClinical safety: concurrent modifications to a prescription must be surfaced to the prescriber. Gateway returns 412 Precondition Failed on stale ETag. No silent merge.
DispenseRecord (MedicationDispense)server_authoritative + ETagDispense records are immutable after creation; updates require ETag. Partial fill changes must be explicit.
SubscriptionChannelserver_authoritativeSubscription channel config is fully replaced on update. No partial patch.
WorkflowTaskserver_authoritative + ETagTask status must be reconciled explicitly; no silent overwrite of renewal/clarification state.
IdempotencyRecordappend_onlyIdempotency records are written once on create; never updated. Lookups only.

ETag Concurrency Detail​

  1. Gateway issues ETag: W/"<sha256-of-fhir-resource>" on every GET and POST-create response.
  2. PUT or status-changing PATCH must include If-Match: W/"<etag>".
  3. Mismatch returns 412 Precondition Failed; response body contains current resource for client diff.
  4. Client MUST refresh (GET), perform diff, and resubmit.
  5. There is NO automatic merge of concurrent edits. Clinical safety requires explicit clinician review.

Idempotency (create deduplication)​

  • Idempotency-Key header on POST prevents duplicate resources on network retry.
  • Same key + same payload fingerprint: gateway returns 201 with original resource (no new DB row).
  • Same key + different payload: gateway returns 409 IDEMPOTENCY_KEY_CONFLICT — client must use a new key.
  • Idempotency records expire after 24 hours (configurable per tenant).

Offline Client Guidance​

  1. Clients (EHR, Pharmacy backends) MUST cache ETag on every resource fetch.
  2. On reconnect after offline period, GET fresh resource + ETag before any mutation.
  3. Use Idempotency-Key (UUID per create operation) to handle network retries safely.
  4. On 412: surface conflict to user; DO NOT retry with same payload.
  5. On 429: implement exponential backoff with jitter per tenant fair-use policy.

NATS Consumer Idempotency​

Downstream consumers (pharmacy-service, orders-service) MUST deduplicate incoming NATS events by data.prescriptionBusinessId (or data.medicationRequestId) + data.etag. Duplicate delivery of the same event MUST NOT cause duplicate clinical side effects (BR-RX-003).