انتقل إلى المحتوى
كل المقالات
شركات-الشحنالتجارة-الإلكترونيةالسعوديةربط-APIدراسة-حالة

ربط المتجر بشركات الشحن في السعودية: تجربتنا مع OTO

١٢ نوفمبر ٢٠٢٦ 9 دقيقة قراءة· Mahmoud Makhlouf
Read this article in English

صاحب متجر في الرياض يفتح تقرير الشهر فيجد أن تكلفة الشحن التي دفعها لشركة الشحن أعلى بكثير مما حصّله من العملاء. السبب بسيط: المتجر يأخذ رسوم توصيل ثابتة على كل الطلبات، بينما الشحن إلى أبها أو تبوك يكلّف أكثر من الشحن داخل الرياض.

الإجابة المختصرة: أسهل طريقة لربط المتجر بشركات الشحن في السعودية هي الربط مع منصة تجميع شحن واحدة مثل OTO بدل ربط كل شركة على حدة. تحصل من خلال API واحد على سعر توصيل حقيقي وقت الدفع، وتتبّع موحّد، ودعم للدفع عند الاستلام والمرتجعات. أما الجزء الهندسي المهم فهو تخزين الأسعار مؤقتًا، والتحقق من الـ Webhook، وألّا يُفشل إنشاء الشحنة عملية الدفع أبدًا.

المشكلة من زاوية صاحب المتجر

سعر الشحن في السعودية ليس رقمًا واحدًا. يتغيّر حسب مدينة الإرسال، ومدينة الاستلام، ووزن الطرد وحجمه، وهل الدفع عند الاستلام أم مسبق، وأي شركة شحن تختار.

السعر الثابت يخسرك في الاتجاهين: عميل يراه مرتفعًا فيترك السلة، وطلب تدفع أنت فرقه من هامشك.

وبعد البيع تبدأ أسئلة أخرى:

  • من ينشئ الشحنة عند شركة الشحن ويطبع البوليصة؟
  • كيف يعرف العميل مكان طلبه دون أن يتصل بك؟
  • في طلبات الدفع عند الاستلام، المندوب يحصّل المبلغ ثم تحوّله الشركة لاحقًا. كيف تعرف المستحق لك؟
  • كيف يعرف فريقك بالمرتجعات ومحاولات التوصيل الفاشلة في اليوم نفسه؟

الإدارة اليدوية بين لوحة شركة الشحن ولوحة متجرك تنجح مع عشرة طلبات يوميًا، وتتعثر عند مئة.

الخيارات المتاحة: كل شركة على حدة أم منصة تجميع؟

ربط مباشر مع كل شركة شحنمنصة تجميع مثل OTO
العقودعقد مستقل مع كل شركةأسعار المنصة، أو ربط عقودك الحالية مع الشركات
العمل البرمجيAPI ونظام حالات وبوليصة مختلفة لكل شركةAPI واحد وقائمة حالات واحدة
السعر وقت الدفعتقارن بين الشركات بنفسكطلب واحد يعيد خيارات مسعّرة من عدة شركات
التتبّعربط منفصل لكل شركةWebhook واحد لكل الشحنات
تغيير شركة الشحنمشروع ربط جديدغالبًا إعداد في لوحة المنصة
التكلفةلا رسوم منصة، لكن بناء وصيانة أكثرباقة اشتراك وتسعير للشحنة حسب المنصة

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

OTO من منصات تجميع الشحن المبنية لهذا السوق. وقت كتابة المقال (نوفمبر 2026) تذكر صفحتها العربية أكثر من 460 شركة شحن محلية ودولية وأكثر من 45 قناة بيع، وتعرض صفحات الربط لديها شركات مثل أرامكس وسمسا والبريد السعودي (SPL) وناقل إكسبريس. وتوضّح صفحات OTO أنك تستطيع الشحن بأسعارها المخفّضة أو ربط عقدك الحالي مع شركة الشحن. تفاصيل الباقات وعدد الشركات المسموح ربطها تتغير، فراجعها على موقع tryoto.com قبل القرار.

ثلاثة قرارات تجارية قبل أي سطر برمجي

  1. من يدفع الشحن؟ العميل دائمًا، أو شحن مجاني فوق مبلغ معيّن، أو سعر ثابت. كثير من المتاجر تجمع بينها: مجاني فوق حدّ معيّن، وسعر حي تحته.
  2. هل تضيف هامشًا على التوصيل؟ المنصة متعددة التجار تتحمّل تكلفة دعم وتشغيل، فتضيف نسبة فوق سعر شركة الشحن. قرّر أيضًا: هل يرى العميل مبلغًا واحدًا أم تفصيلًا؟
  3. ماذا يحدث إذا تعطّل API الشحن أو لم توجد تغطية للمسار؟ تحتاج سعرًا احتياطيًا، وإلا توقّف الدفع. قرّر ذلك الآن، لا أثناء العطل.

كيف بنينا الشحن في أجزاء

أجزاء سوق سعودي لقطع غيار السيارات: متاجر مستقلة كثيرة، وتطبيق واحد للعميل، ولوحة إدارة واحدة. كل طلب يُشحن من مدينة المتجر إلى عنوان العميل، والمنصة تحتاج سعر شركة شحن حقيقيًا وقت الدفع. لذلك اعتمدنا OTO طبقةً واحدة للشحن.

هذا ما يراه صاحب العمل في المنتج:

  • الدفع لكل متجر على حدة. سلة فيها منتجات من متجرين تتحول إلى طلبين، لكل منهما رسوم توصيل خاصة، لأن الطردين يخرجان من مدينتين مختلفتين.
  • حدّ شحن مجاني لكل متجر. كل متجر يحدّد المبلغ الذي يصبح الشحن بعده مجانيًا. تحته نطلب من OTO سعرًا حيًا.
  • العميل يختار شركة الشحن. نجلب كل الخيارات المسعّرة مرتبة من الأرخص، ونختار الأرخص افتراضيًا. وإذا اختار العميل خيارًا آخر في السلة نلتزم باختياره عند إنشاء الطلب.
  • مبلغ واحد أمام العميل. المنصة تضيف عمولة توصيل بنسبة تُضبط من لوحة الإدارة فوق سعر شركة الشحن. العميل يرى الإجمالي فقط، والتفصيل (سعر الشركة، ونسبة العمولة، وقيمتها) يُحفظ مع الطلب لتقارير الإدارة.
  • بديل يُبقي الدفع يعمل. إذا لم يكن OTO مفعّلًا، أو لم تغطِّ أي شركة المسار بين المدينتين، يُستخدم سعر الشحن الثابت للمتجر.
  • فحص التغطية قبل السلة. عندما يحدّد العميل موقع عنوان جديد على الخريطة، يستطيع التطبيق أن يخبره هل التوصيل متاح هناك أم لا.
  • الدفع عند الاستلام. في طلبات الدفع عند الاستلام نرسل إجمالي الطلب مبلغًا مستحق التحصيل لشركة الشحن، وفي الطلبات المدفوعة مسبقًا يكون المستحق صفرًا.
  • التتبّع يصل للعميل. تحديثات الحالة تصل عبر Webhook، فتُحدَّث حالة الطلب، ويصل التحديث للتطبيق مباشرة، ويُرسَل إشعار في اللحظات المهمة مثل "خرج للتوصيل".

شاشة الدفع في تطبيق العميل تعرض رسوم التوصيل وقائمة شركات الشحن لمتجر واحدشاشة الدفع في تطبيق العميل تعرض رسوم التوصيل وقائمة شركات الشحن لمتجر واحد

صفحة الشحن في لوحة الإدارة تعرض الطلبات مع حالة OTO وشركة الشحن ورقم التتبعصفحة الشحن في لوحة الإدارة تعرض الطلبات مع حالة OTO وشركة الشحن ورقم التتبع

التفاصيل التقنية

هذا مسار الطلب الواحد من السلة حتى التسليم:

Customer app            Ajza backend                         OTO
------------            ------------                         ---
checkout  ──quote──▶  cache (5 min) ──miss──▶  checkOTODeliveryFee
                      + commission
pay       ──────────▶ payment tx COMMIT
                      └─ after commit: createShipment ──────▶ create order + shipment
order screen ◀─socket─ webhook handler ◀──── signed status ── webhook
             ◀─push───  (dedupe, map status)

المصادقة تحت ضغط الطلبات المتزامنة

يعمل OTO برمز تحديث (Refresh Token) يُستبدل برمز وصول قصير العمر (JWT). نقطتان حدّدتا طريقة كتابتنا للكود:

  • OTO يغيّر رمز التحديث نفسه مع كل عملية استبدال، فلا بد أن يحتفظ النظام بأحدث رمز.
  • وقت الذروة قد تصل طلبات كثيرة في اللحظة التي ينتهي فيها الرمز. لو طلب كل منها رمزًا جديدًا لتسابقت برمز تحديث لم يعد صالحًا.

لذلك جعلنا التحديث عملية واحدة مشتركة: أول طلب يبدأها، والبقية تنتظر النتيجة نفسها.

private async getAccessToken(): Promise<string> {
  // Refresh 60s before expiry to avoid racing in-flight requests.
  if (this.accessToken && Date.now() < this.expiresAt - 60_000) {
    return this.accessToken;
  }
  if (this.refreshPromise) return this.refreshPromise; // share one refresh
  this.refreshPromise = this.refreshAccessToken().finally(() => {
    this.refreshPromise = null;
  });
  return this.refreshPromise;
}

وإذا رجع أي طلب برمز 401 نمسح الرمز المخزّن ونعيد المحاولة مرة واحدة فقط.

سعر التوصيل بطيء، فنخزّنه مؤقتًا

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

وزن الطرد عندما لا يعرف الكتالوج الأبعاد

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

أرقام الجوال بصيغة واحدة

العملاء يكتبون أرقام الجوال السعودية بكل الصيغ: مع ‎+966 أو 00966 أو 05 في البداية أو 5 فقط. واجهة مواقع الاستلام في OTO تتوقع الرقم المحلي من 9 خانات، فيمرّ كل رقم على دالة توحيد واحدة قبل إرساله.

إنشاء الشحنة لا يُفشل الدفع أبدًا

هذا القرار نكرّره في كل مشروع. عند نجاح الدفع يُحدَّث الطلب داخل معاملة قاعدة بيانات (Transaction). أما إنشاء الشحنة في OTO فهو اتصال بنظام خارجي قد يتأخر أو يفشل. لو وضعناه داخل المعاملة لأمكن أن يُلغي تأخّرُ OTO عمليةَ دفع أتمّها العميل فعلًا.

لذلك ننشئ الشحنة بعد اعتماد المعاملة فقط، ونسجّل أي فشل دون أن نرميه للأعلى:

await queryRunner.commitTransaction();

// Post-commit: failures here must not bubble up.
// Admins can retry the shipment from the shipping page.
if (payment.orderId) {
  this.shipping
    .createShipmentForOrder(payment.orderId)
    .catch((err) => this.logger.error(`Auto shipment failed: ${err}`));
}

ودالة إنشاء الشحنة آمنة من التكرار: إذا كان للطلب رقم في OTO مسبقًا لا تنشئ شحنة ثانية. وقبل الاتصال بـ OTO تتحقق من اكتمال البيانات: اسم العميل وجواله وعنوانه، واسم مدينة يعرفه OTO، وعنوان المتجر وهاتفه. وإذا نقص شيء تعيد قائمة واضحة بما ينقص بدل رسالة خطأ عامة.

تفاصيل الطلب في لوحة الإدارة مع الخط الزمني لتتبّع الشحنةتفاصيل الطلب في لوحة الإدارة مع الخط الزمني لتتبّع الشحنة

الـ Webhook: تحقّق، ثم توجيه، ثم منع التكرار، ثم ترجمة الحالة

كل تغيّر في حالة الشحنة يصل إلى نقطة Webhook واحدة، والمعالج يقوم بأربع خطوات:

  1. التحقق. يمكن أن يوقّع OTO الحدث بـ HMAC-SHA256 على النص orderId:status:timestamp بترميز base64، أو يرسل مفتاح تفويض مشتركًا في الترويسة. عند ضبط بيانات التحقق يجب أن ينجح أحد الفحصين على الأقل.
  2. التوجيه. في أجزاء ثلاثة أنواع من الشحنات: طلبات السوق، وطلبات القطع الخارجية، وطلبات المتاجر. المعالج يبحث عن الرقم في كل نوع بالترتيب ويمرّر الحدث للمعالج المناسب.
  3. منع التكرار. قد يصل الحدث نفسه أكثر من مرة. نحفظ حالة OTO الخام مع السجل، ونتجاهل أي حدث تطابق حالته ما هو محفوظ.
  4. ترجمة الحالة. لدى OTO قائمة طويلة من الحالات التفصيلية، ونموذج الطلب عندنا يحتاج حالات قليلة. جدول من نحو ثلاثين حالة يجمعها في: قيد التجهيز، تم الشحن، خرج للتوصيل، تم التسليم، تعذّر التوصيل، مرتجع، ملغى. والحالات التي لا تغيّر شيئًا تُحفظ كما هي ليرى فريق الدعم كلمة شركة الشحن بالضبط.
const OTO_STATUS_ACTION_MAP: Record<string, OrderAction> = {
  shipmentCreated: 'processing',
  pickedUp: 'shipped',
  outForDelivery: 'out_for_delivery',
  delivered: 'delivered',
  pickupAttemted: 'failed',     // OTO's own spelling, kept as sent
  undeliveredAttempt: 'failed',
  reversePickedUp: 'returned',
  shipmentCanceled: 'cancelled',
  // ...
};

لاحظ pickupAttemted. هكذا ترسلها OTO، ونحن نطابقها كما هي. لو "صحّحنا" الإملاء عندنا لتوقف هذا الحدث عن المطابقة دون أي رسالة خطأ.

ما تعلّمناه

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

قائمة تحقّق قبل ربط متجرك بشركات الشحن

  1. حدّد من يدفع الشحن، وحدّ الشحن المجاني، وهل تضيف هامشًا على التوصيل.
  2. حدّد السعر الاحتياطي عند تعطّل API الشحن أو غياب التغطية.
  3. اختر بين منصة تجميع وربط مباشر، وتأكّد من الشركات التي تغطي مدن متاجرك.
  4. أضف وزنًا لكل منتج، أو اتفق على أوزان افتراضية وحدّ أدنى معقول.
  5. احفظ أسماء المدن بالصيغة التي يتوقعها API الشحن، لا الاسم العربي المعروض فقط.
  6. وحّد صيغة أرقام الجوال السعودية قبل الإرسال.
  7. خزّن أسعار التوصيل بضع دقائق، وامنع تكرار الطلبات المتزامنة.
  8. اجعل تحديث الرمز عملية واحدة مشتركة إذا كان المزوّد يغيّر رموز التحديث.
  9. أنشئ الشحنة بعد اعتماد الدفع، بشكل آمن من التكرار، مع زر إعادة محاولة في لوحة الإدارة.
  10. تحقّق من توقيع الـ Webhook، وتجاهل المكرر، واحفظ الحالة الخام.
  11. أرسل مبلغ التحصيل الصحيح في الدفع عند الاستلام، وصفرًا في المدفوع مسبقًا.
  12. ترجم حالات الإرجاع والشحن العكسي حتى تظهر المرتجعات في يومها.

الأسئلة الشائعة

ما أفضل طريقة لربط المتجر بشركات الشحن في السعودية؟

لأغلب المتاجر، الربط مع منصة تجميع شحن مثل OTO هو الأسرع، لأن API واحدًا يعطيك عدة شركات وأسعارًا حية وتتبّعًا موحّدًا. الربط المباشر مع شركة واحدة يناسب غالبًا من يشحن كميات كبيرة عبرها بعقد تفاوض عليه.

ما شركات الشحن في السعودية التي يمكن الوصول إليها عبر OTO؟

تعرض صفحات OTO وقت كتابة المقال شركات مثل أرامكس وسمسا والبريد السعودي (SPL) وناقل إكسبريس، إلى جانب شركات دولية. القائمة وعدد الشركات المتاحة في كل باقة يتغيران، فراجع موقع OTO للقائمة الحالية.

هل يدعم OTO الدفع عند الاستلام؟

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

هل يمكن عرض سعر الشحن الحقيقي للعميل وقت الدفع؟

نعم. يوفّر OTO طلبًا يعيد خيارات مسعّرة حسب مدينة الإرسال ومدينة الاستلام وحجم الطرد. ولأن الطلب قد يستغرق عدة ثوانٍ، خزّن النتيجة بضع دقائق واحتفظ بسعر ثابت احتياطي للمسارات غير المغطاة.

هل تستطيع المنصة إضافة ربح على رسوم التوصيل؟

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

الخطوة التالية

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

وعندما تكون جاهزًا، أرسل لنا ملخص مشروعك ونخبرك بما يحتاجه الربط في حالتك.

// لنبدأ

عندك فكرة منتج؟ خذ خطة واضحة و مكالمة تعارف مجانية 15 دقيقة.

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

احجز مكالمة مجانية WhatsApp