Webnify Ship API (v1)

Apni website / admin panel se seedha courier rate dekho aur parcel book karo. JSON in, JSON out.

API key

Settings → API keys → "Nayi key". Key sirf ek baar dikhti hai — copy karke apne server ke env me rakho (browser me kabhi nahi). Har request me header bhejo:

Authorization: Bearer ws_live_xxxxxxxx

Key band karni ho to Settings me "Band karo". Galat/band key → 401 UNAUTHORIZED.

1. Rates — POST /api/v1/rates

Body: delivery_pincode (zaroori), weight_grams, payment_mode (prepaid | cod), cod_amount (COD me zaroori, ₹), optional pickup_pincode / pickup_location (pickup address ka naam ya id; default = default pickup), dims {length_cm, breadth_cm, height_cm}.

curl -X POST https://webnify-ship.vercel.app/api/v1/rates \
  -H "Authorization: Bearer ws_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_pincode": "110034",
    "weight_grams": 500,
    "payment_mode": "cod",
    "cod_amount": 499,
    "dims": { "length_cm": 20, "breadth_cm": 15, "height_cm": 8 }
  }'

price = seller jo dega (Webnify fee shamil) — wahi jo app me dikhta hai. Rupees me.

{
  "ok": true,
  "pickup": { "pincode": "125049", "label": "Baill ji store", "id": "…" },
  "zone": "C", "charge_weight_grams": 500, "payment_mode": "cod",
  "rates": [
    { "courier": "delhivery", "courier_name": "Delhivery Surface", "price": 112.5,
      "breakdown": { "freight": 70.5, "cod_fee": 35, "webnify_fee": 7 },
      "eta_days": 4, "live": true, "best_rate": true, "fastest": false, "recommended": true }
  ],
  "unavailable": [ { "courier": "delhivery_express", "courier_name": "Delhivery Express", "reason": "…" } ]
}

2. Book — POST /api/v1/shipments

Wahi booking jo app karta hai: wallet se paisa katta hai → courier pe booking → courier mana kare to paisa turant wapas. courier rates wala code (delhivery = Surface, delhivery_express = Express; jab ON hon: ekart, xpressbees); na bhejo to seller ka auto rule. courier diya aur wo available nahi to error (fallback nahi). max_charge (optional) se zyada rate hua to booking nahi hogi (409 PRICE_CHANGED).

Idempotent: same order_ref dobara bhejo to naya parcel nahi banta — pehle wala shipment duplicate: true ke saath aata hai (cancelled ho to naya ban sakta hai).

curl -X POST https://webnify-ship.vercel.app/api/v1/shipments \
  -H "Authorization: Bearer ws_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ref": "BJ-1001",
    "customer": {
      "name": "Rakesh Kumar", "phone": "9876543210",
      "house": "House 12", "area": "Gandhi Nagar", "landmark": "Shiv Mandir",
      "city": "Delhi", "state": "Delhi", "pincode": "110034"
    },
    "items": [ { "name": "Kesh Amrit Hair Oil 200 ml", "qty": 2 } ],
    "weight_grams": 500,
    "payment_mode": "cod", "cod_amount": 499,
    "courier": "delhivery",
    "max_charge": 112.5
  }'

201 {
  "ok": true, "duplicate": false,
  "shipment": {
    "id": "…", "order_ref": "BJ-1001", "order_no": "WS-000012", "awb": "1234567890123",
    "courier": "delhivery", "courier_name": "Delhivery Surface", "status": "BOOKED", "status_label": "Pickup baaki",
    "charged_amount": 112.5, "payment_mode": "cod", "cod_amount": 499, "eta_days": 4,
    "label_url": "https://webnify-ship.vercel.app/api/v1/shipments/…/label",
    "tracking_url": "https://webnify-ship.vercel.app/track?awb=1234567890123"
  }
}

3. Status + tracking

GET /api/v1/shipments/:id (id, AWB ya order_ref) ya GET /api/v1/shipments?order_ref=BJ-1001 → shipment + events [{status, title, location, at}] (Delhivery ke live scans).

4. Label PDF

GET /api/v1/shipments/:id/label (same Bearer header) → PDF (live Delhivery parcel pe Delhivery ka apna label).

5. API Orders (check karke push) — POST /api/v1/orders

Order seedha book nahi hota — Webnify Ship ke API Orders section me aata hai. Seller wahan address / wazan / COD check (aur edit) karta hai, live rate dekhta hai, phir Push to Courier dabata hai. Body bilkul /api/v1/shipments jaisi, plus callback_url (https). Same order_ref dobara bhejo to pending order update hota hai; book ho chuka ho to wahi wapas aata hai. Kuch charge nahi hota jab tak Push to Courier na dabe.

Booking (ya cancel) hote hi Webnify callback_url pe POST karta hai: { event: "shipment.booked", order_ref, api_order_id, status, awb, courier }. Is ping pe bharosa mat karo — usse sirf signal maano aur GET /api/v1/orders/:order_ref (apni key ke saath) se asli data lo: { status: PENDING|BOOKED|CANCELLED, review_url, shipment: { awb, courier, courier_name, status, label_url, tracking_url, delhivery_tracking_url } }.

DELETE /api/v1/orders/:order_ref → pending order hatao.

Errors

Har error: { ok: false, code, error, charged: 0 }. Codes: UNAUTHORIZED 401 · VALIDATION 400 · INSUFFICIENT_WALLET 402 · PRICE_CHANGED 409 · NOT_SERVICEABLE / NO_COURIER / NO_PICKUP / COD_OFF 422 · COURIER_WALLET / COURIER_FAILED 502 (courier ka apna jawab error me, paisa wapas).

402 { "ok": false, "code": "INSUFFICIENT_WALLET", "error": "Webnify Ship wallet me balance kam hai: ₹0 hai, ₹112.5 chahiye…",
      "wallet_balance": 0, "needed": 112.5, "charged": 0 }