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

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

الفارق هو API. وهذه المقالة تشرح لك كيف تفعل نفس الشيء.

أولاً: ما هو الـ API ولماذا يهمك كصاحب متجر؟

API اختصار لـ Application Programming Interface، وهو ببساطة "جسر رقمي" بين نظامين. بدله، كل نظام يعمل في عزلة تامة. بوجوده، متجرك يتكلم مع شركة الشحن مباشرة ودون تدخلك.

عملياً، هذا يعني: زبون يطلب منتجاً على متجرك، يتأكد الدفع أو الطلبية، فيُنشأ تلقائياً طرد في نظام شركة الشحن مع كل بيانات الزبون، وتصلك أنت رقم التتبع مباشرة في لوحة إدارة متجرك.

بلا نسخ، بلا لصق، بلا أخطاء بشرية.

ثانياً: أبرز شركات الشحن الجزائرية التي تدعم الـ API

أبرز شركات الشحن الجزائرية التي طورت واجهات برمجية للمطورين تشمل: Yalidine وZR Express وProcolis وEcotrack وMaystro Delivery. إليك نظرة سريعة على كل منها:

Yalidine Express — الأوسع انتشاراً

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

ZR Express عبر Procolis — موثوقة في الداخل

Procolis هي الواجهة البرمجية الرسمية لـ ZR Express. تدعم استعلام أسعار الشحن حسب الولاية، وإنشاء الطلبيات، وطباعة الوثائق. كثير من المطورين الجزائريين يفضلونها لاستقرارها.

Maystro Delivery — الأسرع نمواً

Maystro Delivery طورت واجهة برمجية تدعم إنشاء الطرود ومتابعتها وحتى إضافة المنتجات. تميزها أنها من الشركات التي تمددت بسرعة في الولايات الداخلية خلال السنتين الأخيرتين.

Ecotrack — شبكة موحدة لعدة مزودين

Ecotrack ليست شركة شحن بحد ذاتها بل منصة تجمع عدة مزودين من بينهم DHD وConexlog/UPS، مما يجعلها خياراً ذكياً لمن يريد الوصول إلى شبكة أوسع من خلال تكامل واحد.

ثالثاً: طريقة الربط — ثلاثة مسارات حسب مستواك التقني

المسار الأول: إذا كان متجرك على Shopify

هذا الأسهل والأسرع. لا تحتاج كتابة سطر كود واحد.

تطبيق Yalidine Express Algeria على Shopify يبسط عملية الشحن كلياً. بعد التثبيت، تدخل API ID وAPI Token مرة واحدة في الإعدادات، وتنتقل لقسم الطلبيات حيث تظهر كل الطلبيات غير المُعالجة في قائمة مرتبة مع خانات اختيار. تختار الطلبيات التي تريد شحنها، تحدد الولاية ونمط التوصيل، وتضغط إرسال.

النتيجة: الطلبيات ترسل تلقائياً لحساب Yalidine، ويُحدَّث Shopify بمعلومات التتبع فوراً لك وللعميل.

كيف تحصل على API ID وToken من Yalidine؟

سجّل كتاجر على yalidine.com، ثم توجه لقسم المطورين على yalidine.app/dev لتوليد API ID وToken الخاصين بك.

المسار الثاني: إذا كان متجرك على WooCommerce أو منصة PHP

هنا يحتاج الأمر مطوراً أو معرفة بسيطة ببرمجة PHP.

الخيار الأذكى هو مكتبة CourierDZ، وهي مكتبة PHP مفتوحة المصدر طورها مبرمجون جزائريون تحديداً لهذا الغرض.

CourierDZ مكتبة PHP مصممة لتبسيط ربط متاجر التجارة الإلكترونية بشركات الشحن الجزائرية، وتدعم ZR Express وProcolis وYalidine وEcotrack وMaystro Delivery عبر واجهة برمجية موحدة.

تخيل CourierDZ كـ "مترجم ذكي متعدد اللغات" يجلس بين موقعك الإلكتروني وشركات الشحن.

المشكلة الأساسية قبل وجود هذه الأداة:

لو كنت تملك متجراً إلكترونياً، وأردت التعامل مع 3 شركات شحن جزائرية (مثلاً: ياليدين، مايسترو، وبروكوليس):

• شركة ياليدين تتحدث "لغة رقمية خاصة بها" لاستقبال الطلبات.
• شركة مايسترو تتحدث "لغة رقمية مختلفة تماماً".
• شركة بروكوليس تتحدث "لغة ثالثة".

كمطور، كنت مجبراً على كتابة 3 أكواد مختلفة تماماً في موقعك لتستطيع إرسال الطرود لكل شركة، وإذا غيرت أي شركة نظامها، سيتعطل موقعك وتضطر لإعادة كتابة الكود من جديد. وهذا يأخذ وقتاً وجهداً كبيراً.

الحل: ماذا تفعل CourierDZ وكيف؟

CourierDZ هي أداة برمجية ومكتبة مطورة بلغة PHP (تحديداً كـ SDK أو Client)، صُممت خصيصاً لمطوري الويب وأصحاب المتاجر الإلكترونية في الجزائر.

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

بدل أن يقوم المطور بكتابة كود خاص ومختلف لكل شركة شحن (لأن نظام Yalidine يختلف عن Maystro وعن Procolis)، تأتي CourierDZ لتمنحه كوداً واحداً موحداً يتعامل مع الجميع.

ماذا تفعل CourierDZ بالضبط؟ (الميزات الأساسية)

1. دعم شركات شحن جزائرية متعددة (Multi-Provider Support):

   تدمج المكتبة في نظامها أشهر منصات الشحن في السوق الجزائري، مثل:

• Yalidine و Yalitec
• Maystro Delivery
• Procolis (الخاصة بوكالة ZR Express)

• Ecotrack (التي تعتمدها شركات مثل DHD و Conexlog وغيرهما)

واجهة برمجية موحدة (Unified API):

تمنح المطور طريقة ثابتة (Functions/Methods) للتعامل مع أي شركة، فإذا أراد إنشاء طرد، يستخدم نفس الأمر برمجياً بغض النظر عن الشركة المختارة.

إدارة كاملة للطلبيات (Order Management):

تتيح للموقع إرسال طلبات الشحن، تحديث بياناتها، أو إلغائها مباشرة من لوحة تحكم المتجر دون الحاجة لفتح موقع شركة الشحن.

استخراج ملصقات الشحن (Fetching Labels):

تقوم بجلب وثيقة الشحن (باركود الطرد) من سيرفر الشركة سواء على شكل رابط PDF أو كود مدمج (Base64) لطباعته مباشرة.

هذه الأداة تأتي لتوحد كل شيء. بدلاً من أن يتحدث موقعك مع كل شركة بلغتها المعقدة، موقعك سيتحدث مع CourierDZ فقط وبأمر واحد بسيط وموحد.

كيف يحدث ذلك على أرض الواقع؟

باختصار شديد:

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

التثبيت بسيط عبر Composer:

composer require piteurstudio/courierdz

ثم ربط الشركة التي تريدها:

// لـ Yalidine
$credentials = ['token' => 'TOKEN_هنا', 'key' => 'KEY_هنا'];

// لـ ZR Express عبر Procolis
$credentials = ['id' => 'ID_هنا', 'token' => 'TOKEN_هنا'];

// لـ Maystro
$credentials = ['token' => 'TOKEN_هنا'];

$shipping = CourierDZ::provider(ShippingProvider::YALIDINE, $credentials);

الميزة الرئيسية لـ CourierDZ هي الواجهة الموحدة، يعني نفس الكود يعمل مع أي شركة شحن تدعمها المكتبة دون تغيير منطق التطبيق. وهذا يعني أنك لو قررت تغيير شركة الشحن لاحقاً، تغيير سطر واحد يكفي.

المسار الثالث: إذا كنت تبني متجراً من الصفر بـ JavaScript/Node.js

مكتبة yalidine npm تتيح التكامل الكامل مع Yalidine بكود JavaScript نظيف وبسيط:

رابعاً: ماذا يحدث بعد إنشاء الطرد؟

هذا الجزء يفوّته كثيرون. الـ API ليس فقط لإنشاء الطرود، بل لمتابعة دورة حياتها كاملة.

طباعة البوالص تلقائياً

Yalidine وEcotrack يدعمان طباعة وثيقة الشحن مباشرة من الـ API، يعني يمكنك بناء زر واحد في لوحة إدارتك يولد PDF البوليصة فوراً بدون دخول موقع شركة الشحن.

متابعة حالة التوصيل

كل شركة تُعيد حالة الطرد في الاستجابة: قيد المعالجة، في الطريق، تم التسليم، مرتجع. يمكنك ربط هذه الحالات تلقائياً بإشعارات SMS أو واتساب لزبائنك.

إدارة الدفع عند الاستلام

Yalidine تجمع المبلغ من العميل عند التسليم ثم تحوله لك يومياً مع خصم عمولة COD تبلغ حوالي 1.5%. يمكن للـ API تتبع هذه المبالغ وتسجيلها تلقائياً في نظام محاسبتك.

خامساً: الحل الأشمل — استخدام عدة شركات في آنٍ واحد

هذا ما يفعله أصحاب المتاجر الكبيرة وهو سرّهم في رفع نسبة التوصيل.

يمكنك استخدام عدة شركات شحن في وقت واحد واختيار الأنسب لكل طلبية. الاستراتيجية الذكية: ابدأ بشركة واحدة، قيّم أداءها بعد شهر، ثم أضف شركة ثانية أو ثالثة لتغطية كل ولايات الجزائر.

بمعنى عملي: ياليدين قوية في الشمال والمدن الكبرى، ZR Express قوية في الداخل والمناطق النائية. متجرك يختار تلقائياً الأنسب حسب ولاية الزبون.

هذا ما تتيحه CourierDZ تحديداً: واجهة واحدة تتحكم في كل الشركات دون تعقيد.

سادساً: مشاكل شائعة وكيف تتجنبها

مشكلة CORS في التطبيقات الأمامية:

الـ API الأصلي لـ Yalidine يُحجب بواسطة CORS حين تستدعيه مباشرة من المتصفح. الحل هو بناء طبقة وسيطة على السيرفر تستقبل الطلب وترسله لـ Yalidine بدلاً منك. لا تستدع أبداً الـ API من كود JavaScript الأمامي مباشرة.

حماية بيانات الاعتماد:

لا تضع API Token مباشرة في كود الـ Frontend أو تشاركه علنياً. ضعه في متغيرات البيئة .env على السيرفر فقط. Token مسرّب يعني أي شخص يستطيع إنشاء طرود على حسابك.

التعامل مع حالات الفشل:

الـ API يُخفق أحياناً لأسباب خارجة عن إرادتك: سيرفر الشركة متوقف، اتصال الإنترنت منقطع، بيانات الزبون غير صحيحة. بنِ دائماً منطق إعادة المحاولة في كودك، وسجّل كل الأخطاء في ملف Log حتى لا تضيع طلبية دون أن تعرف.

خاتمة: الربط ليس رفاهية، بل ضرورة

إذا كان متجرك يعالج أكثر من 10 طلبيات يومياً وما زلت تدخلها يدوياً، فأنت تخسر وقتاً ثميناً كل يوم وتعرض نفسك لأخطاء بشرية مكلفة.

ربط الـ API ليس بالصعوبة التي تتخيلها. على Shopify هو مجرد تثبيت تطبيق وإدخال مفتاحين. على PHP هو تثبيت مكتبة وكتابة عشرين سطراً. والعائد على الاستثمار من حيث الوقت يتحقق من اليوم الأول.

ابدأ بـ Yalidine لأنها الأكثر توثيقاً والأوسع انتشاراً، واستخدم CourierDZ إذا أردت المرونة في التنقل بين الشركات لاحقاً.

متجرك يستحق بنية تقنية تُمكّنك من التركيز على البيع، لا على إدخال البيانات.

نصائح ذهبية لتفادي المشاكل التقنية في الجزائر