مزامنة مخزون سلة مع ERP: اجعل كل حركة قابلة للتدقيق

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

توفر Merchant API الحالية في سلة أدوات أفضل: تحديث الكميات جماعيًا بأنماط `increment` و`decrement` و`overwrite` مع `branch` و`reason_id`، وقراءة الكميات، وقائمة أسباب التغيير، وواجهة سجل تدقيق الكميات. لا تصنع هذه الواجهات موصل ERP كاملًا وحدها، لكنها تمنحك primitives لبناء مزامنة يمكن شرح حركاتها ومطابقتها وإصلاحها.

حدد مصدر الحقيقة قبل كتابة الكود

يحتاج تصميم المزامنة إلى مالك واضح لكل قرار. يمكن أن يمتلك ERP أوWMS المخزون الفعلي المتاح، وتمتلك سلة الحجوزات وسلوك البيع، ويمتلك التكامل حالة التسليم. لا تسمح لمهمة مجدولة وOrder Webhook وتعديل مستودع بأن ينفذ كل منها Overwrite للحقل نفسه بصورة مستقلة.

عرّف هوية المخزون على الأقل بصيغة `store + branch + product or variant`. أنشئ جدول Mapping من معرفات المستودع وSKU في ERP إلى معرف الفرع والمنتج أوVariant في سلة. تعرض واجهة List Branches معرفات الفروع وبياناتها؛ خزّن المعرف المستقر، لا اسم العرض وحده لأنه قابل للتغيير. أرسل الهوية غير المربوطة أوالمبهمة إلى Exception Queue بدل الكتابة بصمت في الفرع الافتراضي.

حدد كذلك معنى الكمية: هل يرسل ERP الكمية الموجودة فعليًا، أمAvailable to Sell، أمDelta لحركة واحدة؟ هل يطرح Safety Stock؟ وهل انعكست طلبات سلة في ERP قبل المزامنة التالية؟ طلب API صحيح مع تعريف أعمال غامض للكمية ينتج مخزونًا خاطئًا.

فضّل الحركات على Snapshots العمياء

توثق واجهة Bulk ثلاثة أنماط: يضيف `increment` وحدات، ويزيل `decrement` وحدات، ويستبدل `overwrite` الكمية. تصف سلة Overwrite بأنه مناسب للإعداد الأولي أوإعادة الضبط الكاملة، وتنصح بالحذر عند استخدامه مع الأنظمة الخارجية. يحفظ increment وdecrement النية: استلام 12 وحدة وإتلاف وحدتين يبقيان حركتين واضحتين بدل تغيير غير مفسر من 40 إلى 50.

يمكن أن يبدو سجل الحركة في نظام التكامل هكذا:

movement_id: erp-warehouse-7-00018492
identity: store-44 / branch-349994915 / variant-8439405958
delta: -2
reason: damaged
occurred_at: 2026-09-26T11:41:08Z
state: pending

احفظ السجل قبل استدعاء سلة. هذا نمط Transactional Outbox: تحفظ معاملة الأعمال ونيتها للخروج معًا، ثم يرسل Worker الحركة. يمنع Unique Constraint على `movement_id` إنشاء الحركة المحلية نفسها مرتين. ونفّذ Serialization للعمال حسب هوية المخزون حتى لا تتسابق حركتان للـVariant والفرع نفسيهما.

اجلب قائمة أسباب التغيير من المنصة واربط Codes في ERP بالمعرفات المعادة. تعرض الوثائق حاليًا أسبابًا مثل التصحيح وإعادة التخزين والاستقبال والتالف والسرقة أوالضياع، لكن IDs الموجودة في الأمثلة ليست Configuration. خزّن الـMapping المحلول مع سياسة تحديث، وأوقف أي حركة لا تجد سببًا مطابقًا. حفظ السبب يجعل التحقيق التشغيلي أوضح من تسجيل كل شيء كتصحيح عام.

ابنِ Bulk Request بعناية

تقبل واجهة الكتابة معرف المنتج أوVariant والكمية والنمط والفرع والسبب. تستخدم بنية الطلب المنشورة التهجئة `identifer_type` و`identifer` للحقلين؛ لذلك يجب أن يتبع Client عقد API الفعلي بدل تصحيح التهجئة تلقائيًا داخل JSON. هذا Payload توضيحي:

{
  "products": [
    {
      "identifer_type": "variant_id",
      "identifer": "8439405958",
      "quantity": 2,
      "mode": "decrement",
      "branch": "349994915",
      "reason_id": 525144736
    }
  ]
}

استخدم المثال للشكل فقط، واجلب قيم المتجر والفرع والـVariant والسبب الفعلية للتاجر. تحتاج الكتابة إلى Scope باسم `products.read_write`، بينما تستخدم قراءة الكميات والتدقيق والأسباب `products.read`، ويحتاج اكتشاف الفروع `branches.read`. اطلب أقل صلاحيات يحتاجها التطبيق.

اجعل حجم Batch محدودًا بالعدد والسياق التشغيلي. لا تخلط آلاف التحديثات لمتاجر مختلفة أوتصحيحات يوم كامل في طلب مبهم واحد. سجّل Hash للـPayload ورقم المحاولة وحالة الاستجابة والأوقات، من دون تسجيل Access Tokens أوبيانات العملاء.

استجابة 201 ليست الحالة النهائية للمخزون

توثق واجهة Bulk استجابة نجاح HTTP 201 برسالة تقول إن التفاصيل أُدخلت إلى Queue وقد تحتاج عدة دقائق. إذن قبول النقل لا يثبت أن كل كمية ظهرت بالفعل. مثّل التسليم بحالات مثل `pending` و`accepted` و`verified` و`failed` و`unknown` بدل اعتبار الحركة مكتملة عند أول 201.

يصبح الفرق مهمًا عند Timeout. لا توثق الصفحة العامة مفتاح Idempotency يقدمه العميل لحركة Bulk. إعادة `increment` أو`decrement` بعد نتيجة مبهمة قد تطبق Delta مرتين إذا كان الطلب الأول قد قُبل. يمنع Deduplication داخل تطبيقك تكرار الإرسال لأحداث محلية معروفة، لكنه لا يثبت ما فعله الخادم البعيد بعد انقطاع الاتصال.

عند نتيجة مجهولة، أوقف معالجة هوية المخزون مؤقتًا، واقرأ الكمية الحالية وافحص Audit Trail قبل تقرير إعادة المحاولة. إذا بقي الدليل مبهمًا، أرسل الحركة إلى مراجعة بشرية أونفذ Reconciliation مضبوطًا. تكون Blind Retry آمنة فقط عندما ينص العقد البعيد صراحةً على Idempotency؛ لا تفترضها هنا.

طابق الكميات والتاريخ

شغّل Reconciliation مجدولًا مستقلًا عن التسليم الفوري. اقرأ كميات المنتجات لكل فرع مربوط وقارنها بالحالة المتوقعة في سجل التكامل. صنّف الفروقات: كتابات مقبولة لم تُتحقق بعد، SKUs غير مربوطة، تعديل يدوي من التاجر، حركة موجودة في ERP فقط، فرق توقيت الطلب، أوUpdate فشل فعلًا.

تضيف واجهة Audit سياقًا بإعادة الكمية القديمة والجديدة والـVariant والسبب والتاريخ والمستخدم المنفذ، وتدعم Filters منها الفرع والكلمة. هذه أدلة مفيدة، لكن الاستجابة الموثقة لا تعرض `movement_id` القادم من ERP. المطابقة بالهوية وDelta والسبب والنافذة الزمنية تبقى Correlation وليست هوية مضمونة من الطرف إلى الطرف. احتفظ بسجلك أنت كتاريخ التسليم المعتمد، واستخدم Audit في سلة كدليل خارجي.

لا تصلح كل فرق باستخدام Overwrite. افهم سبب الانحراف أولًا. قد يكون التصحيح اليدوي داخل لوحة التاجر شرعيًا، ويجب إعادته إلى ERP أوالموافقة عليه بدل محوه. احصر Overwrite في Onboarding أوPhysical Count معتمد أوReset مضبوط يتضمن Snapshot قبل التغيير وموافقة المشغل.

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

ابدأ بمتجر واحد وفرع واحد ومجموعة صغيرة من SKUs منخفضة المخاطر. خذ Opening Snapshot، ونفذ استلامًا معروفًا وتعديل تالف ومرتجعًا، ثم تحقق من الكمية وAudit. اختبر Timeout بعد الإرسال، وVariant غير مربوط، وSKU تغير اسمه، وحركتين متزامنتين للفرع نفسه.

راقب عمر Outbox، وعدد accepted غير verified، وفروق Reconciliation، وفشل Mapping، والنتائج المجهولة، وأخطاء Validation، والزمن من Commit في ERP إلى كمية متجر Verified. يجب أن يشير Alert إلى حركة وهوية مخزون، لا أن يقول فقط «فشلت المزامنة».

الهدف ليس نسخًا لحظيًا أعمى، بل Convergence مضبوط مع تفسير لكل وحدة. توفر سلة Bulk Deltas وسياق الفرع والأسباب والكميات الحالية وAudit View. ويضيف التكامل الموثوق هوية دائمة للحركات وتسليمًا مرتبًا وقواعد Retry حذرة ومطابقة ومسار موافقة للفروقات. بهذه التركيبة يستطيع التاجر توسيع عملياته دون تحويل تصحيحات المخزون إلى تخمين.

إعداد: Noor Yasser