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

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

الحصول على بيانات اعتماد 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. انقر على حفظ الإعدادات.

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

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

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

لإنشاء شحنة، تحتاج إلى توفير بيانات منظمة تحتوي على معلومات المرسل والمستلم وتفاصيل الطرد ومبلغ الدفع عند الاستلام ومرجع الطلب. الحقول التالية مطلوبة:

{
  "sender": {
    "name": "اسم المتجر",
    "phone": "+201234567890",
    "email": "store@example.com",
    "address": "123 شارع رئيسي",
    "city": "القاهرة",
    "country": "EG",
    "postal_code": "11511"
  },
  "recipient": {
    "name": "اسم العميل",
    "phone": "+201098765432",
    "email": "customer@example.com",
    "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();
    
    return response()->json([
        'success' => true,
        'tracking_number' => $response['tracking_number'],
        'label_url' => $response['label_url']
    ]);
    
} catch (\Exception $e) {
    return response()->json([
        'success' => false,
        'error' => $e->getMessage()
    ], 500);
}

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

عند إنشاء الشحنة بنجاح، يُرجع المزود استجابة تحتوي على معلومات التتبع وتفاصيل الشحن:

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

حقول الاستجابة الناجحة:

• tracking_number — رقم تتبع فريد للشحنة
• shipping_cost — التكلفة التي يفرضها المزود
• currency — عملة تكلفة الشحن
• estimated_delivery — تاريخ التسليم المتوقع
• label_url — رابط لتنزيل/طباعة ملصق الشحن
• provider_reference — مرجع داخلي من المزود

معالجة الأخطاء:

إذا فشل إنشاء الشحنة، يطرح المحول استثناءً مع تفاصيل الخطأ:

{
  "success": false,
  "error": "عنوان المستلم غير صالح",
  "details": "تنسيق الرمز البريدي غير صحيح للبلد المحدد"
}

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

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

سير العمل خطوة بخطوة

سير العمل الكامل من الطلب إلى الشحن من الدفع إلى إنشاء الملصق:

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

أنماط التكامل المتقدمة

مزودون متعددون

للمتاجر التي تشحن إلى مناطق متعددة، يمكنك تنفيذ منطق اختيار المزود:

// اختيار المزود بناءً على دولة الوجهة
$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);
        $shipmentData = prepareShipmentData($order);
        $response = $adapter->createShipment($shipmentData);
        
        $order->update([
            'tracking_number' => $response['tracking_number'],
            'status' => 'processing'
        ]);
    } catch (\Exception $e) {
        Log::error("فشل الشحن للطلب {$order->id}: " . $e->getMessage());
    }
}

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

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

• مزود شحن مُعد ومفعّل.
• الطلب يحتوي على عنوان شحن ساري.
• دفع الطلب مؤكد (لطلبات الدفع عند الاستلام، يتم تضمين مبلغ الدفع عند الاستلام).

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

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

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

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

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

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

1. يرسل المزودون تحديثات webhook عند تغيير حالة الشحن.
2. يتلقى كيدلي هذه التحديثات ويُزامنها مع طلبك.
3. تُحدّث حالة الطلب تلقائياً بناءً على حالة المزود.
4. يمكن للعملاء تتبع طلباتهم باستخدام رقم التتبع في واجهة متجرك.

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

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

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

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

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

• اختبار الدفع — محاكاة سير العمل الكامل من الطلب إلى الشحن.
• إنشاء الملصق — يُنشئ أرقام تتبع وملصقات وهمية.
• تحديثات الحالة — يحاكي تغييرات حالة الشحن بمرور الوقت.
• بدون تكاليف — لا رسوم شحن أو مكالمات API فعلية.

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

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

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

• مبني على التواصل — أعدّ بيانات الهاتف والبريد الإلكتروني للتواصل مع شركة الشحن.
• قوالب الملصقات — اختر من تنسيقات A4 القياسية أو طابعات الحرارية.
• عنوان الاستلام — اضبط موقع الاستلام الافتراضي لاستلام شركة الشحن.
• التتبع اليدوي — حدّث حالة الشحن يدوياً في نظام الطلبات.

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

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

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

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