ابدأ الآن

المصادقة

الحصول على رمز

الشحنات

انشاء شحنة

شحنات - الإلتقاط

شحنات - التسليم

تتبع شحنة

تتبع الشحنات المتعددة

طباعة ملصق

إلغاء الشحنة

ويب هوك

New Collection 2162023

NEW API documentation - Live - AR

SPL Documentation - LIVE

Production

Sandbox

تهدف وثيقة واجهة برمجة التطبيقات (API) هذه إلى مساعدتك في ربط أنظمتك وخدماتك الإلكترونية بمنصة سبل للشحن وتتبع الشحنات. ومن خلال استخدام واجهات برمجة التطبيقات هذه، ستتمكن من الحصول على المعلومات اللازمة لبدء عملية التكامل مع المنصة.<div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div>

واجهة برمجة التطبيقات (API)

 هذه إلى مساعدتك في ربط أنظمتك وخدماتك الإلكترونية بمنصة 

سبل للشحن وتتبع الشحنات

. ومن خلال استخدام واجهات برمجة التطبيقات هذه، ستتمكن من الحصول على المعلومات اللازمة لبدء عملية التكامل مع المنصة.

لضمان الحفاظ على معايير عالية من الأمان وتوفير حماية إضافية للمستخدمين والحسابات، تستخدم خدمات واجهة برمجة التطبيقات (API) مزيجًا من التقنيات وبروتوكولات الأمان التي تفرض المصادقة. ويتعين على المستخدمين الحصول على رمز مفتاح (Token) يحتاج إلى التجديد بشكل دوري.

لضمان الحفاظ على معايير عالية من الأمان وتوفير حماية إضافية للمستخدمين والحسابات، تستخدم خدمات واجهة برمجة التطبيقات (API) مزيجًا من التقنيات وبروتوكولات الأمان التي تفرض المصادقة. ويتعين على المستخدمين الحصول على رمز مفتاح (Token) يحتاج إلى التجديد بشكل دوري.

تتيح واجهات برمجة التطبيقات (APIs) هذه للمستخدمين المصرّح لهم ما يلي:<ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">إنشاء شحنة واحدة أو عدة شحنات على منصة سبل.</div></li><li class="slate-li " ><div style="position:relative">تتبع الشحنات باستخدام رقم بوليصة الشحن (AWB Number) أو الرقم المرجعي (Reference Number).</div></li></ul>

تتيح واجهات برمجة التطبيقات (APIs) هذه للمستخدمين المصرّح لهم ما يلي:

<h3 class="slate-h3 " >المتطلبات المسبقة </h3>قبل إنشاء شحنة، تأكد من توفر حساب نشط (Active Account)، ورمز عميل صالح (Customer Code)، ورمز فرع مسجل (Branch Code)، ورمز عنوان فرع مسجل (Branch Address Code). تُعد هذه البيانات ضرورية لإنشاء الشحنة بنجاح، ويمكن الحصول عليها من خلال إجراءات التسجيل الأولي (Onboarding) أو إعداد الحساب ذات الصلة.<h3 class="slate-h3 " > التكرار </h3>يؤدي إرسال طلب مطابق للطلب السابق إلى إنشاء شحنة مكررة برقم بوليصة شحن (Waybill Number) جديد. يتم تطبيق آلية Idempotency على رقم AWB فقط، ولا يتم تطبيقها على الأرقام المرجعية (Reference Numbers).يمكنني أيضًا توحيد صياغة قسم API Documentation بالكامل بنفس الأسلوب والمصطلحات.

قبل إنشاء شحنة، تأكد من توفر 

رمز عنوان فرع مسجل (Branch Address Code)

. تُعد هذه البيانات ضرورية لإنشاء الشحنة بنجاح، ويمكن الحصول عليها من خلال إجراءات التسجيل الأولي (Onboarding) أو إعداد الحساب ذات الصلة.

يؤدي إرسال طلب مطابق للطلب السابق إلى إنشاء 

 برقم بوليصة شحن (Waybill Number) جديد. يتم تطبيق آلية 

 فقط، ولا يتم تطبيقها على 

الأرقام المرجعية (Reference Numbers)

يمكنني أيضًا توحيد صياغة قسم 

 بالكامل بنفس الأسلوب والمصطلحات.

صادر عن سبل - يحدد حسابك ويحدد نطاق الطلب.

customerCode

صادر عن سبل - الفرع المسجّل الذي يتم حجز الشحنة وربطها به. رمز واحد لكل موقع.



branchCode

صادر عن سبل - العنوان المسجّل ضمن الفرع والمستخدم كنقطة استلام. ويُعد هذا العنوان مطلوبًا حتى في حال عدم إجراء عملية استلام.


branchAddressCode

الطابع الزمني للإنشاء. يُسمح بإدخال قيمة مستقبلية.


shippingDateTime

يحدد مسار الاستلام ومسار التسليم، ويحدد ما إذا كان سيتم إنشاء مهمة استلام.

deliveryModel

الخط الخدمي. يحدد القواعد الشرطية التي تنطبق على الحقول.

productType

فئة المحتوى. تحدد آلية التعامل مع الأبعاد. وقد تم تأكيد ذلك في عقد اختبار قبول المستخدم (UAT).


shipmentType

وصف المحتويات. يُطبع على بوليصة الشحن الجوي ويُستخدم لتقييم الجمارك في الشحنات الدولية.

descriptionOfGoods

القيمة المصرّح بها للمحتويات لأغراض التخليص الجمركي. هذا هو الحقل الذي يؤدي إلى طباعة القيمة على الملصق.


customsDeclaredValue

عملة القيمة المصرّح بها.  
مطلوبة إذا تم ملء حقل القيمة المصرّح بها للجمارك.

customsDeclaredValueCurrency

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

إجمالي مبلغ الدفع عند الاستلام (COD) لجميع القطع ضمن الشحنة متعددة القطع. يجب توضيح العلاقة التقنية الدقيقة بين هذا الحقل وحقل `cod`.


totalCod

عملة مبلغ الدفع عند الاستلام (COD). اسم الحقل في العقد الفعلي (Live Contract) مكتوب `codCurrnecy`. يُرجى الرجوع إلى القسم 12.


codCurrency

numberOfPieces

يحدد شركة النقل المسؤولة عن تنفيذ الشحنة.

supplierCode

يُرجع الملصق في استجابة الإنشاء بدلاً من استدعاء منفصل لطباعة الملصق. يوضح الترميز والصيغة.

IncludeLabel

يكون True فقط عندما تكون قيمة productType هي ERTN، ويكون False للقيم DOM وINTIN وINTOUT. تم تأكيد ذلك في عقد UAT.

IsReturnEBU

shipper

shipmentWeight

consignee

reference

items

وقت تسليم الشحنة - حقل اجباري في حال ادخال خدمة اضافية
Mandatory if the "TimeDefnte" is entered as shipment service

ShipmentDeliveryTime

Only one of the three services "WEndDL", "SameDayDL", "TimeDefnte" can be used at the same time
 "WEndDL"، "SameDayDL"، "TimeDefnte"  يمكن استخدام أحد الخدمات الثلاث في نفس الوقت فقط











shipmentServicesCodes

Content-Type

Authorization

api_connection_error

API errors cover any other type of problem (e.g., a temporary problem with servers), and are extremely uncommon.

api_error

Failure to properly authenticate yourself in the request.

authentication_error

Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.

card_error

Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters.

idempotency_error

Invalid request errors arise when your request has invalid parameters.

invalid_request_error

Too many requests hit the API too quickly.

rate_limit_error

Errors triggered by our client-side libraries when failing to validate fields (e.g., when a card number or expiration date is invalid or incomplete).

validation_error

رموز الحالات والأخطاء

The request was unacceptable, often due to missing a required parameter.

The parameters were valid but the request failed.

The API key doesnt have permissions to perform the request.

<h3 class="slate-h3 " >المتطلبات المسبقة </h3>قبل إنشاء شحنة، تأكد من توفر حساب نشط (Active Account)، ورمز عميل صالح (Customer Code)، ورمز فرع مسجل (Branch Code)، ورمز عنوان فرع مسجل (Branch Address Code). تُعد هذه البيانات ضرورية لإنشاء الشحنة بنجاح، ويمكن الحصول عليها من خلال إجراءات التسجيل الأولي (Onboarding) أو إعداد الحساب ذات الصلة.<h3 class="slate-h3 " > التكرار </h3>يؤدي إرسال طلب مطابق للطلب السابق إلى إنشاء شحنة مكررة برقم بوليصة شحن (Waybill Number) جديد. يتم تطبيق آلية Idempotency على رقم AWB فقط، ولا يتم تطبيقها على الأرقام المرجعية (Reference Numbers).يمكنني أيضًا توحيد صياغة قسم API Documentation بالكامل بنفس الأسلوب والمصطلحات.

يحدد مرحلة الاستلام ومرحلة التسليم، كما يحدد ما إذا كان سيتم إنشاء مهمة استلام.

DoortoDoor: التسليم إلى باب العميل.
DoortoRetail: من العميل إلى أقرب منشأة تابعة لـ SPL.

<h3 class="slate-h3 " >المتطلبات المسبقة </h3>قبل إنشاء شحنة، تأكد من توفر حساب نشط (Active Account)، ورمز عميل صالح (Customer Code)، ورمز فرع مسجل (Branch Code)، ورمز عنوان فرع مسجل (Branch Address Code). تُعد هذه البيانات ضرورية لإنشاء الشحنة بنجاح، ويمكن الحصول عليها من خلال إجراءات التسجيل الأولي (Onboarding) أو إعداد الحساب ذات الصلة.<h3 class="slate-h3 " > التكرار </h3>يؤدي إرسال طلب مطابق للطلب السابق إلى إنشاء شحنة مكررة برقم بوليصة شحن (Waybill Number) جديد. يتم تطبيق آلية Idempotency على رقم AWB فقط، ولا يتم تطبيقها على الأرقام المرجعية (Reference Numbers).<h4 class="slate-h4 " >التسليم في أقرب مكتب SPL أو موقع طرود (Drop-Off):</h4>

التسليم في أقرب مكتب SPL أو موقع طرود (Drop-Off):

يحدد مرحلة الاستلام ومرحلة التوصيل، ويحدد ما إذا كان سيتم إنشاء مهمة استلام (Pickup).
RetailtoDoor: يجب إدخال تفاصيل عنوان المكتب أو موقع الطرد (Parcel Location) ضمن تفاصيل عنوان المرسل (Shipper Address Details).
RetailtoRetail: يجب إدخال تفاصيل عنوان المكتب أو موقع الطرد (Parcel Location) ضمن عناوين المرسل (Shipper) والمستلم (Consignee).


airwaybill

airwaybills

labelFormat

labelSize

Failed: "You can't perform this action! The shipment is out for delivery and/or already delivered"


Success : "The shipment Has Been Successfully Cancelled"


لإعداد ويب هوك، يرجى ملاحظة ما يلي:<ol class="slate-ol " ><li class="slate-li " ><div style="position:relative"> المصادقة : سيتم إرسال أحداث الـويب هوك باستخدام إحدى طريقتي Basic Authorization أو X-API-Key، مع استخدام بيانات اعتماد من اختياركم.</div></li><li class="slate-li " ><div style="position:relative"> بيانات الطلب : تم توضيح هيكل بيانات الطلب أدناه. يرجى التأكد من أن نقطة النهاية الخاصة بكم قادرة على استقبال هذا الهيكل.</div></li><li class="slate-li " ><div style="position:relative"> الأحداث : تم إدراج قائمة بأكثر الأحداث شيوعًا التي يتم إرسالها ضمن تبويب للرجوع إليها واستخدامها في عملية الربط.</div></li><li class="slate-li " ><div style="position:relative"> نقطة نهاية الـويب هوك: يتعين عليكم تزويدنا بعنوان نقطة نهاية الويب هوك الخاص بكم حتى نتمكن من تهيئته وربطه بحسابكم.</div></li></ol>ملاحظة: يجب أن تُرجع واجهة برمجة التطبيقات (API) استجابة منظمة حتى نتمكن من التحقق مما إذا كانت عملية التحديث قد تمت بنجاح. ويكون نموذج الاستجابة المتوقع كما يلي:public class DynamicTrackingShipmentResponse{    public bool IsSuccess { get; set; }    public string? Exception { get; set; }}بدون هذه الاستجابة، لن يتمكن نظامنا من التحقق مما إذا كان طلب الـويب هوك قد تم قبوله بنجاح أو فشل. يرجى التأكد من تنفيذ الاستجابة وفقًا للنموذج المطلوب.<div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div>بيانات طلب الويب هوك<ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">يرجى التأكد من أن نقطة النهاية الخاصة بكم قادرة على استقبال هذا الهيكل.</div></li><li class="slate-li " ><div style="position:relative">يرجى ملاحظة أن بيانات طلب الويب هوك لدينا تستخدم تنسيق وهي ؛Camel Case , غير حساسة لحالة الأحرف لذلك يرجى التأكد من أن الويب هوك الخاص بكم لا يعتمد على حالة الأحرف وأنه قادر على استقبال البيانات بأي من التنسيقين (Camel Case أو Pascal Case) مع الحفاظ على مرونة النظام في حال إضافة أي حقول جديدة من جانبنا مستقبلآ.</div></li></ol><div class="code-block-wrapper" style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">{
 &quot;airwaybill&quot;: &quot;***************&quot;,
 &quot;eventCode&quot;: &quot;GN012&quot;,
 &quot;event&quot;: &quot;Shipment Delivered&quot;,
 &quot;eventName&quot;: &quot;Shipment Delivered&quot;,
 &quot;supplier&quot;: null,
 &quot;userName&quot;: &quot;admin&quot;,
 &quot;notes&quot;: null,
 &quot;actionDate&quot;: &quot;2024-10-29T17:30:00+00:00&quot;,
 &quot;eventCountry&quot;: &quot;AMMAN&quot;,
 &quot;eventCity&quot;: &quot;AMMAN&quot;,
 &quot;eventSubCode&quot;: null,
 &quot;eventSubName&quot;: null
 }</textarea><code class="language-plainText keep-markup drop-tokens">{
 &quot;airwaybill&quot;: &quot;***************&quot;,
 &quot;eventCode&quot;: &quot;GN012&quot;,
 &quot;event&quot;: &quot;Shipment Delivered&quot;,
 &quot;eventName&quot;: &quot;Shipment Delivered&quot;,
 &quot;supplier&quot;: null,
 &quot;userName&quot;: &quot;admin&quot;,
 &quot;notes&quot;: null,
 &quot;actionDate&quot;: &quot;2024-10-29T17:30:00+00:00&quot;,
 &quot;eventCountry&quot;: &quot;AMMAN&quot;,
 &quot;eventCity&quot;: &quot;AMMAN&quot;,
 &quot;eventSubCode&quot;: null,
 &quot;eventSubName&quot;: null
 }</code></pre></div>

 يجب أن تُرجع واجهة برمجة التطبيقات (API) استجابة منظمة حتى نتمكن من التحقق مما إذا كانت عملية التحديث قد تمت بنجاح. ويكون نموذج الاستجابة المتوقع كما يلي:

public class DynamicTrackingShipmentResponse

    public bool IsSuccess { get; set; }

    public string? Exception { get; set; }

بدون هذه الاستجابة، لن يتمكن نظامنا من التحقق مما إذا كان طلب ال

 قد تم قبوله بنجاح أو فشل. يرجى التأكد من تنفيذ الاستجابة وفقًا للنموذج المطلوب.

Sections