DEV Community

Cover image for ما هو API التجارة بلا رأس؟ MACH، التجارة القابلة للتركيب، وطبقة العقود
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

ما هو API التجارة بلا رأس؟ MACH، التجارة القابلة للتركيب، وطبقة العقود

إذا بنيت واجهة متجر مخصصة لا تشبه قالبًا جاهزًا، فغالبًا تعمل واجهة برمجة تطبيقات تجارة لارأسية (Headless Commerce API) خلف الكواليس. هذه الواجهة تكشف منطق التجارة في الخلفية: المنتجات، الأسعار، السلة، الدفع، الطلبات، والعملاء، بحيث تستطيع أي واجهة أمامية استخدامها دون الارتباط بقالب منصة محدد. في هذا الدليل سنحوّل الفكرة إلى خطوات عملية: ما الذي تفصله اللارأسية، كيف ترتبط بـ التجارة التركيبية و MACH، وكيف تصمم عقد API يمكن لفريق الواجهة الأمامية والجوال والشركاء الاعتماد عليه. الفكرة امتداد مباشر لما ناقشناه في البرامج تتجه نحو اللارأسية وواجهة برمجة تطبيقاتك أصبحت الآن هي المنتج.

جرّب Apidog اليوم

ماذا تعني "اللارأسية" في التجارة

في منصة التجارة التقليدية، يعيش كل شيء في نظام واحد:

  • كتالوج المنتجات
  • التسعير والمخزون
  • السلة والدفع
  • الطلبات والعملاء
  • صفحات HTML والقوالب التي يراها المستخدم

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

في التجارة اللارأسية، تفصل النظام إلى طبقتين:

  1. واجهة خلفية تجارية: تدير المنتجات، الأسعار، المخزون، السلة، الطلبات، والعملاء.
  2. واجهة أمامية مستقلة: موقع React، تطبيق جوال، واجهة kiosk، مساعد صوتي، أو أي قناة أخرى.

الربط بينهما يتم عبر API.

مثال مبسط:

React Storefront  --->  Commerce API  --->  Commerce Backend
Mobile App        --->  Commerce API  --->  Products / Cart / Orders
Partner App       --->  Commerce API  --->  Customers / Inventory
Enter fullscreen mode Exit fullscreen mode

"الرأس" هو طبقة العرض. إزالة الرأس تعني أن الواجهة الخلفية لا تفرض عليك طريقة العرض، بل تعرض منطق التجارة عبر واجهة برمجة تطبيقات.

متى تختار التجارة اللارأسية؟

اخترها عندما تحتاج إلى:

  • واجهة متجر مخصصة بالكامل.
  • نفس الخلفية لعدة قنوات: ويب، جوال، نقاط بيع، شركاء.
  • فصل دورات نشر الواجهة الأمامية عن الخلفية.
  • استخدام إطار عمل مثل Next.js أو Remix أو Nuxt بدل قالب المنصة.
  • تحسين تجربة الأداء والتخصيص على مستوى الواجهة.

لكن انتبه للمقايضة: أنت مسؤول عن بناء واستضافة الواجهة الأمامية، وربطها بالـ API، ومعالجة حالات الخطأ، والمصادقة، وتجربة الدفع.

اللارأسية مقابل التركيبية مقابل MACH

هذه المصطلحات متقاربة لكنها ليست نفس الشيء.

المصطلح ما يصفه النطاق
التجارة اللارأسية (Headless commerce) فصل الواجهة الأمامية عن واجهة خلفية تجارية واحدة عبر API واجهة خلفية واحدة، واجهة أمامية واحدة أو عدة واجهات
التجارة التركيبية (Composable commerce) تجميع عدة خدمات مستقلة: كتالوج، بحث، مدفوعات، PIM، OMS عدة خدمات مستقلة مرتبطة عبر APIs
MACH مبادئ معمارية: Microservices، API-first، Cloud-native SaaS، Headless فلسفة معمارية وليست منتجًا واحدًا

اللارأسية هي الحالة الأبسط: يمكن أن تستخدم واجهة خلفية واحدة متجانسة، طالما أن واجهة المتجر تتعامل معها عبر API.

أما التجارة التركيبية فتذهب أبعد من ذلك. بدل الاعتماد على محرك تجارة واحد لكل شيء، تجمع خدمات متخصصة:

Storefront
   |
   |-- Product API
   |-- Search API
   |-- Pricing API
   |-- Payment API
   |-- Inventory API
   |-- Order API
Enter fullscreen mode Exit fullscreen mode

أما MACH، فحسب تحالف MACH، تعني:

  • Microservices: خدمات صغيرة مستقلة.
  • API-first: كل وظيفة مكشوفة ومصممة أولًا عبر API.
  • Cloud-native SaaS: خدمات سحابية الأصل.
  • Headless: فصل العرض عن منطق الخلفية.

النقطة العملية هنا: في معماريات MACH، الـ API ليست إضافة. هي العقد الأساسي بين كل أجزاء النظام، وهذا هو نفس منطق التعامل مع واجهة برمجة التطبيقات الخاصة بك كمنتج.

ما الذي تكشفه واجهة برمجة تطبيقات التجارة اللارأسية؟

معظم واجهات التجارة اللارأسية تغطي نفس المجالات الأساسية. عند تصميم API لمتجر لارأسي، ابدأ بهذه الموارد.

1. المنتجات والكتالوج

تحتاج الواجهة الأمامية إلى قراءة المنتجات، المتغيرات، الصور، الأسعار، والتصنيفات.

مثال REST:

GET /products?category=shoes&limit=20
Enter fullscreen mode Exit fullscreen mode

استجابة محتملة:

{
  "items": [
    {
      "id": "prod_123",
      "slug": "running-shoe",
      "name": "حذاء جري",
      "price": {
        "amount": 7900,
        "currency": "SAR"
      },
      "images": [
        "https://example.com/images/shoe.png"
      ],
      "variants": [
        {
          "id": "var_1",
          "size": "42",
          "color": "black",
          "inStock": true
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "nextCursor": "abc123"
  }
}
Enter fullscreen mode Exit fullscreen mode

2. البحث والتصفح

تحتاج واجهة المتجر إلى فلترة وترتيب المنتجات.

GET /search?q=حذاء&brand=nike&sort=price_asc
Enter fullscreen mode Exit fullscreen mode

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

query SearchProducts($query: String!) {
  searchProducts(query: $query) {
    id
    name
    slug
    price {
      amount
      currency
    }
    images
  }
}
Enter fullscreen mode Exit fullscreen mode

3. السلة

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

POST /carts
Enter fullscreen mode Exit fullscreen mode 
{
  "currency": "SAR"
}
Enter fullscreen mode Exit fullscreen mode

إضافة عنصر:

POST /carts/cart_123/items
Enter fullscreen mode Exit fullscreen mode 
{
  "variantId": "var_1",
  "quantity": 2
}
Enter fullscreen mode Exit fullscreen mode

استجابة السلة:

{
  "id": "cart_123",
  "items": [
    {
      "variantId": "var_1",
      "name": "حذاء جري",
      "quantity": 2,
      "unitPrice": 7900,
      "lineTotal": 15800
    }
  ],
  "totals": {
    "subtotal": 15800,
    "discount": 0,
    "tax": 2370,
    "grandTotal": 18170
  }
}
Enter fullscreen mode Exit fullscreen mode

4. العملاء

تتعامل واجهة العملاء مع التسجيل، تسجيل الدخول، العناوين، وسجل الطلبات.

GET /me/orders
Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

5. المخزون والتسعير

تحتاج الواجهة إلى السعر الصحيح حسب السوق، العملة، العميل، أو القناة.

GET /products/prod_123/availability?region=riyadh
Enter fullscreen mode Exit fullscreen mode 
{
  "productId": "prod_123",
  "available": true,
  "quantity": 12,
  "region": "riyadh"
}
Enter fullscreen mode Exit fullscreen mode

Storefront API مقابل Admin API

من الأفضل فصل واجهات القراءة الموجهة للعملاء عن واجهات الإدارة.

Storefront API

تستخدمها واجهة المتجر أو التطبيق:

  • قراءة المنتجات.
  • البحث.
  • إنشاء السلة.
  • الدفع.
  • قراءة حساب العميل.

خصائصها:

  • موجهة للقراءة غالبًا.
  • يجب أن تكون آمنة للاستخدام من الواجهة الأمامية.
  • تحتاج إلى rate limits وسياسات CORS واضحة.
  • لا تكشف عمليات إدارية حساسة.

Admin API

تستخدمها أنظمة الإدارة والعمليات الداخلية:

  • إنشاء المنتجات.
  • تحديث المخزون.
  • إدارة الطلبات.
  • تعديل الأسعار.
  • تكاملات back-office.

خصائصها:

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

REST أم GraphQL؟

كلاهما شائع في التجارة اللارأسية.

استخدم REST عندما:

  • تريد موارد واضحة مثل /products و/carts.
  • لديك فريق معتاد على HTTP التقليدي.
  • تريد caching أبسط على مستوى CDN.
  • تريد توثيقًا مباشرًا عبر OpenAPI.

استخدم GraphQL عندما:

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

مثال الفرق:

REST:

GET /products/prod_123
GET /products/prod_123/reviews
GET /products/prod_123/recommendations
Enter fullscreen mode Exit fullscreen mode

GraphQL:

query ProductPage($id: ID!) {
  product(id: $id) {
    id
    name
    description
    price {
      amount
      currency
    }
    reviews {
      rating
      comment
    }
    recommendations {
      id
      name
      slug
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

إذا كنت تقارن بينهما، راجع REST مقابل GraphQL.

المنصات الرئيسية

ينقسم سوق التجارة اللارأسية عادة إلى محركات SaaS ومحركات مفتوحة المصدر.

قبل اختيار منصة، تحقق من:

  • نموذج الاستضافة.
  • حدود API.
  • دعم REST أو GraphQL.
  • نموذج التسعير.
  • دعم تعدد الأسواق والعملات.
  • سهولة التكامل مع الدفع، الضرائب، الشحن، وOMS.

لماذا يصبح عقد API هو نقطة التحكم الأساسية؟

بعد فصل واجهة المتجر، يصبح عقد API هو الاتفاق بين الفرق.

فريق الواجهة الأمامية يحتاج إلى معرفة:

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

فريق الجوال يحتاج نفس العقد. الشركاء يحتاجونه أيضًا. أي تغيير غير متوافق قد يكسر عدة مستهلكين في نفس الوقت.

مثال تغيير خطير:

{
  "price": 7900
}
Enter fullscreen mode Exit fullscreen mode

ثم تغييره فجأة إلى:

{
  "price": {
    "amount": 7900,
    "currency": "SAR"
  }
}
Enter fullscreen mode Exit fullscreen mode

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

لذلك تحتاج إلى قواعد واضحة:

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

نمط عملي لتصميم API تجارة لارأسية

ابدأ بالعقد قبل كتابة الكود.

الخطوة 1: حدد الموارد الأساسية 

/products
/categories
/search
/carts
/customers
/orders
/checkout
/inventory
/prices
Enter fullscreen mode Exit fullscreen mode

الخطوة 2: عرّف الاستجابات الأساسية

مثال Product:

{
  "id": "prod_123",
  "slug": "running-shoe",
  "name": "حذاء جري",
  "description": "حذاء مناسب للجري اليومي",
  "price": {
    "amount": 7900,
    "currency": "SAR"
  },
  "images": [],
  "variants": [],
  "availability": {
    "inStock": true
  }
}
Enter fullscreen mode Exit fullscreen mode

الخطوة 3: عرّف حالات الخطأ

لا تترك الواجهة الأمامية تخمن.

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "الكمية المطلوبة غير متوفرة",
    "details": {
      "variantId": "var_1",
      "availableQuantity": 1
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

الخطوة 4: أضف أمثلة واقعية

الأمثلة تساعد الواجهة الأمامية على البناء قبل اكتمال الخلفية.

اكتب أمثلة لـ:

  • منتج متوفر.
  • منتج نفد من المخزون.
  • سلة فارغة.
  • سلة بها خصم.
  • فشل الدفع.
  • طلب مكتمل.

الخطوة 5: شغّل خادمًا وهميًا

إذا كان العقد مكتوبًا كمواصفة OpenAPI أو GraphQL schema، يمكن لفريق الواجهة الأمامية بناء الواجهة ضد mock server قبل أن تكون الخلفية جاهزة.

Frontend ---> Mock API ---> Example responses
Enter fullscreen mode Exit fullscreen mode

ثم لاحقًا:

Frontend ---> Real API ---> Commerce backend
Enter fullscreen mode Exit fullscreen mode

أين يتناسب Apidog؟

Apidog لا يشغّل متجرك. ليس محرك تجارة، ولا CMS، ولا بوابة دفع، ولا يجعل بنيتك لارأسية تلقائيًا.

دوره العملي هو إدارة طبقة API-first:

  • تصميم العقد.
  • إنشاء mock server.
  • اختبار الطلبات والاستجابات.
  • توثيق API.
  • مشاركة العقد مع الفرق والشركاء.

صورة توضح واجهة Apidog مع عناصر تصميم واجهة برمجة التطبيقات

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

1. صمم العقد قبل الكود

نمذج Storefront API أو Admin API كمواصفة OpenAPI في Apidog.

مثال موارد أولية:

GET    /products
GET    /products/{id}
POST   /carts
POST   /carts/{cartId}/items
PATCH  /carts/{cartId}/items/{itemId}
POST   /checkout
GET    /orders/{id}
Enter fullscreen mode Exit fullscreen mode

2. استخدم mock API لبدء الواجهة مبكرًا

قبل اكتمال محرك التجارة، شغّل mock server من المواصفة.

فريق الواجهة الأمامية يستطيع بناء:

  • صفحة المنتجات.
  • صفحة تفاصيل المنتج.
  • تجربة السلة.
  • رسائل الخطأ.
  • حالات نفاد المخزون.

اقرأ المزيد في شرح واجهة برمجة التطبيقات الوهمية.

3. اختبر العقد في CI

أضف اختبارات API إلى مسار النشر حتى تلتقط التغييرات الكاسرة قبل الإنتاج.

مثال منطقي لما يجب اختباره:

  • GET /products/{id} يعيد الحقول المتفق عليها.
  • السعر يحتوي amount وcurrency.
  • السلة تعيد totals.
  • أخطاء المخزون تعيد OUT_OF_STOCK.
  • الحقول المطلوبة لا تختفي بين الإصدارات.

4. وثّق API للشركاء

التوثيق التفاعلي يقلل الأسئلة المتكررة ويعطي الجميع مصدرًا واحدًا للحقيقة:

  • فرق الويب.
  • فرق الجوال.
  • تكاملات الولاء.
  • مزودو الضرائب.
  • الأسواق الخارجية.
  • فرق العمليات الداخلية.

إذا أردت تجربة سير العمل، يمكنك تنزيل Apidog واستيراد مواصفة موجودة.

أسئلة مكررة

هل التجارة اللارأسية هي نفسها التجارة التركيبية؟

لا. التجارة اللارأسية تفصل الواجهة الأمامية عن واجهة خلفية تجارية واحدة عبر API. التجارة التركيبية تجمع عدة خدمات مستقلة، مثل البحث، المدفوعات، الكتالوج، وOMS، في تجربة واحدة. كل حزمة تركيبية تكون لارأسية غالبًا، لكن النظام اللارأسي بواجهة خلفية واحدة ليس بالضرورة تركيبيًا.

هل أحتاج إلى GraphQL لواجهة برمجة تطبيقات التجارة اللارأسية؟

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

هل يمكنني اختبار واجهة تجارة لارأسية قبل بناء الخلفية؟

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

ما هو تحالف MACH؟

تحالف MACH هو مجموعة صناعية تشكلت في عام 2020 لتعزيز حزم التقنيات المفتوحة والأفضل في فئتها، المبنية على مبادئ Microservices، API-first، Cloud-native SaaS، وHeadless. MACH ليست منتجًا واحدًا، بل مجموعة مبادئ معمارية.

العقد هو المتجر

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

لذلك لا تبدأ فقط باختيار إطار الواجهة. ابدأ بتصميم العقد:

  • ما الموارد؟
  • ما شكل الاستجابات؟
  • كيف تظهر الأخطاء؟
  • كيف ستتعامل مع الإصدارات؟
  • كيف ستختبر التغييرات؟
  • كيف سيقرأ الشركاء التوثيق؟

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

Top comments (0)