طلبات Salla الخفيفة: Hydration بلا عواصف N+1

لم تعد استجابة الطلب expanded القديمة في Salla افتراضًا آمنًا للتكامل. تنص وثائق Order Details وList Orders الرسمية على توقف دعم expanded في 1 سبتمبر 2026؛ كما أن عقد Order Details الخفيف لا يضم shipments ولاorder items ولاpickup branch ولاcustomer groups. الإجابة الإنتاجية هي حفظ Canonical Order Projection صغيرة، وتنفيذ Hydration للموارد التي تحتاجها كل عملية فقط، ومعاملة Webhooks كإشارات تغيير، وإجراء Reconciliation من Salla بدل إعادة بناء الاستجابة الضخمة عبر N+1 Calls غير منضبطة.

هذا شرح هندسي عملي وليس خبرًا. يعتمد على وثائق Salla Merchant API الحالية وسجل التغييرات، وتم التحقق منها في 26 أكتوبر 2026. الحقول الموقوفة أوالمحذوفة من الاستجابة حقائق موثقة. أما نموذج التخزين وQueues والميزانيات ومسار التعافي أدناه فهي توصيات هندسية.

الخلاصة أولًا

عامل Light Order كغلاف ثابت للهوية والإجمالي والحالة وملخص الدفع ومرجع العميل. لا تفترض وجود Items أوShipments أوPickup Branch أوCustomer Groups داخلها. حدد احتياجات كل Consumer، واجلب الموارد الناقصة عبر Endpoints المخصصة، واحفظ كل Resource مع Freshness وSource Metadata مستقلة، ولا تنشر Canonical Snapshot داخلية إلا عندما تكتمل Dependencies المطلوبة للعملية.

الهدف ليس تقليل Calls بأي ثمن، بل جعل كل Call مقصودة ومحدودة وقابلة للرصد والتعافي.

ما الذي تغير في العقد؟

تقول وثائق Order Details إن الاستجابة الافتراضية Light بعد انتهاء Legacy Expanded، وتذكر صراحة أن Light Details تستبعد Shipments وItems وPickup Branch وCustomer Groups. كما توثق List Orders أن expanded=true لم يعد مدعومًا. ويسجل Changelog أن Customer Groups داخل customer object قديمة ويجب جلبها عبر Customer Details.

وفي 3 سبتمبر 2026، أضافت Salla مصفوفة payment_methods إلى عقود Create وUpdate وDuplicate وDetails وList وWebhooks للطلبات. هذا مهم لأن payment_method واحدة لا تمثل Split Tender بدقة. ابن منطق المال على Array عند وجودها، واحتفظ بالـLabel المفردة كملخص توافق فقط.

قد تتأخر أمثلة الوثائق عن العقد المعلن وتعرض حقولًا لا تضمنها Response Shape بعينها. ابن الاختبارات من الحقول التي يحتاجها تطبيقك، ثم اختبر Demo Store وFixtures شبيهة بالإنتاج. ظهور الحقل في Example واحدة دليل على المثال، وليس ضمانًا دائمًا.

مثّل الطلب كموارد لا كمستند واحد

يجعل Local Order Row ضخمة غياب Embedded Objects يبدو كفقد بيانات. استخدم Resource-oriented Projection:

{
  "store_id": "trusted-installation-id",
  "order_id": "1333249299",
  "reference_id": "275839672",
  "order_version": 42,
  "order_fetched_at": "2026-10-26T17:20:00Z",
  "items_state": "fresh",
  "items_fetched_at": "2026-10-26T17:20:01Z",
  "shipments_state": "not_required",
  "customer_groups_state": "stale",
  "payment_state": "fresh",
  "source_event_id": "durable-inbox-id"
}

افصل Core Order وItems وShipments وCustomer Profile وPayment Transactions في جداول أوVersioned Records. يحتاج كل Record إلى Source Identity ووقت الرصد وContent Digest وآخر Fetch ناجحة. Null تعني قيمة null موثقة. Missing تعني لم تعدها الاستجابة. Not Requested تعني أن Workflow لم تحتجها. Failed تعني محاولة Hydration لم تكتمل. لا تدمج هذه الحالات في Database Value واحدة.

عرّف Hydration Profiles قبل كتابة الكود

أنشئ Profiles مسماة مرتبطة بأفعال العمل:

يقبل API Client اسم Profile بدل Booleans موزعة عبر Controllers. يمنع هذا Support Page من تشغيل أربع Remote Requests لكل صف، ويجعل تخطيط Rate Limits قابلًا للقياس.

ابن Hydration Planner آمنة للتكرار

عندما يكتشف Webhook أوBackfill طلبًا، اكتب Inbox Record أولًا. نفذ Upsert للـLight Envelope، ثم خطط للموارد الناقصة أوالقديمة فقط. استخدم Key مثل store_id + order_id + resource + desired_revision حتى تتقارب Duplicate Webhooks وJob Retries على العمل نفسه.

webhook/backfill
  -> durable inbox
  -> upsert light order
  -> evaluate hydration profile
  -> enqueue missing resources
  -> validate and persist each resource
  -> publish canonical projection

لا تبق Webhook HTTP Request مفتوحة أثناء Hydration. أرسل Acknowledge بعد جعل Inbox دائمة، ثم عالج Asynchronously. Webhooks تشير إلى تغير حالة؛ وليست Database Replication كاملة أومرتبة. يبقى Periodic Reconciliation ضروريًا.

تجنب N+1 دون إعادة إنشاء Expanded

نمط الفشل واضح: تعرض 30 طلبًا، ثم تستدعي Details وItems وShipments وCustomer Details لكل واحد. تتحول الصفحة الواحدة إلى أكثر من 100 Request، ويزيد Latency، وتضخم Retries الحمل، ويجعل فشل Dependency واحدة الشاشة كلها غير موثوقة.

استخدم هذه الضوابط:

• نفذ Hydration للطلبات المحددة أوالقابلة للإجراء فقط، لا لكل صف؛
• مرر العمل عبر Queue مع Per-store Concurrency وRequest Budgets؛
• Cache للموارد الثابتة أوالبطيئة التغير مع Freshness صريحة؛
• Deduplicate لنفس Resource Fetch عبر المستخدمين والWorkers؛
• أعط أوامر Fulfilment والمال أولوية على Enrichment؛
• أوقف Enrichment عند انخفاض Rate-limit Budget؛
• احفظ Partial Progress حتى تستأنف Retry بدل إعادة الطلب كاملًا.

تطلب إرشادات List Orders صفحات متسلسلة، وتوصي بـper_page=30، وتحذر من تخطي الصفحات، وتطلب إكمال Pagination خلال نافذة Cache مدتها 15 دقيقة. لذلك يحتاج Backfill الموثوق Page Checkpoint وDate Window محدودة. اجعل Hydration Jobs بعد Discovery حتى لا تكسر Calls البطيئة عقد Pagination المتسلسلة.

عامل Split Payments كتوزيعات مالية

يمكن أن تصف payment_methods أكثر من Method وAmount وTransaction Reference. احفظ كل عنصر Allocation بهوية محلية ثابتة. لا تجمع Strings مالية باستخدام Binary Float؛ حوّلها إلى Minor Units أوExact Decimal واحتفظ بالعملة.

{
  "order_id": "1333249299",
  "allocations": [
    {"method": "bank", "amount_minor": 1093, "reference": null},
    {"method": "credit_card", "amount_minor": 546, "reference": "9682442091042222"}
  ]
}

تحقق أن Currency التوزيع تطابق Currency الطلب، وقارن المجموع بالمبلغ المدفوع المعتمد في Financial Workflow. الاختلاف Reconciliation Exception وليس قيمة تعدلها بصمت. احجب Transaction References عن Logs وAnalytics العامة.

عامل Webhooks كإشارات Invalidation

توثق Salla نماذج Order Webhooks وعائلات Events متعددة. اربط كل عائلة بـInvalidation Map صغيرة:

لا تفترض ترتيب التسليم. يجب ألا يكتب Event متأخر حالة أقدم فوق Fetch أحدث. سجل Event Receive Time وأي Platform Timestamps متاحة، لكن احسم التقارب عبر Authoritative Read-back وقواعد Resource Versions.

انشر Canonical Order داخلية بأمان

لا تجعل Downstream Systems تعتمد مباشرة على JSON الخاصة بـSalla. انشر Typed Internal Contract مع Optionality وProvenance صريحة:

{
  "order_key": "store-42:1333249299",
  "status": "in_progress",
  "currency": "SAR",
  "total_minor": 1639,
  "items": {"state": "fresh", "count": 2},
  "shipments": {"state": "not_required"},
  "payments": {"state": "fresh", "allocated_minor": 1639},
  "observed_at": "2026-10-26T17:20:01Z"
}

Version هذا Schema. احتفظ بـRaw Source Snapshots بشكل خاص للتشخيص، لكن لا تعرضها كDomain Contract. وعند نقص Resource مطلوبة، انشر Typed Incomplete State أواحجب Action-specific Projection؛ لا تخترع Items Array فارغة يفسرها Downstream كطلب ملغي.

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

شغل Reconciliation على الطلبات المتغيرة حديثًا والحالات المهمة للعمل. قارن Salla Core وItem Identities وQuantities وShipment References وPayment Allocations الحالية مع Local Projections. سجل Difference قبل الإصلاح، وطبق Idempotent Update، ثم تحقق من Convergence.

أعط الأولوية لـ:

• Paid Orders بلا Item Hydration؛
• Fulfilment-ready Orders بلا Shipment Projection؛
• Refunds لها Payment Allocation قديمة؛
• Webhook Events ذات Hydration فاشلة أوفي Dead Letter؛
• Orders تجاوزت Freshness فيها Workflow SLA.

استخدم Bounded Lookback وPage Checkpoints. لا تعاود مسح المتجر كله كل دقائق.

أفضل الممارسات

• ابن على Light Contract المعلنة لاRich Sample Response.
• افصل Resource Absence عن null وNot Requested وFetch Failure.
• استخدم Hydration Profiles مرتبطة بأفعال العمل.
• اجعل Webhook Ingestion سريعة ودائمة ونفذ Hydration Asynchronously.
• افرض Per-store Concurrency وRequest Budgets.
• احفظ Payment Allocations بدقة وطابق إجمالياتها.
• Version للـCanonical Schema واحتفظ بـProvenance.
• اختبر Fixtures القديمة والجديدة أثناء الترحيل.

Anti-patterns

• إرسال expanded=true وافتراض أن Parameter المتجاهلة ما زالت تعمل.
• جلب Details وItems وShipments وCustomer لكل List Row.
• تفسير Missing Embedded Array كحقيقة Business فارغة.
• استخدام payment_method واحدة لمحاسبة Split Payment.
• إعادة بناء الطلب كاملًا داخل Webhook Request.
• السماح لـDelayed Event بالكتابة فوق Authoritative Fetch أحدث.
• تسجيل Customer وTransaction Payloads كاملة للتسهيل.

Checklist الترحيل

1. احصر كل Field تُقرأ من List Orders وOrder Details وWebhooks.
2. صنف كل Field كـCore أوResource مخصصة.
3. أضف Resource State وFreshness صريحتين.
4. أدخل Hydration Profiles وDurable Work Queue.
5. حلل payment_methods كـExact Allocations.
6. شغل Contract Fixtures للحالات Missing وNull.
7. نفذ Shadow للـLight Pipeline وقارن Canonical Outputs.
8. رحّل Consumers Workflow واحدة كل مرة.
9. احذف expanded=true وأنشئ Alert لأي استخدام عرضي.
10. طابق Recent Orders وتحقق أن لا Action استخدمت بيانات ناقصة.

اقرأ أيضًا: Backfills الطلبات في Salla، وState Machine لطلبات Salla وZid، وتدوير Webhook Endpoint في Salla، ومركز هندسة التجارة الإلكترونية، وخدمات تكامل Salla وZid.

المراجع الأساسية

• Salla — Order Details
• Salla — List Orders
• Salla — List Order Items
• Salla — Orders Webhook Events Model
• Salla Merchant API changelog
• Wikimedia Commons — Warehouse interior with shelving and packages
• Creative Commons Attribution 2.0

إعداد: Noor Yasser