واجهة برمجية مجانية للتوصيل في الجزائر: دليل DZShip للمطورين

نعم، توجد واجهة برمجية مجانية للتوصيل في الجزائر: إنها DZShip التي تشغّلها DZBuild على freeship.dzbuild.com. تتيح إنشاء طرود بالدفع عند الاستلام وتتبّعها وطلب سعر التوصيل وعرض مكاتب التوصيل (stop desk) لدى 99 شركة توصيل جزائرية، بصيغة طلب واحدة. وحسب الأسئلة الشائعة في موقع الخدمة، التي اطّلعنا عليها في 3 نوفمبر 2026، فلا تسجيل ولا مفتاح API ولا رسوم على الطرد.

الفكرة بسيطة: يحمل كل طلب بيانات دخولك الخاصة لدى شركة التوصيل (Yalidine أو ZR Express أو NOEST أو إحدى الشركات العاملة على Ecotrack…). يُنشأ الطرد على حسابك لدى الشركة، فتفوترك على التوصيل كما تفعل اليوم وتحوّل إليك المبالغ المحصّلة. وتؤكد DZBuild أن بيانات الدخول تُستعمل لطلب واحد فقط ولا تُخزَّن أبدًا.

هذا الدليل موجّه للمطورين والوكالات الذين يريدون ربط موقعهم بشركات التوصيل في الجزائر دون وصلة برمجية لكل شركة. أنت تاجر بلا مطوّر؟ انتقل إلى قسم المقارنة بين DZShip ومتجر DZBuild.

باختصار:

• مجانية: لا تسجيل ولا مفتاح API ولا رسوم على الطرد، أما رسوم التوصيل فتبقى مستحقة لشركة التوصيل.
• التغطية: 99 شركة توصيل، منها عائلة Yalidine وZR Express (على Procolis والمنصة الجديدة) وMaystro وNOEST وZimou وElogistia و82 شركة تعمل على Ecotrack.
• الوظائف: إنشاء الطرود، والتتبّع عبر 14 حالة موحّدة، والأسعار، ومكاتب التوصيل، والولايات والبلديات.
• الاختبار: شركة توصيل تجريبية اسمها «sandbox» تتحقق من طلباتك دون إنشاء أي طرد.
• الأمان: الاستدعاء من خادمك لحماية بيانات دخولك، وحصص استعمال معقولة حسب عنوان IP، ويبقى التحصيل عند الاستلام لدى شركة التوصيل.

واجهة برمجية مجانية للتوصيل في الجزائر: ما هي DZShip؟

أعلنت DZBuild عن DZShip في تدوينة مؤرخة في 12 جويلية 2026، وقدّمتها على أنها واجهة برمجية عامة ومجانية للتوصيل في الجزائر. والسبب الذي تذكره الشركة أن لكل شركة توصيل جزائرية واجهة برمجية مختلفة، وأغلبها بلا توثيق.

ثلاث نقاط ينبغي معرفتها قبل البدء:

• المجاني هو الوصول إلى الواجهة البرمجية. تواصل شركة التوصيل فوترة كل عملية توصيل حسب عقدك معها.
• جزء فقط مفتوح المصدر. أدلة شركات التوصيل ومكتبات العملاء منشورة برخصة MIT، ومجموعة بيانات الولايات الـ58 والبلديات الـ1,541 (بالفرنسية والعربية، بصيغتي JSON وCSV) في الملك العام (CC0). أما الخدمة المستضافة نفسها (المحوّلات والبوابة والبنية التحتية) فملك لـDZBuild، ولا يمكنك تثبيتها على خادمك.
• الجمهور المستهدف واسع. حسب الموقع، تخاطب DZShip كل من يبني حلًا للسوق الجزائرية: متجر إلكتروني، أو صفحة هبوط، أو نظام ERP، أو جدول طلبيات على Google Sheets.

شركات التوصيل المدعومة: API ياليدين وAPI زد ار اكسبرس وMaystro وEcotrack

يعيد المسار GET /v1/couriers لكل شركة مفتاحها ومنصتها وبيانات الدخول التي تشترطها. وهذه أبرزها، مع ما يجب معرفته عند الربط:

• Yalidine وشبكاتها الشقيقة (Yalitec وGuepex وEasy & Speed وEconomiqua وWe Can)
• بيانات الدخول: apiId وapiToken، إضافة إلى ولاية الانطلاق (options.fromWilaya).
• للعلم: حسب DZBuild، يتطلب الوصول إلى API ياليدين عادةً حسابًا مهنيًا موثّقًا. وتحدّد شروط النقل لدى Yalidine سقف المبلغ المحصّل عند الاستلام بـ150,000 دج للطرد. التفاصيل في دليلنا عن أسعار Yalidine والتوصيل إلى المكتب.
• ZR Express على منصتيها
• Procolis (الواجهة القديمة): token وkey. لا قائمة لمكاتب التوصيل عبر الواجهة البرمجية، إذ يعيد طلب المكاتب الخطأ 422 NOT_SUPPORTED.
• المنصة الجديدة zrexpress.app: apiKey وtenantId. وهي المنصة الواجب اعتمادها إذا كان الزبون سيختار مكتب توصيل باسمه.
• للعلم: تحدّد ZR Express أيضًا سقف الدفع عند الاستلام بـ150,000 دج للطرد. راجع دليلنا عن ZR Express وProcolis.
• Maystro Delivery
• تدعمها DZShip، وتُوجَّه طرود التوصيل إلى المكتب حسب البلدية، دون معرّف للمكتب.
• NOEST
• بيانات الدخول: API Token وUser GUID، من لوحة تحكم التاجر.
• للعلم: ينبّه دليل DZShip الخاص بـNOEST إلى أن الطلبيات المنشأة برمجيًا تبقى مسودات ما لم تُشغَّل خطوة تأكيد منفصلة، ويذكر أن NOEST تقبل عبر الواجهة فتح الطرد قبل الدفع والاستبدال.
• الشركات العاملة على Ecotrack (82 شركة حسب DZShip، منها DHD وConexlog وMSM Go وRocket وWorld Express وAnderson)
• بيانات الدخول: رمز token واحد لكل شركة.
• للعلم: Ecotrack برنامج تسيير وليست شركة توصيل. ويمكن استدعاء شركة تعمل على Ecotrack وغير مدرجة في القائمة عبر options.baseUrl، بشرط أن يكون نطاقها من نوع .ecotrack.dz. وتُوجَّه طرود التوصيل إلى المكتب حسب البلدية. ولمعرفة كيفية ربط Ecotrack برمجيا، راجع دليلنا عن Ecotrack.
• Zimou Express وElogistia وColivraison وغيرها (Ecom Delivery وNear Delivery وMDM)
• توجّه Elogistia طرود التوصيل إلى المكتب حسب البلدية. أما Colivraison، شأنها شأن ZR Express على Procolis، فلا تنشر قائمة مكاتبها عبر الواجهة البرمجية.

لا تغيّر DZShip شروط شركات التوصيل، ولاختيار الأنسب راجع مقارنتنا بين شركات التوصيل في الجزائر.

كيف تعمل: بيانات الدخول والمسارات والبيئة التجريبية

يتبع كل طلب البنية نفسها: courier (مفتاح مأخوذ من /v1/couriers)، وcredentials (الحقول الخاصة بتلك الشركة)، ثم بيانات العملية. وتغيير شركة التوصيل لا يتطلب سوى تعديل هذين الحقلين.

المسارات المتاحة:

• POST /v1/orders: إنشاء طرد.
• POST /v1/track: الحالة الحالية والسجل الكامل للأحداث.
• POST /v1/rates: رسوم التوصيل والإرجاع لمسار معيّن.
• POST /v1/desks: مكاتب التوصيل لدى شركة ما في ولاية معيّنة.
• GET /v1/couriers و/v1/wilayas و/v1/communes: البيانات المرجعية.
• GET /openapi.json و/llms.txt: العقد الكامل، بصيغة تقرؤها الآلة أو وكيل ذكاء اصطناعي.

قواعد التحقق التي تُفشل الطلبات الأولى غالبًا:

• deliveryType قيمته «home» للتوصيل إلى المنزل أو «stopdesk» للتوصيل إلى المكتب. وللمكتب، احصل على معرّفه عبر /v1/desks وأرسله في order.stopDeskId.
• phone رقم هاتف نقال جزائري (05 أو 06 أو 07).
• wilayaCode من 1 إلى 58. صارت الجزائر تضم 69 ولاية منذ أفريل 2026، لكن حسب DZShip لا تقبل أي شركة توصيل بعدُ رمزًا يتجاوز 58. ويعيد GET /v1/wilayas?all=1 الولايات الـ69 كلها، ومع كل ولاية رمز «shipAs» الواجب استعماله.
• communeName يطابق الكتابة الفرنسية التي تعتمدها شركة التوصيل: خذه من /v1/communes لا من الذاكرة.
• codAmount عدد صحيح بالدينار الجزائري، والقيمة 0 تعني طردًا مدفوعًا مسبقًا.

يحوّل التتبّع مصطلحات كل شركة إلى 14 حالة موحّدة، مع تسميات بالفرنسية والعربية: created، pending_pickup، picked_up، in_transit، at_hub، out_for_delivery، delivery_attempted، delivered، on_hold، return_in_transit، returned، cancelled، lost وunknown. مع الاحتفاظ بالحالة الأصلية للشركة.

مثال: إنشاء طرد بالدفع عند الاستلام وتتبّعه وتسعيره عبر البيئة التجريبية

إليك المسار الأدنى، استنادًا إلى توثيق المسارات:

1. اختبر دون حساب. أرسل POST /v1/orders مع courier بقيمة «sandbox» ودون credentials. وضع في order: مستلمًا (الاسم الكامل، والهاتف 0551234567، وwilayaCode 16، وcommuneName «Bab Ezzouar»)، وdeliveryType «home»، وقائمة منتجات productList، وcodAmount بقيمة 4500. تتحقق البيئة التجريبية من الحقول كشركة توصيل حقيقية، دون إنشاء أي طرد.
2. انتقل إلى شركة توصيل حقيقية. استبدل قيمة courier بـ«yalidine»، وأضف credentials (apiId وapiToken)، وoptions.fromWilaya بقيمة 16، وعنوانًا (addressLine)، ومرجعك الخاص في reference، مثل «ORD-1042». يتضمن الرد رقم التتبّع trackingNumber والحالة «created» ومرجعك.
3. تتبّع الطرد. أرسل POST /v1/track بنفس courier وcredentials ومعهما trackingNumber، فتتلقى الحالة الموحّدة وقائمة الأحداث من الأقدم إلى الأحدث.
4. احسب السعر. أرسل POST /v1/rates مع query: fromWilaya 16 وtoWilaya 31 وtoCommune «Oran» وdeliveryType «home». ويقبل الحقل query.tier القيمة «express» (الافتراضية) أو «economic» حين تعرض شركة التوصيل خيارًا أبطأ وأرخص.
5. اقترح مكتب توصيل. أرسل POST /v1/desks مع الولاية المقصودة. وفي البيئة التجريبية يتضمن الرد مكتبًا تجريبيًا في وهران.

تنشر DZBuild مكتبات عملاء برخصة MIT لـNode.js (حزمة npm باسم «dzship»، الإصدار 1.2.0 في 3 نوفمبر 2026، بلا تبعيات ومع أنواع TypeScript)، ولـPHP وPython وRuby. وفي المستودع أمثلة لـLaravel وWooCommerce وDjango وRails وGoogle Sheets.

حصص الاستعمال والأمان وأفضل الممارسات

حصص الاستعمال المعقول، كما اطّلعنا عليها في 3 نوفمبر 2026:

• 200 طلبية في الساعة و1,000 في اليوم لكل عنوان IP؛
• 10 طلبيات في اليوم لرقم المستلم نفسه؛
• 60 طلب تتبّع في الدقيقة و5,000 في اليوم لكل عنوان IP؛
• 60 طلب تسعير و60 طلب قائمة مكاتب في الدقيقة لكل عنوان IP.

عند تجاوزها تردّ الواجهة بالرمز HTTP 429: انتظر عدد الثواني المذكور في الترويسة Retry-After ثم أعد المحاولة. وترسل المسارات المرجعية ترويسة Cache-Control، فخزّن نتائجها مؤقتًا بدل استدعائها باستمرار.

أفضل الممارسات:

• استدعِ الواجهة من خادمك لا من المتصفح. موقف DZBuild صريح: ستصبح بيانات دخولك مقروءة لأي زائر. مرّ دائمًا عبر خادمك.
• تحقّق قبل إعادة إرسال طلب الإنشاء. لا تعيد DZShip محاولة إنشاء طرد تلقائيًا أبدًا، لأن كل محاولة جديدة تنشئ طردًا مكرّرًا. أرسل مرجعك الخاص في reference وتحقّق قبل إعادة الإرسال.
• أكّد طرودك لدى NOEST. من دونه تبقى طرودك مسودات.

كيف تعمل DZShip مع شركة التوصيل:

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

DZShip أم متجر DZBuild: ماذا تحتاج فعلًا؟

اختر DZShip إن كان لديك موقع أو نظام ERP ومطوّر يتولى الاستدعاءات من الخادم.

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

رأي هيئة التحرير: DZBuild خيارنا الأول للتجار الجزائريين، ومعاييرنا كلها قابلة للتحقق على صفحاتها:

• الدفع عند الاستلام مدمج في كل متجر، مع متجر ولوحة تحكم بالعربية أو الفرنسية؛
• شركات التوصيل: أكثر من 102 شركة توصيل حسب الشركة (Yalidine وZR Express وNOEST وMaystro وشبكة Ecotrack…)، وقوائم مكاتب توصيل تُزامَن من 14 شركة؛
• الأسعار كما اطّلعنا عليها في 3 نوفمبر 2026 على صفحة الأسعار: Pro بـ1,000 دج شهريًا، وUnlimited بـ2,500 دج، وEnterprise ابتداءً من 5,500 دج، مع تجربة Pro لمدة 3 أيام دون بطاقة (الخطة المجانية مغلقة أمام الحسابات الجديدة)؛
• بلا عمولة ولا رسوم على الطلبية حسب DZBuild، مع تصدير إلى Google Sheets في كل الخطط وREST API في خطة Enterprise.

كود الخصم: WELCOME15، خصم 15% على أول دفعة.

لتبدأ، اتبع دليلنا لإنشاء متجر على DZBuild خطوة بخطوة أو اطّلع على بطاقة DZBuild.

الخطوات التالية

1. اعرض شركات التوصيل وبيانات دخولها عبر GET /v1/couriers.
2. اختبر في البيئة التجريبية حتى تختفي أخطاء التحقق.
3. اربط شركة توصيل حقيقية من خادمك، مع مرجعك الخاص.
4. خزّن الولايات والبلديات مؤقتًا وتعامل مع الرمز 429.

وتجمع بطاقة DZShip المعلومات المتحقَّق منها عن الخدمة.