المصادقة

يستخدم CodFlow مخططي مصادقة مستقلين. استخدم المخطط المطابق للواجهة التي تستدعيها.

الواجهة	الترويسة	الهوية	المستدعي المعتاد
API التاجر	`X-API-Key`	مستخدم في لوحة التحكم ونطاقاته	لوحة الإدارة، الأتمتة، تكامل الخادم
API التاجر	`Authorization: Bearer <JWT>`	جلسة لوحة تحكم مسجّلة	Worker لوحة التحكم
API واجهة المتجر	`X-Store-API-Key`	متجر	واجهة المتجر، القالب، إتمام الطلب

يوضح مرجع API المخطط الذي تقبله كل عملية.

مصادقة التاجر

مفتاح API

أرسل المفتاح في X-API-Key:

Code
GET /api/orders HTTP/1.1
Host: localhost:8787
X-API-Key: cod_your_api_key_here

تنتمي المفاتيح إلى المستخدمين. يحمّل الخادم المستخدم، ويتحقق من أن الحساب نشط، ويستنتج نطاقات المستدعي:

يحصل مستخدم admin على النطاق الشامل * ويجتاز كل فحص صلاحية.
يحصل مستخدم staff على النطاقات المخصصة له في لوحة التحكم فقط.

يُرفض المفتاح الغائب قبل تشغيل أي معالج. ويُرفض المفتاح الذي لا يطابق أي مستخدم باعتباره غير صالح.

رمز الجلسة

ترسل لوحة التحكم رمز JWT قصير العمر في Authorization: Bearer <JWT>. يتحقق الخادم من الرمز، ويحمّل المستخدم، ويطبّق فحوص الحالة والنطاقات نفسها المطبقة مع مفتاح API.

هذا المخطط مخصص للوحة التحكم. يجب أن تستخدم تكاملات الطرف الثالث مفتاح API بدلًا من رمز جلسة متصفح منسوخ.

تدوير مفتاح

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

مصادقة واجهة المتجر

تستخدم استدعاءات واجهة المتجر مفتاح المتجر في X-Store-API-Key:

Code
GET /store/products HTTP/1.1
Host: localhost:8787
X-Store-API-Key: your_store_api_key_here

يُجزّئ الخادم المفتاح المقدّم ويبحث عنه في store_api_keys. المفتاح الصالح يطابق متجرًا واحدًا فقط؛ وكل استعلام في واجهة المتجر محصور بذلك المتجر. يُنشأ المفتاح للمتجر ويمكن للمدير نسخه من التكاملات → مفتاح API للمتجر في لوحة التحكم.

مفتاح المتجر لا يصادق على استدعاءات /api/*. ومفتاح التاجر لا يصادق على استدعاءات /store/*.

النطاقات

تأخذ النطاقات الشكل resource:action، على سبيل المثال:

النطاق	يسمح بـ
`orders:read`	قراءة الطلبات
`orders:create`	إنشاء الطلبات
`orders:update`	تغيير حالة معالجة الطلب وتفاصيله
`orders:delete`	حذف الطلبات أو إلغائها
`products:read`	قراءة الكتالوج
`products:manage`	إدارة المتغيرات والمخزون
`delivery:dispatch`	إنشاء شحنات مع شركة توصيل
`integrations:read`	عرض الـ webhooks ونتيجة عمليات تسليمها
`integrations:manage`	إضافة الـ webhooks وتعديلها واختبارها وإعادة إرسالها وحذفها
`meta:read`، `meta:manage`	عرض تطبيق Meta أو ضبطه. لكل تطبيق زوجه الخاص، مسمّى بمفتاحه: `dzverify`، `turnstile`، `sendili`، `whatsapp-button`
`settings:team`	إدارة أعضاء الفريق والصلاحيات
`mcp:view`	عرض اتصالات MCP الخاصة بك وإبطالها

لوحة التحكم هي مصدر الحقيقة لنطاقات المستخدم. العملية التي تحتاج نطاقًا يفتقده المستدعي تُرجع 403 برسالة Insufficient permissions. ويتجاوز المستخدمون المسؤولون هذا الفحص.

تأتي إخفاقات النطاقات من middleware RBAC وتستخدم جسمًا أصغر من أخطاء التطبيق: { "error": "Insufficient permissions", "required": "orders:read" }. راجع الأخطاء لأشكال الاستجابة الكاملة.

إخفاقات المصادقة

الحالة	الجسم	السبب
`401`	`{"error":"Missing authorization","code":"MISSING_API_KEY","category":"AUTHENTICATION"}`	لا يوجد `X-API-Key` أو رمز Bearer
`401`	`{"error":"User not found","code":"AUTHENTICATION_FAILED","category":"AUTHENTICATION"}`	المفتاح أو الرمز لا يطابق أي مستخدم
`401`	`{"error":"Invalid token","code":"AUTHENTICATION_FAILED","category":"AUTHENTICATION"}`	فشل التحقق من رمز Bearer
`403`	`{"error":"User account is inactive","code":"USER_INACTIVE","category":"AUTHENTICATION"}`	المستخدم معطّل
`403`	`{"error":"Insufficient permissions","required":"orders:read"}`	المستخدم يفتقر إلى النطاق
`401`	`{"error":"Missing store API key"}`	لا يوجد `X-Store-API-Key`
`401`	`{"error":"Invalid store API key"}`	مفتاح المتجر لا يطابق أي متجر

CORS

تسمح API بالطلبات عبر الأصول باستخدام الترويسات X-API-Key وX-Store-API-Key وAuthorization وContent-Type وAccept. في التطوير المحلي يعيد الخادم أصل الطلب، لذا تعمل ساحة التجربة على http://localhost:3000. وفي الإنتاج لا يسمح إلا بالأصول المدرجة في ALLOWED_ORIGINS؛ أضف أصل التوثيق إليها إذا أردت أن تصل ساحة التجربة إلى خادم منشور.

البدء الأخطاء