نظرة عامة على API

يوفّر Logistall واجهة REST صغيرة للقراءة فقط (/api/v1/*) لدمج بيانات الشحنات والعملاء والفواتير في أنظمة أخرى، إلى جانب ويب هوك صادرة لتغييرات حالة الشحنات في وقت شبه فعلي. يوثّق هذا القسم كليهما، إضافة إلى نقطة نهاية رابط التتبع العامة (غير المصادَق عليها).

إذا كنت تبحث عن الصفحات داخل التطبيق التي تُولَّد منها بيانات هذه الواجهة — الشحنات والعملاء والفواتير ومفاتيح API — فانظر دليل المستخدم بدلًا من هذا القسم. هذا القسم موجّه للمطوّرين الذين يدمجون برمجيًا.

عنوان الأساس

تُخدَّم الواجهة من اسم مضيف إنتاجي واحد — لا يوجد نطاق فرعي لكل شركة. يُحدَّد المستأجر حصرًا عبر مفتاح API الذي تقدّمه، لا عبر المضيف الذي تتصل به:

https://tenant.logistall.cloud/api

كل نقاط النهاية أدناه نسبية إلى هذا الأساس — فمثلًا، ‏GET /v1/shipments تعني GET https://tenant.logistall.cloud/api/v1/shipments.

قراءة فقط، الإصدار v1

الواجهة العامة حاليًا للقراءة فقط: كل نقطة نهاية تحت /v1/* هي GET. لا توجد طريقة لإنشاء السجلات أو تحديثها أو حذفها عبر هذه الواجهة — كل الكتابة تتم عبر تطبيق Logistall على الويب. يوجد إصدار واحد فقط هو v1، ولم تُعتمد بعدُ أي خطة إصدارات تتجاوز هذه البادئة.

المصادقة

كل نقطة نهاية تحت /v1/* تتطلب مفتاح API. انظر المصادقة لمعرفة كيفية إنشاء مفتاح وتقديمه مع الطلبات.

صيغة الاستجابة

كل الاستجابات JSON. مفاتيح الكائنات بصيغة camelCase بغضّ النظر عن أسماء أعمدة قاعدة البيانات الأصلية (فمثلًا، عمود shipment_number في قاعدة البيانات يُعاد باسم shipmentNumber).

نقاط نهاية القوائم تعيد مصفوفة JSON مجردة — لا يوجد كائن غلاف ولا عدّاد total.

تقسيم الصفحات

تقبل نقاط نهاية القوائم معاملي استعلام:

المعامل	الافتراضي	الحد الأقصى	ملاحظات
limit	50	200	القيم فوق 200 تُقتصّ إلى 200. القيم غير الرقمية أو الأقل من 1 ترجع إلى الافتراضي.
offset	0	—	القيم الأقل من 0 تُرفع إلى 0.

لا يوجد تقسيم صفحات قائم على المؤشر (cursor) — استخدم offset وأعد الجلب. النتائج مرتّبة من الأحدث إلى الأقدم (حسب تاريخ الإنشاء) ما لم يُذكر خلاف ذلك في نقطة النهاية.

الأخطاء

الأخطاء دائمًا كائن JSON يحوي سلسلة error واحدة:

{ "error": "Invalid API key" }

رموز الحالة الشائعة:

الحالة	المعنى
401	مفتاح API مفقود أو مشوّه أو غير صالح.
404	السجل المطلوب غير موجود (أو لا يخص المستأجر الذي يُحلّ إليه مفتاحك).
500	خطأ غير متوقع في الخادم أو قاعدة البيانات.

حدود المعدل

لا يُفرض حاليًا أي حد معدل لكل مفتاح على نقاط النهاية /v1/*. تقييد المعدل الوحيد في المنصة اليوم ينطبق على نقاط نهاية تسجيل الدخول/إعادة تعيين كلمة المرور التي يستخدمها تطبيق الويب نفسه، لا على المسارات المصادَق عليها بمفتاح API الموثّقة هنا. قد يتغير هذا — فقد يُستحدث حد معدل على /v1/* مستقبلًا — لذا لا تبنِ تكاملًا يفترض حجم طلبات غير محدود، لكن لا يوجد اليوم رقم موثّق تصمّم على أساسه.

نقاط النهاية في لمحة

الطريقة	المسار	الوصف
GET	/v1/shipments	قائمة الشحنات
GET	/v1/shipments/:id	شحنة واحدة مع سجلّها الزمني للتتبع
GET	/v1/customers	قائمة العملاء
GET	/v1/invoices	قائمة الفواتير

إضافة إلى:

• الويب هوك — اشترك في أحداث shipment.status_changed بدل الاستطلاع الدوري.
• التتبع العام — الرابط غير المصادَق عليه الذي يستخدمه العملاء لمتابعة حالة شحنة.