# حالات استخدام واجهة التجارة البرمجية: سبعة مشاريع لا تستطيع بناءها بأداة جاهزة

> عندما لا تكون أداة المتجر الجاهزة هي الشكل المناسب: التجارة المضمّنة في منتجات SaaS، والكتالوجات متعددة الواجهات، والمتاجر ذات العلامة البيضاء، وتجربة المستخدم المخصصة، ووكلاء الذكاء الاصطناعي، وذكاء الأعمال المخصص. مع أمثلة برمجية من Shoprocket JS SDK.

Ryan Badger - 4 أغسطس 2025 - القراءة في 5 دقيقة

## لماذا توجد واجهة تجارة برمجية للتضمين

تعطيك معظم منصات التجارة الإلكترونية أداة جاهزة (widget): الصق سكربتًا فيظهر متجر. تعمل جيدًا مع 95% من المتاجر.

وتلجأ إلى واجهة التجارة البرمجية (API) حين تريد ما لا تفعله الأداة الجاهزة: عرض المنتجات داخل واجهتك الخاصة، أو تضمين إتمام الشراء داخل لوحة تحكم SaaS، أو توزيع كتالوج على عدة أسطح (ويب + جوال + صوت)، أو بناء مسارات شراء مخصصة لا تقدمها أي منصة جاهزة.

يقدّم Shoprocket الاثنين. [الأداة الجاهزة](https://v3.shoprocket.io/ar/blog/headless-commerce-the-three-tiers-the-real-options-and-which-one-you-probably-actually-want.md) هي الافتراضي. أما [`@shoprocket/core` SDK](https://github.com/shoprocket/shoprocket-js) فهو لحين تتجاوز الأداة الجاهزة، أو لمن لم يحتج إليها أصلًا.

## حالات تتطلب واجهة برمجية لا أداة جاهزة

هذه هي المشاريع التي لا تكفيها الأداة الجاهزة. إن كانت فكرتك في هذه القائمة، فأنت في منطقة الواجهة البرمجية.

### 1. التجارة داخل منتج SaaS الخاص بك

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

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

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// اعرض بطاقات الإضافات داخل لوحة SaaS
const addons = await sr.products.list({ category: 'addons' })

// ينقر المستخدم على زر «إضافة رصيد»
await sr.cart.addItem(addon.id, 1)
```

### 2. كتالوج متعدد الأسطح (ويب + تطبيق أصلي + صوت + دردشة)

كتالوج منتجات واحد يُعرض بشكل مختلف في كل مكان. متجر الويب يعرض تفاصيل المنتج كاملة، وتطبيق iOS الأصلي يعرض قائمة مضغوطة، والمساعد الصوتي يصف المنتجات بصوت مسموع، وتكامل الدردشة يرد برابط قابل للشراء.

تستدعي الأسطح الأربعة الواجهة البرمجية نفسها. حين تحدّث سعر منتج في لوحة تحكم Shoprocket، ينعكس على كل سطح عند الجلب التالي. دون مزامنة محتوى لكل سطح.

### 3. متاجر الشركاء بالعلامة البيضاء

أنت منصة يبيع فيها آخرون بضائعهم: سوق مجتمعي، أو دليل شركاء، أو شبكة امتياز لها مواقع فردية للوكلاء. لكل شريك علامة تجارية خاصة به، لا لك.

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

### 4. تجربة مشترٍ مخصصة بالكامل

مُهيّئات منتجات تفاعلية (تجميعات حواسيب مخصصة، ومجوهرات شخصية، وأثاث حسب الطلب). وعارضات منتجات ثلاثية الأبعاد. ومعارض صور "تسوّق الغرفة" حيث تضيف النقرة على نقطة في الصورة المنتج إلى السلة. وأزرار إعادة طلب سريعة داخل البريد.

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

### 5. وكلاء الذكاء الاصطناعي والتجارة الوكيلية

وكيل ذكاء اصطناعي (ChatGPT أو Claude أو وكيل مخصص) يتصفح المنتجات ويُتم عمليات الشراء نيابة عن المستخدم. يحتاج الوكيل إلى وصول برمجي إلى كتالوجك وسلتك، لا إلى أداة DOM عليه تحليلها.

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

### 6. التجارة المضمّنة في أدوات المحتوى

صفحة Notion يمكن أن تكون بعض كتلها قابلة للشراء. وتصميم Framer بنقاط ساخنة للشراء بنقرة. وأداة نشرة بريدية يستطيع فيها المشتركون النقر على بطاقة منتج والدفع دون مغادرة البريد. كلها مبنية فوق واجهة برمجية.

### 7. التقارير المخصصة ولوحات ذكاء الأعمال

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

## ما يقدمه SDK اليوم

من `@shoprocket/core`:

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

إضافةً إلى واجهة REST الكاملة لكل ما لا يغلّفه SDK بعد (الطلبات والعملاء والخصومات وكتابة المنتجات). راجع [api.shoprocket.io/docs](https://api.shoprocket.io/docs) للمرجع الكامل.

## حيث يكون نهج الواجهة البرمجية أولًا خطأ

بعض الحالات تكون فيها الأداة الجاهزة هي الخيار الصحيح والواجهة البرمجية مبالغة:

- **متجر بسيط فيه 10-200 منتج.** تعرضه الأداة الجاهزة على أكمل وجه؛ وكتابة واجهة كتالوج بنفسك إعادة لعمل محلول.
- **لا تملك طاقة هندسية مخصصة للواجهة الأمامية.** يتطلب نهج الواجهة البرمجية أولًا أن تبني وتصون حالات التحميل وواجهة المتغيّرات ومعالجة الأخطاء وإمكانية الوصول والترجمة (i18n) عبر 21 لغة بنفسك. هذه أسابيع من العمل تمنحك إياها الأداة الجاهزة مجانًا.
- **همّك الأول سرعة الإطلاق.** الأداة الجاهزة دقائق؛ ونهج الواجهة البرمجية أولًا أسابيع على الأقل.

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

## مشروع أول واقعي

أشيع مشروع من نوع "أحتاج الواجهة البرمجية": منتج SaaS يريد بيع رصيد أو اشتراكات أو إضافات لمرة واحدة داخل لوحة تحكمه.

الطريقة:

1. ثبّت `@shoprocket/core` في واجهتك الأمامية
2. أنشئ فئة في Shoprocket باسم "Add-ons" أو ما يشبهه
3. أضف المنتجات بالتسعير والوصف الدقيقين اللذين تريدهما
4. اعرض قائمة المنتجات في لوحة تحكمك بمكتبة مكوناتك الخاصة
5. عند النقر، أضف إلى السلة ثم حوّل إلى إتمام الشراء المستضاف من Shoprocket (أو ضمّن إتمام الشراء داخل الصفحة إن كنت مرتاحًا للعمل الإضافي)
6. اضبط نقطة نهاية webhook لاستقبال أحداث `order.paid` لتفعّل ما يفتحه الشراء (رصيد أو وصول أو شحنة)

هذا كل شيء. حفنة من الملفات، ويوم عمل لمن اعتاد استدعاء الواجهات البرمجية. بلا أداة جاهزة، ولا iframe، ولا تنازل في واجهة منتجك.

## ما لا ننصح به

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

> **نصيحة:** إن كنت تفكر في نهج الواجهة البرمجية أولًا لأن التنسيق الافتراضي للأداة الجاهزة لا يطابق علامتك التجارية، فجرّب [خطافات التنسيق في الأداة الجاهزة](https://github.com/shoprocket/shoprocket-js) أولًا. تقبل الأداة تخصيص CSS أكثر بكثير مما يبدو. وإعادة البناء الكاملة بالواجهة البرمجية جهد أثقل بكثير.

## باختصار

- **الأداة الجاهزة** = الافتراضي، وتغطي 95% من المتاجر
- **الواجهة البرمجية / SDK** = حين لا تكون الأداة الجاهزة الشكل المناسب (تجارة SaaS مضمّنة، متعدد الأسطح، علامة بيضاء، تجربة مخصصة، وكلاء الذكاء الاصطناعي، ذكاء أعمال مخصص)
- **ما يغطيه SDK اليوم:** المنتجات والسلة والجلسات؛ إضافةً إلى واجهة REST الكاملة للطلبات والعملاء والخصومات
- **نمط المشروع الأول:** لوحة SaaS تبيع رصيدًا أو إضافات عبر SDK مع تفعيل يقوده webhook
- **لا تعِد البناء بالواجهة البرمجية** لما تجيده الأداة الجاهزة؛ اختر شكلك

[ابدأ تجربة مجانية](https://app-v3.shoprocket.io/signup) واحصل على مفتاح عام؛ استخدام SDK مجاني في أي خطة من Shoprocket. 14 يومًا، دون بطاقة.

---

- HTML version: https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget
- Language: العربية (ar)
- Also in: [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)