Pigee Shipping Partner API

فوری شروعات

اکاؤنٹ بنانے سے لے کر آپ کی پہلی براہ راست شپمنٹ تک ایک گھنٹے سے بھی کم میں۔ یہ پانچ مراحل اختیار کریں:

1. Pigee کا ایک مفت اکاؤنٹ بنائیں account.pigeepost.com پر اور اپنے اکاؤنٹ کی قسم کے طور پر شپنگ پارٹنر منتخب کریں۔
2. جائیں ڈیش بورڈ → ڈویلپر → API کلیدیں اور ایک براہ راست کلید اور ایک ٹیسٹ کلید جنریٹ کریں۔
3. اپنی ادائیگی کی طریقہ کار منتخب کریں: Pigee Pay یا Pigee اکاؤنٹ بیلنس.
4. اپنی سروس فیس کو ڈیش بورڈ → فیسز.
5. میں ترتیب دیں۔ درآمد کریں Postman مجموعہ سٹیجنگ ڈویلپمنٹ کے لیے۔

تصدیق

ہر درخواست میں آپ کی API کلید شامل ہونی چاہیے Authorization ہیڈر میں بیئرر ٹوکنکے طور پر۔ کلیدیں آپ کے پارٹنر اکاؤنٹ کے لیے محدود ہیں اور آپ کی فیس کی ترتیب اور ادائیگی کی طریقہ کار کو برقرار رکھتی ہیں۔

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

کلید کی اقسام

ماحول اور بیس URLs

سینڈ باکس پروڈکشن کا مکمل 1:1 آئینہ ہے۔ اپنی کلید کا سابقہ بدل کر یا وضاحت کے لیے واضح سینڈ باکس URL استعمال کر کے ماحول تبدیل کریں۔

SDKs اور لائبریریاں

سرکاری SDKs REST API کو ٹائپ شدہ ماڈلز، خودکار دوبارہ کوششوں اور سینڈ باکس ہیلپرز کے ساتھ لپیٹتے ہیں۔

API کلید کی تصدیق کریں

براہ راست جانے سے پہلے اس اِن ڈ پوائنٹ کو کال کریں تاکہ تصدیق ہو کہ آپ کی API کلید فعال ہے اور صحیح طریقے سے ترتیب دی گئی ہے۔

POST /api/v1/store/valid
Authorization: Bearer pgk_live_…
Content-Type: application/json

{
  "store_type": 2,
  "api_key": "pgk_live_YOUR_KEY"
}

{
  "valid": true,
  "account": {
    "id": "acc_7H4K",
    "type": "shipping_partner",
    "payment_mode": "pigee_pay",
    "service_fee_pct": 8.5,
    "balance_gbp": 240.00
  }
}

شپنگ ریٹس حاصل کریں

کسی شپمنٹ کے لیے براہ راست کیریئر ریٹس حاصل کریں۔ تمام دستیاب سروسز قیمت کے لحاظ سے ترتیب شدہ واپس کریں، ٹرانزٹ ٹائم، انشورنس شدہ قدر کی معاونت اور ل yanded کی لاگت شامل ہے۔

{
  "shop_url": "https://your-store.com",
  "currency": "GBP",
  "parcel": {
    "type": "Box",
    "boxsize": 4
  },
  "weight": { "value": 4, "units": "kg" },
  "dimension": {
    "length": 40,
    "width": 30,
    "height": 20,
    "units": "cms"
  },
  "address": {
    "pickup": {
      "address_line1": "10 High Street",
      "town": "London",
      "post_code": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "destination": {
      "address_line1": "123 Ocean Drive",
      "town": "Miami",
      "post_code": "33101",
      "country": "United States"
    }
  }
}

{
  "rates": [
    {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE",
      "method_title": "DHL Express Worldwide",
      "price": 125.50,
      "currency": "GBP",
      "transit_days": 2,
      "insurance_available": true,
      "customs_included": true
    }
  ],
  "currency": "GBP",
  "request_id": "req_7H4K2026"
}

درخواست کے پیرامیٹرز

آرڈر بنائیں

Pigee آرڈر بنائیں استعمال کرتے ہوئے carrier_request_id شرح کے اختتام سے۔ Pigee لیبل، تجارتی انوائس اور، اگر Pigee Pay استعمال ہو رہی ہے، تو ہوسٹ شدہ ادائیگی کی لنک بناتا ہے۔

{
  "order_from": "api",
  "shop_url": "https://your-store.com",
  "order_id": "ORDER-10001",
  "currency": "GBP",
  "items": [
    {
      "name": "Vintage leather jacket",
      "quantity": 1,
      "value": 600.00,
      "currency": "GBP",
      "hs_code": "4203100090"
    }
  ],
  "shippingData": {
    "method_title": "DHL Express Worldwide",
    "cost": 125.50,
    "currency": "GBP",
    "meta_data": {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE"
    }
  }
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "pending_payment",
  "payment_url": "https://pay.pigee.com/c/abc123",
  "label_url": null,
  "tracking_number": null
}

آرڈر مکمل کریں

ادائیگی کی تصدیق کے بعد حتمی تکمیل کی تفصیلات بھیجیں۔ Pigee شپنگ لیبل بناتا ہے، کیریئر بک کرتا ہے اور ٹریکنگ نمبر واپس کرتا ہے۔

{
  "order_id": "po_78910",
  "status": "processing",
  "shop_id": "https://your-store.com",
  "currency": "GBP",
  "total": 725.50,
  "shipping_total": 125.50
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "booked",
  "label_url": "https://labels.pigeepost.com/PGE-7H4K-2026-0042.pdf",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "estimated_delivery": "2026-05-08"
}

ٹریکنگ

API کے ذریعے بنائے گئے کسی بھی شپمنٹ کے لیے براہ راست ٹریکنگ ایونٹس حاصل کریں۔

{
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "status": "in_transit",
  "estimated_delivery": "2026-05-08",
  "events": [
    {
      "timestamp": "2026-05-06T08:14:00Z",
      "status": "in_transit",
      "location": "DHL Hub, Leipzig",
      "description": "Shipment in transit"
    }
  ]
}

ادائیگی کے طریقے

Pigee دو ادائیگی کے طریقے سپورٹ کرتا ہے۔ فعال طریقہ آپ کے شریک ڈیش بورڈ میں سیٹ ہے اور تمام آرڈرز پر لاگو ہوتا ہے۔

سروس کی فیسیں

ایک شپنگ پارٹنر کے طور پر، آپ Pigee کی بنیادی کیریئر شرح کے اوپر اپنی اپنی فیس شامل کر سکتے ہیں۔ فیسیں آپ کے ڈیش بورڈ میں ترتیب دی جاتی ہیں اور شرح واپس کرنے سے پہلے خودکار طور پر لاگو ہوتی ہیں۔

• فیصد فیس: بنیادی کیریئر لاگت کے فیصد کے طور پر لاگو۔
• مقررہ فیس: ہر شپمنٹ میں شامل کی گئی فلیٹ رقم۔
• فی لین کے مستثنیات: مخصوص اصل/منزل کے جوڑوں کے لیے عام فیس کو زیادہ لکھیں۔

تسویہ کاری اور زرمبادلہ

Pigee Pay آخری صارفین سے جمع کرتا ہے 135+ کرنسیاں اور آپ کے مقامی کرنسی میں آپ کے بینک اکاؤنٹ میں رقم منتقل کرتا ہے۔

• سیٹلمنٹ سائیکل عام طور پر شپمنٹ ڈیلیوری کی تصدیق کے بعد T+2 کاروباری دن ہے۔
• ڈیش بورڈ کے ذریعے اپنے Pigee بیلنس سے نکلوائیں۔
• تفصیلی لین دین کے ریکارڈ کے تحت دستیاب ہیں Finance → Settlements.
• سیٹل شدہ لین دین کے انوائسز خود کار طور پر تیار ہوتے ہیں اور PDF کے طور پر دستیاب ہیں۔

Webhooks

Pigee حقیقی وقت کے واقعات کو JSON کے طور پر آپ کے HTTPS اینڈ پوائنٹ پر بھیجتا ہے POST درخواستیں۔ اپنا webhook URL کنفیگر کریں Dashboard → Developer → Webhooks.

{
  "event": "parcel.delivered",
  "created_at": "2026-05-08T14:22:07Z",
  "api_version": "v1",
  "data": {
    "pigee_order_id": "PGE-7H4K-2026-0042",
    "order_id": "ORDER-10001",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "delivered_at": "2026-05-08T14:18:00Z"
  }
}

Webhook ایونٹ حوالہ

ویب ہک دستخطیں

ہر ویب ہک درخواست میں شامل ہے X-Pigee-Signature ہیڈر، خام درخواست کے جسم کا HMAC-SHA256 ڈائجسٹ۔ پروسیس کرنے سے پہلے ہمیشہ اس کی تصدیق کریں۔

// Node.js
const crypto = require('crypto');

function verifyPigeeWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

خرابیاں

تمام خرابیاں JSON کے ساتھ واپس آتی ہیں error object میں مشین قابل فہم code اور انسانی قابل فہم message.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your Pigee partner balance is not sufficient to create this shipment.",
    "request_id": "req_7H4K2026"
  }
}

شرح کی حدود

شرح کی حدود فی API کلید پر لاگو ہوتی ہیں اور آپ کی اکاؤنٹ ٹائر کے ساتھ بڑھتی ہیں۔

جب شرح کی حد پوری ہو جائے تو API واپس کرتا ہے HTTP 429 کے ساتھ Retry-After ہیڈر۔

ڈیٹا کی اقسام اور کنونشنز

• تاریخیں اور اوقات - ISO 8601 UTC، مثال کے طور پر 2026-05-06T14:22:07Z
• کرنسیاں - ISO 4217 تین حروفی کوڈز، مثال کے طور پر GBP, USD, NGN
• رقوم - number دو اعشاریہ جگہوں کے ساتھ، ہمیشہ currency فیلڈ کے ساتھ جوڑا جائے
• ملکوں کے نام - انگریزی مکمل نام، مثال کے طور پر "United Kingdom", "United States"
• فون نمبرز - E.164 فارمیٹ تجویز کردہ، مثال کے طور پر +447700900123
• وزن - kg یا lbs درخواست کے مطابق مقرر
• IDs - Pigee سے تیار کردہ IDs سابقہ فارمیٹ استعمال کرتے ہیں، مثال کے طور پر po_78910, cr_abc123

کیریئر IDs حوالہ

استعمال کریں pigee_carrier_id آرڈرز بناتے وقت نرخ کے جواب سے اقدار لیں۔

تبدیلیوں کی فہرست

v1.3 - مئی 2026

• شامل کیا گیا insurance_available اور customs_included شرح الاسعار کے جواب میں فلیگز۔
• Webhook کی توثیق اب HMAC-SHA256 استعمال کرتی ہے۔
• نیا خرابی کوڈ RATE_EXPIRED.
• ٹریکنگ اختتام شامل کیا گیا: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - فروری 2026

• ڈیش بورڈ میں فی پٹری سروس فیس میں نمائندگی شامل کی گئی۔
• Pigee Pay ادائیگی کے روابط اب ایک شامل کریں expires_at فیلڈ۔
• گمرکی اور تسویہ کے لیے نئے webhook واقعات شامل کیے گئے۔

v1.1 - اکتوبر 2025

• ابتدائی Postman مجموعہ شائع کیا گیا۔
• ریت کے ماحول کا افتتاح کیا گیا۔
• اکاؤنٹ بیلنس ادائیگی کی طریقہ جاری کی گئی۔

v1.0 - جون 2025

• ابتدائی عوامی رہائی: توثیق، شرح حاصل کریں، آرڈر بنائیں، آرڈر پورا کریں۔