MedsGH Developers
v0.1 · draft

For provider engineering teams

Logistics Provider Standard

Four calls on your API, one key you issue us, and signed status events you POST to the per-job URL we hand you. Same contract for every provider.

Base URL
{provider_base}
Auth
provider-issued key
Callbacks
signed, per-job URL
Stable
quote · book · callbacks
About the pathsPaths on your side (/rates, /jobs…) show the shape of the standard. If your API names things differently, our adapter maps them. Cancel windows may tighten while the standard is in draft.

Credentials come from you

You issue a sandbox key and a production key. They're separate and never interchangeable. We attach your key to every call, in the header you name at onboarding.

We ping first. A 200 means everything below will work.

Status callbacks go the other way (you → MedsGH) to the per-job callback_url in every job packet. That URL is our endpoint and already carries an unguessable tok query parameter. Each callback is also signed with HMAC-SHA256 using the signing secret we agree at onboarding.

Key check
POST{provider_base}/ping
What you send us at onboarding
// you issue these; we plug them in and ping
"base_url":       "https://sandbox.<your-domain>",
"api_key":        "<key-we-attach-to-every-call>",
"auth_header":    "Client-Api-Key (or yours, just name it)",
"signing_secret": "<shared-secret-for-callback-HMAC>"

The four calls

MedsGHYou (provider)
1GET rates

Price it. Returns a quote_reference that locks the price.

2POST jobs

Hand it over. Idempotent on Idempotency-Key.

3Status callbacks

You POST signed events to the job's callback_url.

4Cancel

Before pickup only.

Get rates

Price a trip before committing. We send you the pickup and dropoff coordinates, parcel weight, dimensions and value, and the slot. You return one number.

The quote_reference you return is passed back verbatim at booking. It locks the price so neither side reprices mid-job. Recommended timeout: 10s.

Parcel units are kg, metres and GHS. If your API takes other units, say so at onboarding and the adapter converts.

Request
GET/rates?pickup_lat=…&pickup_lng=…&dropoff_lat=…&dropoff_lng=…&weight_kg=…&service=standard
Response · 200
{
  "quote_reference": "Q-2PT-88121",
  "amount": 25.00, "currency": "GHS",
  "expires_at": "2026-09-13T12:00:00Z",
  "breakdown": { "base": 10, "distance": 9, "weight": 2, "priority": 0, "tax": 4 }
}

Post a job

Hand over the full job packet. Retries reuse the same Idempotency-Key. Duplicates return the original booking (201 with an identical reference), never a second job.

IdempotencyThe header and the idempotency_key field carry the same value: req_{request_id}_pharm_{pharmacy_id}.
Identifiersjob_id (MG-{request}-P{pharmacy}) is our identity for the job and is what appears in the callback URL and callback body. The idempotency key is only for deduplicating your bookings.
Optional fieldsSome fields (service.zone, pickup.ready_at, fragile, cold_chain) are optional and may be absent. Don't require them.
Request
POST/jobsIdempotency-Key: req_1042_pharm_17
Body · the job packet
{
  "job_id": "MG-1042-P17",
  "idempotency_key": "req_1042_pharm_17",
  "quote_reference": "Q-2PT-88121",
  "distance_km": 7.4,
  "service": { "level": "standard", "insurance": false, "date": "2026-09-13", "time": "10:15" },
  "pickup": {
    "pharmacy_id": 17, "name": "Aseda Pharmacy",
    "address": "12 Oxford Street, Osu",
    "latitude": 5.5556, "longitude": -0.1833,
    "contact": "0244123456"
  },
  "dropoff": {
    "address": "14 Mango Road, East Legon",
    "latitude": 5.6380, "longitude": -0.1720,
    "receiver_name": "Ama Serwaa", "receiver_phone": "0551234567",
    "note": "Call on arrival."
  },
  "package": {
    "description": "Sealed pharmacy parcel", "type": "parcel",
    "weight_kg": 0.8,
    "length_m": 0.20, "width_m": 0.15, "height_m": 0.10,
    "value": 145.50
  },
  "metadata": {},
  "callback_url": "https://api.medsgh.com/api/webhooks/provider/jobs/MG-1042-P17/status?tok=<token>"
}
Response · 201
{ "provider_reference": "uuu24Rres", "status": "accepted", "accepted_at": "2026-09-13T10:16:02Z" }

Status callbacks

You POST to us. Every job packet carries a callback_url, our endpoint minted for that job. Post each status change to it with four headers:

  • X-Provider-Id: the provider id we gave you
  • X-Provider-Signature: lowercase hex HMAC-SHA256 of the JSON body
  • X-Event-Id: a unique id per event (we dedupe on it)
  • X-Event-At: ISO timestamp, within ±10 minutes of our clock

No callback yet? We poll your tracking endpoint as a fallback.

Proof ruledelivered needs proof.otp_verified: true or a proof.photo_url. Unrecognised statuses are rejected with 422 UNKNOWN_STATUS and logged, never guessed.
Rejected events consume their event idIf we reject an event with 422, its X-Event-Id is already recorded. Fix the payload and resend it with a new event id. Reusing the old one returns 200 {"deduped": true} and nothing is applied.
Signing detailsWe compare against JSON.stringify of the parsed body. Send compact JSON, keep key order stable, and avoid numbers that re-serialize differently (like 1.0). The body is validated strictly: unknown fields get 400 BAD_PAYLOAD, and job_id must match the URL.

Try these rules in the callback simulator →

Request · to our callback_url
POST{callback_url}
Event payload
{
  "job_id": "MG-1042-P17", "provider_reference": "uuu24Rres",
  "status": "in_transit", "at": "2026-09-13T11:02:00Z",
  "rider": { "name": "Kwame M.", "phone": "0559876543", "plate": "GS-4410-22" },
  "proof": { "otp_verified": false }
}
Signing it (Node.js)
const body = JSON.stringify(event);
const sig  = crypto.createHmac('sha256', SIGNING_SECRET)
                   .update(body).digest('hex');

await fetch(callbackUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Provider-Id': PROVIDER_ID,
    'X-Provider-Signature': sig,
    'X-Event-Id': crypto.randomUUID(),
    'X-Event-At': new Date().toISOString(),
  },
  body,
});

The six words

StatusMeaningTriggers on our side
acceptedJob takenAssigned; pharmacy and customer notified
picked_upCollected from pharmacyCustomer tracking updates
in_transitOn the wayCustomer tracking updates
deliveredHanded over + proofPayout triggered; order completed
failedNot deliverable + reasonJob re-offered; pharmacy notified
cancelledStood down pre-pickupJob returned to pool

What our endpoint answers

HTTPCode / flagWhen
200—Applied.
200deduped: trueWe've already seen this X-Event-Id. Nothing changed.
200stale: trueThe job is already finished (delivered, failed or cancelled) and this event says something different. Acknowledged, ignored.
400BAD_SIGNATUREWrong tok or wrong signature.
400BAD_PAYLOADMissing X-Event-Id, unknown fields, or job_id doesn't match the URL.
403FORBIDDEN_JOBThe job belongs to a different provider.
404UNKNOWN_JOBNo such job.
409STALE_EVENTX-Event-At is outside the ±10 minute window.
422UNKNOWN_STATUSNot one of the six words.
422PROOF_REQUIREDdelivered without OTP or photo.

Failures look like { "success": false, "code": "…", "message": "…" }.

Cancel

Valid before pickup only. Post-pickup cancellations return 409 TOO_LATE_TO_CANCEL. End the job as failed with a reason instead.

Request
POST/jobs/:id/cancel{ "reason": "customer_requested" }

Wallet

We read your balance endpoint for accrued amounts, and you confirm transfers via callbacks to us. Reconcile daily and report mismatches with job ids attached.

Request
GET/wallet/balance

Timeouts and retries

CallTimeoutRetries
rates10sNo retry. A fresh quote on the next open is cheaper than a stale one.
create job15s3 attempts, backoff 1s → 2s → 4s, same idempotency key.
track10sOn demand. Callbacks are the live channel; track is the fallback.
cancel10sIdempotent by reference, so it's safe to re-send.
Timeout ≠ rejectionA timeout means “unknown”. Verify with track before acting, and never assume the job was or wasn't created.

Error contract (your API)

Failures from your API return { code, message }. These are the codes we expect from you. The codes our callback endpoint returns are listed under Status callbacks.

CodeHTTPWhen
INVALID_QUOTE422Quote reference missing, expired or mismatched
UNKNOWN_REFERENCE404Booking reference not found
TOO_LATE_TO_CANCEL409Cancel attempted after pickup
NO_COVERAGE422Zone not served
PROVIDER_DOWN502Upstream unreachable after retries

Go-live checklist