# المصادقة

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

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

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

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

### مفتاح API

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

```http
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`:

```http
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`. ويتجاوز المستخدمون المسؤولون هذا الفحص.

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

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

| الحالة | الجسم | السبب |
| --- | --- | --- |
| `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`؛ أضف أصل التوثيق إليها إذا أردت أن تصل ساحة التجربة إلى خادم منشور.