مركز الشحن دليل الربط والتنفيذ

مركز الشحن — دليل شامل

ربط مزودي الشحن، أتمتة تنفيذ الطلبات، وتتبع الشحنات. تعلّم كيفية إعداد بيانات اعتماد الناقل، وإنشاء الملصقات، وإدارة طلبات الدفع عند الاستلام.

★ مقدمة عن مركز الشحن

مركز الشحن هو مركز القيادة الخاص بك لإدارة التنفيذ عبر عدة شركات شحن. ربط حسابات الشحن، أتمتة إنشاء ملصقات الشحن، وتتبع الشحنات في الوقت الفعلي.

  • دعم متعدد الناقلات — ربط مزودي الخدمة من مصر، السعودية، الإمارات، والناقلات الدولية مثل DHL و FedEx.
  • الملصقات الآلية — إنشاء ملصقات الشحن (AWB) تلقائياً عند إنشاء الطلبات.
  • إدارة الدفع عند الاستلام — التعامل مع مبالغ الدفع عند الاستلام مع قواعد العملة لكل مزود.
  • التتبع في الوقت الفعلي — تتبع الشحنات ومزامنة تغييرات الحالة (قيد الانتظار، في الطريق، تم التسليم، ملغي).
  • بيانات الاعتماد الآمنة — مفاتيح API وبيانات الاعتماد مشفرة ومخزنة بأمان لكل متجر.
نصيحة: استخدم مركز الشحن من القائمة الجانبية للوصول إلى جميع الإعدادات والعمليات المتعلقة بالشحن.

1 مزودو الشحن المدعومون

يدعم كيدلي مزودي شحن رئيسيين عبر منطقة الشرق الأوسط وشمال أفريقيا والأسواق الدولية. انقر على اسم المزود لزيارة وثائقهم الرسمية.

مصر (EG)

السعودية (SA)

الإمارات (AE)

دولي (INT)

2 دليل الإعداد خطوة بخطوة

ربط حسابات مزودي الشحن بإدخال بيانات اعتماد API في نموذج إعداد مركز الشحن.

الوصول إلى مركز الشحن

القائمة الجانبية → مركز الشحن
  1. سجّل الدخول إلى لوحة تحكم كيدلي.
  2. انقر على مركز الشحن من القائمة الجانبية اليسرى.
  3. ستظهر قائمة بمزودي الشحن المتاحين مصنفة حسب المنطقة.
  4. انقر على إعداد على أي مزود لإعداد بيانات الاعتماد.
…/user/shipping-hub
مزودو الشحن
مصر (EG)
بوستاإعداد
أرامكسإعداد
السعودية (SA)
SMSAإعداد
شكل ٢.١ — قائمة مزودي مركز الشحن

الحصول على بيانات اعتماد API

كل مزود له خطوات مختلفة للحصول على بيانات اعتماد API. يعرض نموذج الإعداد تعليمات خاصة بكل مزود.

بوستا (Bosta)

  1. سجّل الدخول إلى لوحة تحكم بوستا.
  2. انتقل إلى الإعدادات > API.
  3. أنشئ مفتاح API وسري جديد.
  4. انسخ بيانات الاعتماد وألصقها في نموذج إعداد كيدلي.

أرامكس (Aramex)

  1. اتصل بأرامكس للحصول على بيانات اعتماد حساب الشحن الخاص بك.
  2. ستتلقى: رقم الحساب، اسم المستخدم، كلمة المرور، ورمز PIN.
  3. أدخل بيانات الاعتماد هذه في نموذج إعداد كيدلي.

مزودون آخرون

لـ SMSA و Ajex و Fetchr و DHL و FedEx وغيرها، زر بوابات المطورين أو اتصل بفريق الدعم للحصول على بيانات اعتماد API. سيظهر نموذج الإعداد متطلبات الحقل المحددة لكل مزود.

إدخال بيانات الاعتماد في كيدلي

مركز الشحن → إعداد (على بطاقة المزود)
  1. انقر على إعداد على المزود الذي تريد ربطه.
  2. يُظهر نموذج الإعداد حقولاً ديناميكية بناءً على مخطط المزود.
  3. املأ الحقول المطلوبة (المميزة بـ *).
  4. لحقول كلمة المرور، القيم الموجودة مقنعة لأسباب أمنية. اتركها فارغة للحفاظ على بيانات الاعتماد الموجودة.
  5. اضبط نسبة العمولة (%) — هذا هو رسوم المنصة لمعاملات الشحن.
  6. فعّل نشط لتمكين هذا المزود لمتجرك.
  7. انقر على حفظ الإعدادات.
…/user/shipping-hub/configure/1
إعداد بوستا
تعليمات الإعداد
للحصول على بيانات اعتماد بوستا، سجّل الدخول إلى لوحة تحكم بوستا وانتقل إلى الإعدادات > API.
مفتاح API *
السري *
رابط Webhook
نسبة العمولة (%)
حفظ الإعدادات
شكل ٢.٢ — نموذج إعداد المزود

اختبار الاتصال

  1. بعد حفظ بيانات الاعتماد، تُظهر بطاقة المزود حالة الاتصال.
  2. متصل — المؤشر الأخضر يعني بيانات الاعتماد صالحة.
  3. غير متصل — المؤشر الأحمر يعني بيانات الاعتماد تحتاج للتحقق.
  4. انقر على اختبار الاتصال (إن وُجد) للتحقق من الوصول إلى API.
  5. إذا فشل الاتصال، تحقق من بيانات الاعتماد وحاول مرة أخرى.
بعض المزودين قد يتطلبون خطوات تحقق إضافية مثل القائمة البيضاء للعناوين IP. تحقق من وثائق المزود للمتطلبات.

3 إنشاء الشحنات

بعد ربط مزود الشحن، يمكن لكيدلي إنشاء الشحنات والملصقات نيابة عنك. معظم أصحاب المتاجر يحتاجون الخطوات التالية فقط — دون أي برمجة.

ما تفعله كصاحب متجر

  1. اربط مزود شحن في مركز الشحن وفعّله (نشط).
  2. اختبر الاتصال للتأكد من صحة بيانات الاعتماد.
  3. عند وصول طلب، افتح الطلب واضغط إنشاء ملصق (أو اترك الإنشاء التلقائي إن كان مفعّلاً).
  4. اطبع / نزّل ملصق الشحن وألصقه على الطرد.
  5. تتبّع تحديثات الحالة على الطلب (قيد الانتظار → قيد المعالجة → في الطريق → تم التسليم).
نصيحة: أعدّ المزودين مرة واحدة. مركز الشحن يتولى إنشاء الملصقات والتتبع. استخدم «إنشاء ملصق» يدوياً من صفحة الطلب إذا فشل الإنشاء التلقائي.

سير العمل من الطلب إلى الشحن

كيف يتحول طلب العميل إلى شحنة قابلة للتتبع:

  1. إتمام الطلب — العميل يكمل الدفع على واجهة متجرك.
  2. التحقق من الطلب — النظام يتحقق من عنوان الشحن وطريقة الدفع.
  3. اختيار المزود — يُختار مزود الشحن النشط حسب الوجهة.
  4. إنشاء الملصق — المزود يُنشئ رقم التتبع وملصقاً قابلاً للطباعة.
  5. تحديث الطلب — تُحفظ معلومات التتبع وتنتقل حالة الطلب إلى قيد المعالجة.
  6. الاستلام والتتبع — استلام شركة الشحن (إن وُجد) وتتبع مباشر لك وللعميل.
الطلب → تدفق الشحن
1
إتمام العميل
↓
2
إنشاء الطلب
↓
3
اختيار المزود
↓
4
إنشاء الملصق
↓
5
تفعيل التتبع
شكل ٣.١ — سير العمل من الطلب إلى الشحن
للمطورين — هياكل API والمحولات والأنماط المتقدمة

مرجع تقني اختياري للفرق التي تتكامل برمجياً مع مركز الشحن. يمكن لأصحاب المتاجر تخطي هذا القسم.

هيكل البيانات

لإنشاء شحنة برمجياً، وفّر بيانات المرسل والمستلم والطرد ومبلغ الدفع عند الاستلام ومرجع الطلب:

الحقلالنوعالوصف
senderكائنمعلومات المرسل (الاسم، الهاتف، العنوان، المدينة، الدولة)
recipientكائنمعلومات المستلم (الاسم، الهاتف، العنوان، المدينة، الدولة)
packageكائنتفاصيل الطرد (الوزن، الأبعاد، الوصف)
cod_amountعشريمبلغ الدفع عند الاستلام (0 للطلبات المدفوعة مسبقاً)
currencyسلسلةرمز العملة (مثل EGP، SAR، AED، USD)
referenceسلسلةرقم مرجع الطلب للتتبع
providerسلسلةمعرف مزود الشحن (مثل 'bosta'، 'aramex')
{
  "sender": {
    "name": "اسم المتجر",
    "phone": "+201234567890",
    "email": "[email protected]",
    "address": "123 شارع رئيسي",
    "city": "القاهرة",
    "country": "EG",
    "postal_code": "11511"
  },
  "recipient": {
    "name": "اسم العميل",
    "phone": "+201098765432",
    "email": "[email protected]",
    "address": "456 شارع العميل",
    "city": "الإسكندرية",
    "country": "EG",
    "postal_code": "21500"
  },
  "package": {
    "weight": 1.5,
    "length": 20,
    "width": 15,
    "height": 10,
    "description": "إلكترونيات - هاتف ذكي"
  },
  "cod_amount": 2500.00,
  "currency": "EGP",
  "reference": "ORD-2024-001234",
  "provider": "bosta"
}

أمثلة الكود (PHP / Laravel)

use App\Services\Shipping\ShippingAdapterFactory;
use App\Services\Shipping\Adapters\BostaAdapter;

$user = auth()->user();
$adapterFactory = new ShippingAdapterFactory($user);
$adapter = $adapterFactory->getAdapter('bosta');

if (!$adapter) {
    throw new \Exception('مزود بوستا غير مُعد');
}

$shipmentData = [
    'sender' => [
        'name' => $user->shop_name,
        'phone' => $user->phone,
        'email' => $user->email,
        'address' => $user->address,
        'city' => $user->city,
        'country' => 'EG',
        'postal_code' => $user->postal_code ?? '11511'
    ],
    'recipient' => [
        'name' => $order->customer_name,
        'phone' => $order->customer_phone,
        'email' => $order->customer_email,
        'address' => $order->shipping_address,
        'city' => $order->shipping_city,
        'country' => $order->shipping_country,
        'postal_code' => $order->shipping_postal_code
    ],
    'package' => [
        'weight' => $order->total_weight,
        'length' => $order->package_length ?? 20,
        'width' => $order->package_width ?? 15,
        'height' => $order->package_height ?? 10,
        'description' => 'طلب #' . $order->order_number
    ],
    'cod_amount' => $order->payment_method === 'cod' ? $order->total : 0,
    'currency' => $order->currency_code,
    'reference' => $order->order_number,
    'provider' => 'bosta'
];

try {
    $response = $adapter->createShipment($shipmentData);
    $order->tracking_number = $response['tracking_number'];
    $order->shipping_cost = $response['shipping_cost'];
    $order->estimated_delivery = $response['estimated_delivery'];
    $order->status = 'processing';
    $order->save();
} catch (\Exception $e) {
    // سجّل الخطأ وعالجه
}

معالجة الاستجابة

{
  "success": true,
  "tracking_number": "BOS-1234567890",
  "shipping_cost": 45.50,
  "currency": "EGP",
  "estimated_delivery": "2024-01-25",
  "label_url": "https://provider.example.com/labels/BOS-1234567890.pdf",
  "provider_reference": "PROV-987654321"
}

سيناريوهات الأخطاء الشائعة

  • الإعداد مفقود — بيانات اعتماد المزود غير مُعدة
  • عنوان غير صالح — تنسيق عنوان المستلم غير صحيح
  • الوجهة غير مدعومة — المزود لا يشحن إلى تلك الدولة
  • تجاوز حد الدفع عند الاستلام — المبلغ يتجاوز حد المزود
  • حد المعدل — طلبات كثيرة جداً إلى API المزود
  • فشل المصادقة — بيانات اعتماد API غير صالحة

أنماط متقدمة

مزودون متعددون حسب الدولة

$provider = match ($shipmentData['recipient']['country']) {
    'EG' => 'bosta',
    'SA' => 'smsa',
    'AE' => 'fetchr',
    default => 'aramex'
};
$adapter = $adapterFactory->getAdapter($provider);

شحنات دفعية

$orders = Order::where('status', 'pending')->get();
foreach ($orders as $order) {
    try {
        $adapter = $adapterFactory->getAdapter($order->shipping_provider);
        $response = $adapter->createShipment(prepareShipmentData($order));
        $order->update([
            'tracking_number' => $response['tracking_number'],
            'status' => 'processing'
        ]);
    } catch (\Exception $e) {
        Log::error("فشل الشحن للطلب {$order->id}: " . $e->getMessage());
    }
}
نفّذ دائماً معالجة الأخطاء وتسجيل السجلات عند استدعاء واجهات الشحن.

4 العمليات وتنفيذ الطلبات

بعد إعداد المزودين، تدمج عمليات الشحن مع سير عمل طلباتك.

إنشاء الملصقات تلقائياً

عند إنشاء طلب جديد، يمكن للنظام إنشاء ملصقات الشحن (AWB) تلقائياً إذا:

  • مزود شحن مُعد ومفعّل.
  • الطلب يحتوي على عنوان شحن ساري.
  • دفع الطلب مؤكد (لطلبات الدفع عند الاستلام، يتم تضمين مبلغ الدفع عند الاستلام).
  1. الطلبات في حالة قيد الانتظار مؤهلة لإنشاء الملصق.
  2. يرسل النظام بيانات الشحن إلى API المزود المُعد.
  3. يُرجع المزود رقم التتبع وملصقاً قابل للطباعة.
  4. يُحفظ رقم التتبع في الطلب ويُعرض في تفاصيل الطلب.
  5. تُحدّث حالة الطلب إلى قيد المعالجة عند إنشاء الملصق.

التعامل مع الدفع عند الاستلام (COD)

طلبات الدفع عند الاستلام تتطلب معاملة خاصة لجمع المبالغ وقواعد العملة:

  • مبلغ الدفع عند الاستلام — إجمالي الطلب يُرسل إلى المزود كمبلغ الدفع عند الاستلام لجمعه.
  • قواعد العملة — بعض المزودين يقبلون الدفع عند الاستلام بعملات معينة فقط (مثل الجنيه المصري لمزودي مصر).
  • تحويل العملة — إذا كان متجرك يستخدم عملة مختلفة، يحوّل النظام مبلغ الدفع عند الاستلام إلى العملة المقبولة للمزود.
  • رسوم الدفع عند الاستلام — بعض المزودين يفرضون رسوماً إضافية لطلبات الدفع عند الاستلام. تُخصم عادة من المبلغ المجموع.
نصيحة: أعدّ إعدادات العملات المتعددة لضمان تحويل صحيح لمبلغ الدفع عند الاستلام للمزودين الدوليين.

تتبع الشحنات في الوقت الفعلي

تتبع الشحنات ومزامنة تغييرات الحالة من المزود إلى نظام طلباتك:

الحالةالوصف
قيد الانتظارالطلب مُنشأ، بانتظار إنشاء الملصق
قيد المعالجةالملصق مُنشأ، الشحن مُلتقط من قبل الناقل
في الطريقالطرد في الطريق إلى عنوان التسليم
تم التسليمالطرد سُلّم بنجاح للعميل
ملغيالشحن مُلغي أو مُرجع
استثناءمشكلة في التسليم (عنوان خاطئ، مرفوض، إلخ)
  1. يرسل المزودون تحديثات webhook عند تغيير حالة الشحن.
  2. يتلقى كيدلي هذه التحديثات ويُزامنها مع طلبك.
  3. تُحدّث حالة الطلب تلقائياً بناءً على حالة المزود.
  4. يمكن للعملاء تتبع طلباتهم باستخدام رقم التتبع في واجهة متجرك.
…/all/item/orders/1043
طلب #1043
التتبع: BOS-12345678
إنشاء الملصق
الالتقاط
في الطريق
تم التسليم
شكل ٤.١ — الجدول الزمني لتتبع الطلب

إنشاء الملصق يدوياً

إذا فشل إنشاء الملصق تلقائياً أو تحتاج إلى إعادة الإنشاء:

  1. افتح تفاصيل الطلب من جميع الطلبات.
  2. انقر على إنشاء ملصق في قسم الشحن.
  3. اختر مزود الشحن إذا كان متعدد متاح.
  4. يطلب النظام ملصقاً جديداً من المزود.
  5. نزّل أو اطبع الملصق لإلصاقه على الطرد.

5 أوضاع المحاكاة واليدوي

اختبر سير عمل الشحن دون حسابات ناقل حية باستخدام محولات المحاكاة واليدوي.

محول المحاكاة

يتيح لك محول المحاكاة المدمج اختبار الدفع وإنشاء الملصق دون الاتصال بالناقلين الحقيقيين:

  • اختبار الدفع — محاكاة سير العمل الكامل من الطلب إلى الشحن.
  • إنشاء الملصق — يُنشئ أرقام تتبع وملصقات وهمية.
  • تحديثات الحالة — يحاكي تغييرات حالة الشحن بمرور الوقت.
  • بدون تكاليف — لا رسوم شحن أو مكالمات API فعلية.
  1. في مركز الشحن، ابحث عن مزود المحاكاة.
  2. انقر على إعداد — إعداد بسيط مطلوب (اسم المستخدم/كلمة المرور للبوابة).
  3. اضبط معلمات اختيارية مثل تأخير البوت (مللي ثانية) ومعدل النجاح (%).
  4. احفظ وفعّل محول المحاكاة.
  5. اختبر سير عمل الدفع — ستستخدم الطلبات المحاكاة للشحن.
المحاكاة مثالية للتطوير والاختبار والتدريب. انتقل إلى مزودين حقيقيين عند الذهاب حياً.

محول الشحن اليدوي

للشركات المحلية دون تكامل API، استخدم المحول اليدوي:

  • مبني على التواصل — أعدّ بيانات الهاتف والبريد الإلكتروني للتواصل مع شركة الشحن.
  • قوالب الملصقات — اختر من تنسيقات A4 القياسية أو طابعات الحرارية.
  • عنوان الاستلام — اضبط موقع الاستلام الافتراضي لاستلام شركة الشحن.
  • التتبع اليدوي — حدّث حالة الشحن يدوياً في نظام الطلبات.
  1. في مركز الشحن، ابحث عن الشحن اليدوي المحلي.
  2. أعدّ تفاصيل التواصل (الهاتف، البريد الإلكتروني) لشركة الشحن.
  3. اختر قالب الملصق واضبط عنوان الاستلام.
  4. احفظ وفعّل المحول اليدوي.
  5. عند استخدام الطلبات لهذا المزود، ستحتاج إلى التنسيق يدوياً مع شركة الشحن.

التبديل بين المزودين

يمكنك إعداد مزودين متعددين والتبديل بينهم:

  1. أعدّ بيانات اعتماد لمزودين متعددين في مركز الشحن.
  2. اضبط مفتاح نشط لكل مزود لتمكين/تعطيل.
  3. عند إنشاء الطلبات، اختر المزود للاستخدام (إذا كان متعدد مفعّل).
  4. عطّل مزوداً للتوقف عن استخدامه للطلبات الجديدة.
  5. الطلبات الموجودة تستمر في استخدام المزود المُعيّن أصلاً.
نصيحة: استخدم مزودين مختلفين لمناطق أو أنواع طلبات مختلفة (مثل المحاكاة للاختبار، بوستا لطلبات مصر، أرامكس للدولي).

6 استكشاف الأخطاء

المشاكل الشائعة والحلول

المشكلةالحل
فشل الاتصالتحقق من صحة بيانات اعتماد API. تحقق مما إذا كان المزود يتطلب القائمة البيضاء للعناوين IP.
خطأ في إنشاء الملصقتأكد من أن الطلب يحتوي على عنوان ساري. تحقق مما إذا كان المزود يدعم الدولة الوجهة.
مبلغ الدفع عند الاستلام غير صحيحتحقق من إعدادات تحويل العملة. تحقق من العملة المقبولة للمزود.
التتبع لا يُحدّثتحقق مما إذا كانت webhooks مُعدة. تحقق مما إذا كان المزود يُرسل تحديثات الحالة.
المزود غير مُدرجاتصل بدعم كيدلي لطلب تكامل مزود إضافي.

الحصول على المساعدة

إذا واجهت مشاكل غير مغطاة هنا:

  • تحقق من الوثائق الرسمية للمزود لمتطلبات API.
  • راجع تعليمات الإعداد في نموذج الإعداد.
  • اتصل بدعم كيدلي من خلال قسم الدعم.