دليل الربط والتكامل (API) 🔌

مرحباً بك في دليل التكامل البرمجي (API Documentation) لمنصة ERP Express.
لقد تم بناء واجهة برمجة التطبيقات الخاصة بنا وفق أعلى المعايير التقنية لتوفير تجربة ربط سلسة واحترافية لمتاجرك الإلكترونية. من خلال هذا التكامل، ستتمكن من أتمتة عملياتك اللوجستية بالكامل؛ بدءاً من التوليد التلقائي للشحنات فور تلقي الطلبات، مروراً بالتتبع الدقيق في الوقت الفعلي، وصولاً إلى إدارة التسويات المالية بفعالية وأمان.

---

المتطلبات الأساسية قبل البدء

لتتمكن من ربط متجرك بنجاح، ستحتاج إلى:

• حساب تاجر نشط على منصة ERP Express.
• مفتاح الربط (API Key): يمكنك الحصول عليه من لوحة تحكم التاجر:
  • اذهب إلى: الملف الشخصي والإعدادات > إعدادات الربط (API) > توليد مفتاح جديد.
  • قم بنسخ المفتاح والاحتفاظ به في مكان آمن.

1 الطريقة الأولى: باستخدام إضافة WooCommerce 🛒

إذا كان متجرك مبنياً باستخدام منصة WordPress / WooCommerce، لا داعي لأي برمجة! فقط اتبع الخطوات التالية:

2 الطريقة الثانية: الربط البرمجي المباشر (REST API) 💻

هذه الطريقة مخصصة للمطورين وأصحاب المتاجر المبنية برمجياً من الصفر أو باستخدام منصات أخرى.

1. إنشاء شحنة جديدة (Create Shipment)

لإنشاء شحنة جديدة، قم بإرسال طلب من نوع POST إلى نقطة النهاية المخصصة.

curl -X POST "https://app.erpexpress.dz/api/v1/shipments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "receiver_name": "أحمد محمد",
        "receiver_phone": "0555000000",
        "wilaya_id": 16,
        "commune_id": 45,
        "address": "الجزائر العاصمة، حي ديدوش مراد",
        "service_type": "Home Delivery",
        "cod_amount": 4500,
        "reference": "ORDER-9876",
        "notes": "الرجاء الاتصال قبل التوصيل"
      }'

شرح الحقول الهامة:

• receiver_name: اسم المستلم (الزبون).
• receiver_phone: رقم هاتف المستلم.
• wilaya_id: رقم أو معرف الولاية.
• service_type: نوع خدمة التوصيل (مثلاً: Home Delivery أو Stop Desk).
• cod_amount: المبلغ المراد تحصيله (الدفع عند الاستلام).

2. تتبع حالة الشحنة (Get Shipment Status)

يُستخدم لمعرفة تفاصيل الشحنة وحالتها الحالية.

3. إلغاء شحنة (Cancel Shipment)

3 الطريقة الثالثة: الإشعارات التلقائية (Webhooks) 🪝

لتجنب الاستعلام المتكرر عن حالة الشحنة، تقوم منصة ERP Express بإرسال إشعار تلقائي لمتجرك في اللحظة التي تتغير فيها حالة الشحنة.

كيفية تسجيل Webhook

curl -X POST "https://app.erpexpress.dz/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://your-store.com/api/webhooks/erp-express",
        "events": ["shipment.status_updated"]
      }'

استلام إشعار Webhook

بمجرد تسليم الشحنة للزبون، سنرسل لك طلب POST إلى الرابط الذي قمت بتسجيله، يحتوي على البيانات التالية:

{
  "event": "shipment.status_updated",
  "shipment_id": 1024,
  "reference": "ORDER-9876",
  "old_status": "In-Transit",
  "new_status": "Delivered",
  "updated_at": "2026-06-27T14:30:00Z"
}

استكشاف الأخطاء وإصلاحها