زوج مفاتيح API
للخوادم والتكاملات الثابتة (ERP، CRM، سكربتات). ترسل x-api-key و x-api-secret مع كل طلب، والصلاحيات تُحدَّد عند إنشاء المفتاح.
يعمل حتى تلغيه أو ينتهي
المطورون
المصادقة والصلاحيات
طريقتان للوصول إلى واجهة تاجر: زوج مفاتيح API للتكاملات الثابتة، واتصال MCP عبر OAuth لمساعدات الذكاء الاصطناعي.
- x-api-key
- OAuth 2.1 + PKCE
- صلاحيات لكل متجر
أيهما تختار؟
اختر حسب من يتصل: نظامك أم مساعد ذكاء اصطناعي يعمل نيابة عن التاجر.
اتصال MCP عبر OAuth
لمساعدات الذكاء الاصطناعي. التاجر يوافق من شاشة الموافقة، والمساعد يستخدم رمزًا يبدأ بـ tmcp_ في ترويسة Authorization: Bearer.
رمز قصير العمر مع تجديد
كلاهما مرتبط بمتجر واحد
كل مفتاح وكل رمز يعمل داخل متجر واحد فقط، وأي طلب بصلاحية غير ممنوحة يُرفض.
عزل بين المتاجر
من أين يُنشأ وكيف يُلغى
مفاتيح API: الإنشاء
من لوحة التاجر ← المطور ← مفاتيح API. يظهر السر مرة واحدة فقط عند الإنشاء، فاحفظه في مكان آمن.
مفاتيح API: الإلغاء
من الصفحة نفسها ألغِ المفتاح فيتوقف عن العمل فورًا. إنشاء المفاتيح وإلغاؤها لمديري المتجر والموظفين.
اتصال MCP: الإنشاء
يبدأ من تطبيق المساعد الذي يفتح شاشة الموافقة؛ تراجع الصلاحيات المطلوبة ثم توافق أو ترفض.
اتصال MCP: الإلغاء
من لوحة التاجر ← المطور ← اتصالات الذكاء الاصطناعي (/merchant/developer/ai-connections) يمكنك إلغاء أي اتصال.
مسار OAuth 2.1 مع PKCE
نتبع مواصفة تفويض MCP: عملاء عامون، وPKCE بطريقة S256 فقط.
- 01
١. الاكتشاف
العميل يقرأ بيانات المورد من /.well-known/oauth-protected-resource/api/v1/mcp/merchant ثم بيانات خادم التفويض لمعرفة نقاط النهاية.
- 02
٢. التسجيل الديناميكي
العميل العام يسجّل نفسه تلقائيًا (RFC 7591) ولا يحتاج سرًا مشتركًا.
- 03
٣. الموافقة
يوجَّه التاجر إلى شاشة الموافقة، ويرسل العميل PKCE بطريقة S256 فقط. يراجع التاجر الصلاحيات المعروضة ويوافق أو يرفض.
- 04
٤. الرمز
يستبدل العميل الكود برمز وصول (tmcp_) مدته ساعة، ورمز تجديد مدته ٣٠ يومًا. الرمز مرتبط بالمتجر الذي وافق عليه التاجر.
- 05
٥. التجديد
عند انتهاء رمز الوصول يُستخدم رمز التجديد للحصول على زوج جديد، ويُستبدل رمز التجديد في كل مرة.
- 06
٦. الإلغاء
يمكن للعميل استدعاء نقطة الإلغاء، أو يلغي التاجر الاتصال من لوحة التحكم، فيتوقف الوصول.
جدول الصلاحيات
كل الصلاحيات التي يمكن للتاجر منحها لاتصال MCP. تظهر بنفس هذه الأسماء في شاشة الموافقة.
| الصلاحية | العربية | English |
|---|---|---|
| read_products | قراءة المنتجات | Read products |
| write_products | إضافة المنتجات وتعديلها وحذفها | Create, update and delete products |
| read_orders | قراءة الطلبات | Read orders |
| read_customers | قراءة بيانات العملاء | Read customers |
| write_orders | تأكيد الطلبات وشحنها وتسليمها وإلغاؤها | Confirm, ship, deliver and cancel orders |
| read_inventory | قراءة المخزون | Read inventory |
| write_inventory | تعديل كميات المخزون | Adjust inventory quantities |
| read_analytics | قراءة تقارير المبيعات | Read sales reports |
| read_discounts | قراءة أكواد الخصم | Read discount codes |
| write_discounts | إنشاء أكواد الخصم وتعديلها | Create and update discount codes |
| read_themes | قراءة تصميم المتجر | Read store design |
| write_themes | تعديل تصميم المتجر ونشره | Edit and publish store design |
| read_automations | قراءة الأتمتة وسير العمل | Read automations |
| write_automations | إنشاء الأتمتة وتعديلها | Create and edit automations |
| manage_webhooks | إدارة روابط الـ webhooks | Manage webhooks |
| use_ai_content | توليد أوصاف المنتجات ومحتوى التسويق بالذكاء الاصطناعي | Generate product and marketing content with AI |
| write_returns | إدارة طلبات الإرجاع واعتماد المبالغ المستردة | Manage returns and issue refunds |
| upload_media | رفع صور للمنتجات وشعار المتجر | Upload product images and the store logo |
| read_shipping | قراءة الشحن: الناقلون والشحنات والتسعير | Read shipping: carriers, shipments, pricing |
| write_shipping | تعديل إعدادات تجربة الشحن (بيانات البوليصة والتغليف والتنفيذ الذاتي) | Update shipping experience settings (label, packing slip, self-fulfilment) |
| read_payments | قراءة بوابات الدفع وحالتها (بدون المفاتيح) | Read payment gateways and their status (never the keys) |
| read_invoices | قراءة الفواتير وحالة زاتكا والملف الضريبي | Read invoices, ZATCA status and the tax profile |
| read_markets | قراءة الأسواق والعملات وقوائم المنتجات لكل سوق | Read markets, currencies and per-market catalogs |
| read_reviews | قراءة تقييمات المنتجات | Read product reviews |
| write_reviews | قبول تقييمات المنتجات أو رفضها أو تعليمها | Approve, reject or flag product reviews |
| read_campaigns | قراءة الحملات التسويقية وأدائها | Read marketing campaigns and their performance |
ممارسات الأمان
- لا تضع المفاتيح أو الرموز في الكود أو المستودعات أو الرسائل.
- اطلب أقل الصلاحيات اللازمة فقط.
- ألغِ أي مفتاح أو اتصال تشك في تسريبه من لوحة التاجر.
هذه الصفحة وثائق فقط ولا تعرض أي مفاتيح أو رموز حقيقية.