واجهة برمجة تطبيقات Pigee لشركاء الشحن

بداية سريعة

من إنشاء الحساب إلى أول شحنة فعلية لك في أقل من ساعة. اتبع هذه الخطوات الخمس:

1. أنشئ حساب Pigee مجانيًا على account.pigeepost.com واختر شريك الشحن كنوع حسابك.
2. اذهب إلى لوحة التحكم ← المطورون ← مفاتيح API وأنشئ مفتاحًا فعليًا ومفتاحًا تجريبيًا.
3. اختر وضع الدفع الخاص بك: Pigee Pay أو رصيد حساب Pigee.
4. اضبط رسوم خدمتك في لوحة التحكم ← الرسوم.
5. استورد مجموعة Postman لتطوير بيئة الاختبار.

المصادقة

يجب أن يتضمن كل طلب مفتاح API الخاص بك في ترويسة Authorization كـ رمز Bearer. المفاتيح مرتبطة بحساب شريكك وتحمل إعدادات رسومك ووضع الدفع الخاص بك.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

أنواع المفاتيح

البيئات وعناوين URL الأساسية

بيئة الاختبار هي نسخة مطابقة تمامًا لبيئة الإنتاج. يمكنك التبديل بين البيئتين عبر تغيير بادئة مفتاحك، أو استخدام رابط بيئة الاختبار الصريح لمزيد من الوضوح.

حزم SDK والمكتبات

توفر حزم SDK الرسمية غلافًا لواجهة REST البرمجية يتضمن نماذج مصنّفة، وإعادة محاولة تلقائية، وأدوات مساعدة لبيئة الاختبار.

التحقق من مفتاح 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
  }
}

الحصول على أسعار الشحن

احصل على أسعار شركات الشحن المباشرة لشحنة ما. يعيد جميع الخدمات المتاحة مرتبة حسب السعر، بما في ذلك وقت النقل، ودعم القيمة المؤمَّن عليها، والتكلفة الإجمالية شاملة الرسوم.

{
  "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"
}

التتبع

استرجع أحداث التتبع الحيّة لأي شحنة أُنشئت عبر واجهة برمجة التطبيقات.

{
  "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 الخاص بك عبر لوحة التحكم.
• سجلات المعاملات التفصيلية متاحة ضمن المالية ← التسويات.
• تُنشأ فواتير المعاملات المُسوَّاة تلقائيًا وتكون متاحة بصيغة PDF.

Webhooks

يرسل Pigee أحداثًا فورية إلى نقطة النهاية HTTPS الخاصة بك على شكل طلبات JSON POST طلبات. اضبط رابط الويب هوك الخاص بك في لوحة التحكم ← المطوّرون ← 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"
  }
}

مرجع أحداث الويب هوك

توقيعات الويب هوك

يتضمن كل طلب ويب هوك 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 يتضمن رمزًا قابلًا للقراءة آليًا code ورسالة قابلة للقراءة من قبل الإنسان message.

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

حدود المعدل

تُطبَّق حدود معدل الطلبات لكل مفتاح API وتتفاوت حسب فئة حسابك.

عند بلوغ حد معدل الطلبات، تُعيد واجهة برمجة التطبيقات HTTP 429 مع Retry-After ترويسة.

أنواع البيانات والاصطلاحات

• التواريخ والأوقات - بصيغة ISO 8601 بالتوقيت العالمي المنسق، مثل 2026-05-06T14:22:07Z
• العملات - رموز مكونة من ثلاثة أحرف وفق ISO 4217، مثل GBP, USD, NGN
• القيم المالية - number بخانتين عشريتين، مقترنة دائمًا بحقل currency حقل
• أسماء الدول - الأسماء الكاملة باللغة الإنجليزية، مثل "United Kingdom", "United States"
• أرقام الهواتف - يُنصح باستخدام صيغة E.164، مثل +447700900123
• الأوزان - kg أو lbs مُحدَّدة لكل طلب
• المعرّفات - تستخدم المعرّفات الصادرة عن Pigee صيغة بادئة، مثل po_78910, cr_abc123

دليل معرّفات الناقلين

الاستخدام pigee_carrier_id القيم من استجابة الأسعار عند إنشاء الطلبات.

سجل التغييرات

الإصدار 1.3 - مايو 2026

• تمت إضافة insurance_available و customs_included أعلام إلى استجابة الأسعار.
• يعتمد التحقق من توقيع الـ Webhook الآن على HMAC-SHA256.
• رمز خطأ جديد RATE_EXPIRED.
• تمت إضافة نقطة نهاية للتتبع: GET /api/v1/tracking/{pigee_order_id}.

الإصدار 1.2 - فبراير 2026

• تمت إضافة إمكانية تجاوز رسوم الخدمة لكل مسار في لوحة التحكم.
• روابط الدفع في Pigee Pay تتضمن الآن حقل expires_at .
• تمت إضافة أحداث Webhook جديدة للجمارك والتسويات.

الإصدار 1.1 - أكتوبر 2025

• نشر مجموعة Postman الأولية.
• إطلاق بيئة الاختبار Sandbox.
• إصدار وضع الدفع برصيد الحساب.

الإصدار 1.0 - يونيو 2025

• الإصدار العام الأولي: التحقق، الحصول على الأسعار، إنشاء الطلب، تنفيذ الطلب.