كيفية ربط كتالوج منتجات رقمية بمنصّة سوق

إجابة موجزة

ربط المنتجات الرقمية بمنصّة سوق يعني دمج API مورّد في بنية منصّتك القائمة لإضافة بطاقات الهدايا وشحن الألعاب ومنتجات مماثلة كفئة جديدة. للتكامل ثلاث مراحل — استيراد الكتالوج (سحب المنتجات من المورّد وإنشاء قوائم)، وتدفّق الطلب (تشغيل API المورّد عند الشراء)، وإدارة المخزون (إبقاء القوائم متزامنة مع توافر المورّد). العمل التقني بناء يُنفَّذ مرة واحدة؛ والعمليات الجارية مؤتمتة.

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

الخلاصة الأساسية — المنتجات الرقمية هي فئة المنتجات الأكثر ملاءمة لتكامل الواجهة الخلفية عند توسيع منصّة السوق. لا مستودع، ولا لوجستيات، ولا عملية إرجاع. وسلسلة التنفيذ كاملةً هي — استدعاء API يدخل ← كود يخرج. والتعقيد في إدارة الكتالوج (دقّة المنطقة، والتسمية، والتسعير) وموثوقية تدفّق الطلب — لا في العمليات المادية.

لمن هذا الدليل

• مشغّلو منصّات الأسواق الذين يضيفون المنتجات الرقمية كفئة منتجات جديدة
• المطوّرون الذين يدمجون API مورّد منتجات رقمية في منصّة قائمة
• مديرو المنتجات الذين يحدّدون متطلبات تكامل المنتجات الرقمية

نظرة عامة على بنية التكامل

Marketplace                    Supplier API
    │                               │
    ├─ Phase 1: Catalog Import ─────▶ GET /api/products/?category_id_or_slug=...
    │  Pull all products             Returns product ids, names, prices, regions
    │  Create marketplace listings   (run daily or on change)
    │                               │
    ├─ Phase 2: Stock Sync ─────────▶ GET /api/products/{id_or_slug}
    │  Check before showing product  Availability reflected in product data
    │  (real-time on product page)   │
    │                               │
    ├─ Phase 3: Order Flow ─────────▶ POST /api/orders/
    │  Buyer completes checkout       { "items": [{ "itemId": "product_01k...", "quantity": N }] }
    │  Marketplace deducts payment    │
    │                          ◀─────┤ { order_id, items[].externalData when completed }
    │  Deliver code to buyer          │
    │                               │
    └─ Phase 4: Reconciliation ─────▶ GET /api/orders/?statuses=completed&limit=200&offset=0
       Daily finance export          Paginate to reconcile all completed orders

المرحلة 1 — استيراد الكتالوج

ما الذي يُرجِعه الـ API

تُرجِع نقطة نهاية كتالوج المورّد النموذجية —

{
  "results": [
    {
      "id": "product_01krgfgww8eth9xvvysd6y7r4j",
      "name": "Steam Gift Card $20",
      "region": "US",
      "currency": "USD",
      "face_value": 20.00,
      "price": 18.40,
      "category": "gaming",
      "available": true
    }
  ]
}

كيفية التعيين على قوائم منصّة السوق

القواعد —

• قائمة منصّة سوق واحدة لكل معرّف منتج لدى المورّد — بلا دمج
• ضمّن المنطقة في عنوان المنتج دائماً
• احفظ معرّف المنتج id لدى المورّد في قاعدة بياناتك لاستخدامه كـ itemId عند تقديم الطلبات

جدول تحديث الكتالوج

المرحلة 2 — إدارة المخزون

اعرض المنتجات المتوفّرة في المخزون فقط للمشترين. تحقّق من التوافر عند نقطتين —

1. تحميل صفحة قائمة المنتج — استعلم GET /api/products/{id_or_slug} لعرض "متوفّر" أو "غير متوفّر حالياً" (التوافر منعكس في بيانات المنتج)
2. بدء الدفع — تحقّق من التوافر مرة أخرى؛ واحظر الدفع إذا نفد المخزون منذ تحميل الصفحة

GET /api/products/steam-20-usd
→ { "id": "product_01k...", "name": "Steam Gift Card $20", "available": true, ... }

خزّن استجابات المنتج مؤقتاً لمدة 5–15 دقيقة (لا أطول) لتقليل الحمل على الـ API مع البقاء محدَّثاً.

المرحلة 3 — تدفّق الطلب

عندما يُكمِل المشتري عملية الدفع —

1. تؤكّد منصّة السوق الدفع (يُحاسَب المشتري)
2. استدعِ POST /api/orders/ مع { "items": [{ "itemId": "product_01k...", "quantity": N }] }
3. استلم الأكواد في الاستجابة (متزامن) أو باستطلاع GET /api/orders/{order_id} حتى الاكتمال (لا webhooks لدى FoxReload)؛ الأكواد في items[].externalData
4. خزّن order_id والأكواد في قاعدة بياناتك
5. سلّم الكود للمشتري (إشعار داخل التطبيق، أو بريد إلكتروني، أو صفحة سجل الطلبات)
6. أشّر على الطلب كمكتمل

معالجة الأخطاء —

المرحلة 4 — التسوية

اسحب سجل الطلبات من API المورّد يومياً للتسوية المالية —

GET /api/orders/?statuses=completed&limit=200&offset=0
→ [ { order_id, items, timestamp }, ... ]   (paginate with offset to cover full period)

طابِقها مع سجلّات معاملات منصّة السوق لديك. وتتطلّب التباينات التحقيق.

استراتيجية التسعير للمنتجات الرقمية في منصّة السوق

اضبط سعر التجزئة فوق تكلفة الجملة + عمولة منصّة السوق + رسوم الدفع + الهامش المستهدف —

Retail price = Wholesale ÷ (1 − marketplace_commission% − payment_fee% − target_margin%)

مثال (عمولة منصّة سوق 10%، دفع بالبطاقة 2.5%، هامش مستهدف 5%) —

Retail = $18.40 ÷ (1 − 0.10 − 0.025 − 0.05)
Retail = $18.40 ÷ 0.825
Retail = $22.30

تحقّق من أن سعر التجزئة هذا تنافسي. وإن لم يكن كذلك، فإمّا أن تتفاوض على سعر جملة أفضل، أو أن تقيّم ما إذا كانت هذه القناة قابلة للتطبيق لهذا المنتج.

توصيات حجم الكتالوج

ابدأ مركّزاً؛ وتوسّع بعد التحقّق من التكامل —

البدء بـ 200 SKU قبل التحقّق من تدفّق التنفيذ يخلق تعقيداً في تصحيح الأخطاء. ابدأ ضيّقاً؛ وتوسّع بعد إثبات خط الأنابيب.

قائمة التحقّق التقنية

الكتالوج —

• بيانات اعتماد API المورّد مُهيّأة في بيئة الإنتاج
• مهمّة استيراد الكتالوج مجدولة (يومياً كحدّ أدنى) عبر GET /api/products/?category_id_or_slug=...
• كل معرّف منتج للمورّد (itemId) مُعيَّن بنسبة 1:1 على قائمة منصّة السوق
• المنطقة مضمَّنة في عنوان المنتج لجميع المنتجات الإقليمية
• سعر التجزئة محسوب بتطبيق صيغة الهامش لكل منتج

التوافر —

• فحص التوافر (GET /api/products/{id_or_slug}) مُنفَّذ عند تحميل صفحة المنتج
• فحص التوافر مُنفَّذ عند بدء الدفع
• مدّة صلاحية التخزين المؤقت مضبوطة على 5–15 دقيقة
• المنتجات غير المتوفّرة مخفيّة أو مؤشّر عليها كغير متوفّرة

الطلبات —

• استدعاء إنشاء الطلب مُطلَق عند تأكيد الدفع (لا عند بدء الدفع)
• معرّف طلب المورّد محفوظ في قاعدة بيانات طلباتك
• الكود مُسلَّم للمشتري عند اكتمال الطلب
• حالات الخطأ معالَجة — انتهاء المهلة، والفشل، ونفاد المخزون
• التنبيه مُهيّأ لحالات فشل الطلبات التي تتجاوز الحدّ

الماليّة —

• مهمّة تسوية يومية مقابل API طلبات المورّد
• تنبيه التباينات مُهيّأ
• تكلفة الجملة مُسجَّلة لكل طلب لتقارير الهامش