لماذا تكامل API ضروري
البوابة لديها واجهة ويب للإدخال اليدوي، لكن للشركات التي ترسل أكثر من 5-10 إشعارات تسليم يوميًا، الإدخال اليدوي غير مستدام. يتيح تكامل API الإنشاء التلقائي وتأكيد الاستلام ومزامنة الحالة.
بنية النظام
- البروتوكول: HTTPS (TLS 1.2+)
- الصيغة: JSON
- المصادقة: شهادة إلكترونية مؤهلة (TLS متبادل) + مفتاح API
- التوثيق: متاح على البوابة بعد التسجيل
نقاط API النهائية الرئيسية
| النقطة النهائية | الطريقة | الوصف |
|---|---|---|
| /api/v1/delivery-notes | POST | إنشاء إشعار تسليم إلكتروني جديد |
| /api/v1/delivery-notes/{id} | GET | عرض إشعار تسليم واحد |
| /api/v1/delivery-notes | GET | قائمة إشعارات التسليم (مع فلاتر) |
| /api/v1/receipt-notes | POST | إنشاء إشعار استلام (تأكيد الاستلام) |
| /api/v1/delivery-notes/{id}/status | GET | حالة إشعار التسليم |
| /api/v1/delivery-notes/{id}/pdf | GET | نسخة PDF للطباعة |
التكامل مع أنظمة ERP الشائعة
SAP
استخدم SAP PI/PO أو SAP Integration Suite. تعيين من وحدة SD (الشحن/وثيقة التسليم) إلى صيغة API.
Microsoft Dynamics
استخدم Power Automate أو موصلات مخصصة. تعيين من أوامر البيع/النقل.
أنظمة ERP المحلية
معظم حلول ERP المحلية (Pantheon، Lidder، Bild، 4D) تطور أو لديها وحدات إشعارات تسليم إلكترونية.
مشاكل التكامل الشائعة
- الشهادة غير مُعدة بشكل صحيح -- يجب أن تكون على الخادم وليس محطة العمل فقط
- صيغة تاريخ خاطئة -- يتوقع API صيغة ISO 8601 (YYYY-MM-DDTHH:mm:ss)
- حقول مطلوبة ناقصة -- يُعيد API خطأ 400 مع قائمة الحقول
- المستلم غير مسجل -- يجب أن يكون المستلم موجودًا في النظام
- مهلة مع شحنات كبيرة -- قسّم أكثر من 100 عنصر على عدة إشعارات
إشعارات Webhook
تدعم البوابة webhooks لتحديثات الحالة في الوقت الفعلي -- تأكيد الاستلام والقبول/الرفض وتحذيرات المواعيد النهائية.
الخاتمة
تكامل API هو النهج المستدام الوحيد للعمليات كبيرة الحجم.
لدى Arhivix تكامل جاهز مع البوابة -- وصّل ERP بـ Arhivix وهو يتواصل مع البوابة نيابة عنك.
