Awadoc
API Documentation

Pharmacy Provider Guide

For Businesses Integrating as Pharmacy Partners on AwaDoc

This guide reflects the exact live platform behaviour as of December 2025.

Your Role as a Pharmacy Provider

You receive prescription-based or over-the-counter medicine orders, confirm real-time stock & pricing, accept or reject the order, and keep the platform updated on preparation, dispatch, and delivery status.

Prerequisites (same for all partners)

  • Business Record status: ACTIVE
  • One or more APPROVED offerings in category pharmacy
  • testCallbackUrl & productionCallbackUrl configured by AwaDoc team
  • Test and/or Production API keys issued
  • Bank account verified (required for production keys)

Base URLs

Sandbox: https://partners-staging.awadoc.com/api-doc Production: https://partners-prod-001.awadoc.com/api-doc

Security

HMAC SHA256 signatures on every inbound and outbound payload (identical to Consultation guide). Clock skew tolerance: ±5 minutes.

Security: HMAC SHA256 Signatures

All communication is secured with HMAC SHA256 using your environment-specific secret.

From Platform → You (Inbound)

Header Value
X-Event-Id Unique event UUID
X-Timestamp Unix seconds
X-Signature HMAC_SHA256( sha256(body) + "\n" + timestamp, secret ) → hex
Content-Type application/json

From You → Platform (Outbound)

Endpoint:

POST /api/partners/:partnerId/callback
Header Value
x-timestamp Unix seconds
x-signature HMAC_SHA256( sha256(body) + "\n" + timestamp, secret ) → hex
Content-Type application/json

Clock skew allowed: ±5 minutes

Signature Generation (Node.js Example)

import crypto from "crypto";

function signPayload(body: any, secret: string, timestamp: number): string {
  const bodyHash = crypto
    .createHash("sha256")
    .update(JSON.stringify(body))
    .digest("hex");
  const canonical = `${bodyHash}\n${timestamp}`;
  return crypto.createHmac("sha256", secret).update(canonical).digest("hex");
}

Complete Pharmacy Flow & Events You Will Receive

Step Event Type When It Is Sent Response Time Expected Required Response Fields (exact JSON)
1 pharmacy.availability.query User uploads prescription or searches medicines ≤ 10 seconds See below
2 pharmacy.order.requested User proceeds to checkout and selects your pharmacy ≤ 30 seconds Confirm or reject with pricing
3 pharmacy.order.confirmed Payment succeeds on AwaDoc side ≤ 10 seconds Simple acknowledgement

1. pharmacy.availability.query

Payload example (platform → you)

JSON

{
  "event_id": "evt-1001",
  "event_type": "pharmacy.availability.query",
  "timestamp": "2025-12-09T11:20:00Z",
  "context": {
    "query_id": "phq-8871",
    "items": [
      { "drug_name": "Amoxicillin 500mg Caps", "quantity": 30 },
      { "drug_name": "Paracetamol 500mg Tabs", "quantity": 20 }
    ],
    "delivery_mode": "home_delivery",
    "service_area": "Lagos",  // or "ALL"
       // service_area or address
    "address":  {
       "country":"Nigeria",
       "state": "Lagos",
       "city": "Ikeja"
     }
  }
}

Your response (you → platform)

JSON

{
  "status": "available", // or "unavailable"
  "query_id": "phq-8871",
  "queried_at": "2025-12-09T11:20:08Z",
  "items": [
    {
      "drug_name": "Amoxicillin 500mg Caps",
      "available": true,
      "drug_id": "drug_001",
      "substitutable": true,
      "pricing": { "amount": 4500.0, "currency": "NGN" }
    },
    {
      "drug_name": "Paracetamol 500mg Tabs",
      "drug_id": "drug_001",
      "available": false,
      "reason": "out_of_stock"
    }
  ],
  "delivery_modes": ["home_delivery", "pickup"],
  "total_pricing": { "amount": 4500.0, "currency": "NGN" },
  "estimated_delivery_time": "2025-12-09T15:00:00Z"
}

2. pharmacy.order.requested

Sent when the user chooses your pharmacy and clicks “Place Order”.
Payload (Platform → Pharmacy)

{
  "event": "pharmacy.order.requested",
  "order_id": "ord_92hd73ks",
  "user": {
    "id": "usr_8829",
    "name": "John Doe",
    "phone": "+2348012345678"
  },
  "context": {
    "items": [
      {
        "drug_id": "drug_001",
        "name": "Amoxicillin 500mg",
        "quantity": 2,
        "requires_prescription": true
      }
    ],
    "delivery": {
      "type": "home_delivery",
      "address": {
         "country":"NG",
         "state": "Lagos",
         "city": "Ikeja",
         "street":"12 Admiralty Way, Lekki, Lagos"
      }
    },
    "currency": "NGN"
  }
}

Your response (you → platform)
Your response (MUST include final pricing)

JSON

{
  "status": "confirmed",                 // or "rejected"
  "order_id": "ord-9923",
  "confirmed_at": "2025-12-09T11:25:15Z",
  "total_pricing": { "amount": 5200.00, "currency": "NGN" },
  "breakdown": {
    "items": [
      {
        "drug_id": "drug_001",
        "name": "Amoxicillin 500mg",
        "quantity": 2,
        "unit_price": 2250.00,
        "total_price": 4500.00,
      }
    ],
    "subtotal": 4500.00,
    "delivery_fee": 700.00,
    "tax": 0.00
  },
  "delivery_mode": "home_delivery",
  "delivery_address":"12 Admiralty Way, Lekki, Lagos, Ikeja, Lagos, NG",
  "estimated_delivery_time": "2025-12-09T15:30:00Z",
  "notes": "Generic substitute used for Amoxicillin"
}

If rejected:

JSON

{
  "status": "rejected",
  "reason": "out_of_stock",
  "alternative_pharmacies_suggested": true
}

3. pharmacy.order.confirmed
When it is sent
Sent after successful payment on AwaDoc’s side.

Expectation
You only need to acknowledge receipt. No pricing or business logic here

Payload (Platform → Pharmacy)

{
  "event": "pharmacy.order.confirmed",
  "order_id": "ord_92hd73ks",
  "context": {
    "payment": {
      "status": "successful",
      "method": "bank_transfer",
      "amount": 5300,
      "currency": "NGN"
    }
  },
  "confirmed_at": "2025-12-14T10:42:11Z"
}

Your response (you → platform)
Your response (simple ack)

JSON

{
  "status": "acknowledged",
  "acknowledged_at": "2025-12-09T11:27:00Z"
}

Events You Must Send Back (Callbacks)

POST to https://partners-{env}.awadoc.com/api/partners/:partnerId/callback

Event Type When to Send Important Fields
pharmacy.order.preparing Order accepted & pharmacist starts preparation order_id, estimated_ready_time
pharmacy.order.dispatched Rider or delivery agent leaves pharmacy order_id, tracking_url (optional), rider_name, rider_phone
pharmacy.order.delivered Medicines handed to patient / recipient order_id, delivered_at, recipient_name, proof_of_delivery_url (optional)
pharmacy.order.failed Delivery failed (wrong address, etc.) order_id, reason
pharmacy.order.cancelled You or patient cancels before dispatch order_id, reason

Example delivered callback

JSON

{
  "event_id": "evt-3009",
  "event_type": "pharmacy.order.delivered",
  "timestamp": "2025-12-09T15:12:00Z",
  "context": {
    "order_id": "ord-9923",
    "status": "delivered",
    "delivered_at": "2025-12-09T15:10:00Z",
    "recipient": "Chioma Okafor",
    "proof_of_delivery_url": "https://storage.awadoc.com/pod/ord-9923.jpg"
  }
}

Key Notes & Gotchas

  • Field name is exactly "currency" (not "curency")
  • Always return total_pricing in order.requested response — platform will reject if missing
  • Use ISO8601 UTC for all timestamps
  • Respond <10s to availability queries, <30s to order requests
  • No callback URL set → you are completely skipped in searches and bookings
  • For prescription-only drugs, you may add "requires_prescription": true in availability response

You’re now fully equipped to receive and fulfil pharmacy orders on AwaDoc! 💊🚚