دمج ياليدين في موقعك الإلكتروني: دليل تقني للواجهة البرمجية

دمج ياليدين في موقعك يعني استدعاء واجهتها البرمجية من نوع REST من خادمك لإنشاء شحنة، ثم الاستعلام بانتظام عن حالة الطرد — لا توجد إشعارات تلقائية. يغطّي هذا الدليل المصادقة، وإنشاء الطرود، والتتبّع، والحدود الحقيقية للواجهة البرمجية، دون وسيط.

قبل البدء

ثلاثة شروط أساسية، بالترتيب:

1. حساب تاجر نشط لدى ياليدين. الوصول إلى الواجهة البرمجية ليس مفتوحًا للعموم؛ يتطلب حسابًا مهنيًا مصادقًا عليه أصلًا.
2. معرّفات الواجهة البرمجية. تُولَّد من القسم الخاص بالمطوّرين في لوحة التحكّم، على yalidine.app. قيمتان يجب استرجاعهما: API ID و API Token.
3. خادم قادر على استدعاء الواجهة البرمجية. تحجب الواجهة البرمجية الطلبات العابرة للمصدر (CORS): لا يمكن استدعاء api.yalidine.app مباشرة من جافاسكريبت المتصفح. يجب أن ينطلق كل استدعاء من الخلفية (backend) الخاصة بك، لا أبدًا من جهة الزبون — ما يمنع أيضًا كشف رمزك في كود المتجر المصدري العلني.

لا توجد بيئة اختبار (sandbox) موثّقة. استدعاءاتك الأولى تُنشئ شحنات حقيقية: تحقّق من تكاملك بطرد حقيقي بمبلغ منخفض قبل ربط تدفّق الطلبات الكامل.

المصادقة

الواجهة البرمجية من نوع REST، استجابات JSON، عنوان أساسي https://api.yalidine.app/v1/. يجب أن يحمل كل طلب رأسيْن HTTP:

X-API-ID: your_api_id
X-API-TOKEN: your_api_token
Content-Type: application/json

دون هذين الرأسين، تجيب الواجهة البرمجية بـ 401 Unauthorized مع رسالة صريحة (API ID and/or Token must be specified). خزّن هاتين القيمتين مثل أي سرّ بيئي — أبدًا في ملف مرفوع على مستودع أو مُرسَل إلى المتصفح.

إنشاء شحنة

يتم إنشاء الطرود عبر POST /v1/parcels، بجدول من الكائنات — تقبل الواجهة البرمجية الإنشاء الجماعي في استدعاء واحد. الحقول المهمّة لأول إرسال:

الحقل	الدور
order_id	مرجعك الخاص بالطلب، للربط مع قاعدة بياناتك
firstname, familyname, contact_phone	معلومات الاتصال بالمستقبل
to_wilaya_name, to_commune_name, address	عنوان التوصيل
from_wilaya_name	ولاية الشحن (مستودعك)
price	المبلغ المطلوب تحصيله عند التوصيل، بالدينار (0 إلى 150.000)
is_stopdesk + stopdesk_id	توصيل في نقطة استلام عوض المنزل؛ معرّف نقطة الاستلام يأتي من نقطة الوصول /centers
freeshipping	يوضّح إن كانت مصاريف التوصيل على عهدة الزبون أو مستوعبة منك
weight, length, width, height	أبعاد الطرد، تُستخدم لحساب التعريفة

تُرجع الاستجابة رمز تتبّع (tracking، مثلًا yal-12345A) يجب الاحتفاظ به للخطوة التالية. يجب أن يتطابق to_wilaya_name و to_commune_name تمامًا مع التسميات المُرجَعة من نقاط الوصول المرجعية أدناه — خطأ كتابي في اسم البلدية يُفشل الإنشاء.

عمليًا، يبدو استدعاء الإنشاء كالتالي:

POST https://api.yalidine.app/v1/parcels/
X-API-ID: your_api_id
X-API-TOKEN: your_api_token
Content-Type: application/json

[
  {
    "order_id": "CMD-4821",
    "from_wilaya_name": "Alger",
    "firstname": "Karim",
    "familyname": "B.",
    "contact_phone": "0555xxxxxx",
    "to_wilaya_name": "Oran",
    "to_commune_name": "Es Senia",
    "address": "Cité 500 logements, bloc B",
    "product_list": "1x غطاء هاتف",
    "price": 2500,
    "is_stopdesk": false,
    "freeshipping": false,
    "weight": 1
  }
]

إذا كان حقل إلزامي ناقصًا أو لم تتطابق تسمية بلدية مع أي شيء في المرجع، تجيب الواجهة البرمجية برمز خطأ ورسالة صريحة عوض إنشاء طرد بعنوان خاطئ — عالج هذه الاستجابة في كودك عوض افتراض نجاح الاستدعاء. عند حجم يبلغ عشرات الطلبات يوميًا، يمنع التحقّق المنهجي من أسماء الولايات/البلديات قبل الاستدعاء (بمقارنة مع قوائم محفوظة مؤقتًا) معظم هذه الرفوضات.

تتبّع حالة طرد

لا وِبهوك من جهة ياليدين: يجب أن يستعلم خادمك عن الواجهة البرمجية، لا العكس. يتم التتبّع عبر سجل الحالات (GET /v1/histories/)، القابل للتصفية حسب الطرد.

الحالات المرصودة من جهة شركة التوصيل، بترتيب دورة الحياة العادية:

1. لم يُشحَن بعد
2. تم استلامه
3. تم شحنه
4. خارج للتوصيل
5. تم التسليم (أو: فشل التوصيل، أُرجِع إلى البائع)

تُضاف حالة دفع منفصلة (not-ready, ready, receivable, payed) تشير إلى تقدّم تحويل المبلغ المُحصَّل، مختلفة عن حالة توصيل الطرد نفسه.

عمليًا: برمج مهمّة مجدولة تستعلم عن الطرود الجارية كل بضع ساعات عوض كل دقيقة — تفرض الواجهة البرمجية حصصًا في الثانية والدقيقة والساعة واليوم (مرئية في رؤوس الاستجابة)، والقيم الدقيقة غير منشورة. استدعاء متكرر جدًا يُطلق 429 قبل أن تحدّد الحد الحقيقي.

لا تعيد الاستعلام عن كامل سجل طلباتك في كل مرور: قيّد الطلب على الطرود التي لم تصل حالتها النهائية بعد ("تم التسليم"، "أُرجِع إلى البائع"). في متجر بحجم مرتفع، هذا ما يميّز بين مهمّة مجدولة تبقى ضمن الحصص وأخرى تتجاوزها منذ الساعة الأولى.

نقاط الوصول المرجعية

قبل إنشاء الطرود، استعلم عن هذه النقاط مرة واحدة واحفظ النتائج مؤقتًا على خادمك — تتغيّر نادرًا:

نقطة الوصول	المحتوى
GET /v1/wilayas/	قائمة الولايات المخدومة
GET /v1/communes/	البلديات، مع مؤشرات has_stop_desk و is_deliverable
GET /v1/centers/	نقاط الاستلام (stop-desk)، مع معرّفها المستخدَم في stopdesk_id
GET /v1/deliveryfees/	جدول التعريفة حسب الولاية

استخدام هذه التسميات الدقيقة في استمارات طلباتك يمنع معظم فشل إنشاء الطرود المرتبط بعنوان مصاغ بشكل خاطئ. حدّث هذا الحفظ المؤقت مرة في الأسبوع، لا في كل طلب: قائمة الولايات والبلديات المخدومة تتغيّر نادرًا، وقراءتها في كل مرور تستهلك حصتك دون فائدة.

الحدود التي يجب معرفتها قبل الالتزام

ثلاث نقاط تغيّر طريقة بناء التكامل:

• لا وِبهوك. يعتمد كل إشعار توصيل على الاستعلام الدوري، أبدًا على إشعار تدفعه ياليدين إلى خادمك.
• لا حزمة تطوير رسمية (SDK). لا تنشر ياليدين مكتبة عميل. توجد حزم مجتمعية لـ Python، وJavaScript/TypeScript وLaravel، وكذلك إضافات WordPress/WooCommerce — مفيدة للانطلاق بسرعة، لكنها ليست مُصانة من طرف ياليدين نفسها: تحقّق من نشاطها قبل الاعتماد عليها في الإنتاج.
• لا بيئة اختبار. كل اختبار لإنشاء طرد هو شحنة حقيقية. اعزل اختباراتك بمعرّف order_id قابل للتمييز وألغِ طرود الاختبار بسرعة.

بعد ربط التكامل

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

لوضع هذا التكامل ضمن تدفّق الدفع عند الاستلام الكامل — التأكيد الهاتفي، حساب الهامش مع نسبة الإرجاع، الاختيار بين عدة شركات توصيل — راجع دليل الدفع عند الاستلام ومقارنة شركات التوصيل في الجزائر. تفاصيل باقات الاشتراك موجودة في صفحة الأسعار.