واجهة يقين لشركات الشحن (API)
اربط شركة الشحن أو التوصيل بيقين مرة واحدة، فتصلك شحنات كل التجار الذين يفعّلونك، وتعود حالاتها إليهم تلقائياً.
لمن هذه الواجهة؟
لشركات الشحن والتوصيل (محلية ودولية، توصيل في نفس اليوم، الدفع عند الاستلام) التي تريد استقبال شحنات التجار الذين يستخدمون يقين في السعودية ومصر ودول المنطقة، دون ربط كل تاجر على حدة.
كيف تعمل
- التاجر يفعّل شركتكم في يقين (الشحن ← الإعدادات ← شركات الشحن) ويضيف رقم حسابه لديكم.
- عند شحن طلب يضغط التاجر «إرسال إلى …» فتظهر الشحنة عندكم بحالة «جديدة» مع المرسل والمستلم وموقعه على الخريطة والطرود ومبلغ التحصيل.
- تقبلون الشحنة وترسلون رقم التتبع ورابط الملصق (أو ترفضونها مع السبب).
- ترسلون كل تغيير في الحالة: تم الاستلام، في الطريق، خرجت للتوصيل، محاولة فاشلة، تم التسليم مع إثبات التسليم.
- عند تحويل مبالغ التحصيل للتجار ترسلون بيان التحويل، فيراه التاجر على شحناته.
خطوات الربط
- اطلب حساباً: أرسل لنا من صفحة «اتصل بنا» (الموضوع: شراكة) اسم الشركة والدول والخدمات والشخص المسؤول.
- بيانات الدخول التجريبية: نرسل لكم
client_idوclient_secretللبيئة التجريبية، ترى شحنات الشركات التجريبية فقط. - جرّب في Postman: نزّل المجموعة وملف البيئة، الصق بيانات الدخول، ثم شغّل الطلبات بالترتيب: تسجيل الدخول، الشحنات الجديدة، القبول، الحالات، التحصيل. المجموعة تسجل الدخول وحدها.
- اربط نظامكم: استخدم المرجع الكامل (OpenAPI 3) لبناء الربط في نظامكم، ويمكنكم استقبال إشعارات الويب هوك بدل السؤال الدوري.
- التفعيل: بعد مراجعة الربط ننقل حسابكم إلى البيئة الحقيقية ونرسل بيانات الدخول الحقيقية، فيظهر اسمكم لكل التجار في دولكم.
مثال سريع
1) الحصول على رمز الدخول (صالح ساعة):
curl -X POST https://app.yaqinerp.com/api/shipping/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type":"client_credentials","client_id":"yq_test_…","client_secret":"yqs_…"}'2) الشحنات الجديدة:
curl "https://app.yaqinerp.com/api/shipping/v1/shipments?state=new" \ -H "Authorization: Bearer $TOKEN"
3) قبول شحنة:
curl -X POST https://app.yaqinerp.com/api/shipping/v1/shipments/shp_3f9a0c1b2d4e5f60/accept \
-H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"tracking_number":"FX100234","label_url":"https://…/FX100234.pdf"}'4) إرسال حالة:
curl -X POST https://app.yaqinerp.com/api/shipping/v1/shipments/shp_3f9a0c1b2d4e5f60/events \
-H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"status":"DELIVERED","proof_of_delivery":{"receiver_name":"Mohammed"}}'الحالات
| الرمز | المعنى |
|---|---|
| PICKUP_SCHEDULED | موعد الاستلام محدد |
| PICKUP_FAILED | تعذر الاستلام |
| PICKED_UP | تم الاستلام من التاجر |
| AT_HUB | في مركز الفرز |
| IN_TRANSIT | في الطريق |
| OUT_FOR_DELIVERY | خرجت للتوصيل |
| DELIVERY_ATTEMPT_FAILED | محاولة توصيل فاشلة (اذكر السبب) |
| ON_HOLD | معلّقة |
| DELIVERED | تم التسليم (مع إثبات التسليم) |
| RETURN_IN_TRANSIT | مرتجع في الطريق للتاجر |
| RETURNED | أُرجعت للتاجر |
| LOST | مفقودة |
| DAMAGED | تالفة |
قواعد مهمة
- كل الطلبات بصيغة JSON، والتواريخ بصيغة ISO 8601 مع المنطقة الزمنية.
- أرسل الترويسة
Authorization: Bearer <access_token>في كل طلب، واطلب رمزاً جديداً بعد انتهاء صلاحيته. - أرسل
Idempotency-Keyفريداً مع كل طلب POST، فإعادة نفس الطلب لا تنفذه مرتين. - الحد 120 طلباً في الدقيقة لكل حساب، والقوائم مقسمة بصفحات عبر
next_cursor. - الأخطاء بالشكل
{"error": {"code", "message", "details"}}مع رموز 400 و401 و403 و404 و409 و422 و429. - الويب هوك (اختياري): نرسل
shipment.createdوshipment.cancelledمع توقيعX-Yaqin-Signature(HMAC-SHA256).