> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# التسجيل البرمجي: واجهة KYC API لوكلاء الذكاء الاصطناعي

> سجّل واحصل على بيانات اعتماد Didit API في استدعاءين للـ API دون متصفح. منصة التحقق من الهوية المصممة لوكلاء الذكاء الاصطناعي.

## نظرة عامة

Didit هي **منصة التحقق من الهوية الأكثر ملاءمة للوكلاء الذكيين**. يمكن لوكلاء البرمجة بالذكاء الاصطناعي (Cursor وClaude Code وGitHub Copilot وDevin وOpenHands وCodex) التسجيل، وضبط سير العمل، وبدء التحقق من الهويات، كل ذلك برمجياً ودون فتح متصفح أبداً.

**لماذا يفضّل الوكلاء Didit:**

* **استدعاءان لواجهة API فقط** من الصفر حتى الحصول على بيانات الاعتماد (التسجيل والتحقق من البريد الإلكتروني).
* **لا حاجة إلى متصفح**: التشغيل بلا واجهة بالكامل، وهو مناسب تماماً لـ CI/CD ولسير عمل الوكلاء.
* **لا يوجد عامل تحقق ثانٍ لحساب API جديد**: تُعاد الرموز فور التحقق من البريد الإلكتروني.
* **إنشاء تلقائي** للمؤسسة والتطبيق مع `api_key` في استجابة التحقق.
* **واجهة إدارة كاملة**: اضبط سير العمل والاستبيانات والقوائم والفوترة، كل ذلك عبر API.
* **خادم MCP متاح**: يمكن للوكلاء اكتشاف أدوات Didit واستخدامها بشكل أصلي.

يُنشر العقد الكامل في [openapi-auth.json](https://docs.didit.me/openapi-auth.json)، وقد دُققت نقاط النهاية أدناه بالمقارنة معه.

## عنوان URL الأساسي

تقع جميع نقاط النهاية في هذا الدليل على **مضيف المصادقة**:

```
https://apx.didit.me/auth/v2
```

هذا المضيف مختلف عن واجهة التحقق البرمجية (`https://verification.didit.me/v3`). يُصدر مضيف المصادقة رموز الوصول JWT ويدير التطبيقات. أما مضيف التحقق فيُشغّل الجلسات وفحوص AML وسير العمل وغيرها، وتتم المصادقة على حركة واجهة التحقق البرمجية باستخدام `api_key` طويل الأمد الذي تحصل عليه من هذا التدفق.

## البدء السريع

> [!WARNING]
>
> **استخدم عنوان بريد إلكتروني حقيقي يمكن الوصول إليه.** يُرسل نقطة النهاية رمز التحقق بشكل متزامن، لذلك تُرفض نطاقات الاختبار المحجوزة (`@example.com` و`@example.org` و`@*.test` و`@*.example` و`@*.invalid`) من خدمة البريد، ويعيد الاستدعاء حالة `500`. استبدل العنصر النائب `you@yourdomain.com` أدناه بصندوق بريد يمكنك الوصول إليه.

### الخطوة 1: التسجيل

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

**الاستجابة** (`201 Created`):

```json theme={null}
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}
```

يُرسل رمز تحقق أبجدي رقمي من 6 خانات (مثل `A3K9F2`) إلى عنوان البريد الإلكتروني. **تنتهي صلاحية الرمز بعد 10 دقائق من إرساله**. إذا انتهت صلاحيته، فاستدعِ نقطة النهاية هذه مرة أخرى بالبريد الإلكتروني وكلمة المرور نفسيهما: بالنسبة إلى حساب لم يُتحقق منه بعد، ستعيد الاستجابة الرمز `200` مع الرسالة `"A new verification code has been sent to your email."` ورمزاً جديداً. كما تُعيد نقطة النهاية المخصصة `POST /programmatic/resend-otp/` (الجسم: `{"email", "password"}`) إرسال الرمز، مع فترة انتظار 60 ثانية بين كل إرسال والآخر. يشترك المساران في حد المعدل الخاص بالتسجيل المذكور أدناه.

### الخطوة 2: التحقق من الرمز والحصول على بيانات الاعتماد

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
```

**الاستجابة** (`200 OK`):

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

أصبح لديك الآن كل ما تحتاجه. احفظ `application.api_key` بأمان، وأرسله كترويسة `x-api-key` مع كل استدعاء لواجهة التحقق البرمجية.

> [!NOTE]
>
> رموز الوصول هي JWT موقّعة بخوارزمية **RS256**. القيمة الافتراضية لـ `expires_in` هي **86400 ثانية (24 ساعة)**. لا يلزم رمز الوصول إلا لنقاط نهاية الإدارة على `apx.didit.me/auth/v2`. أما حركة واجهة التحقق البرمجية على `verification.didit.me/v3` فتُصادَق بـ `api_key` طويل الأمد، لا بـ JWT.

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

```bash theme={null}
curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## عمليات تسجيل الدخول اللاحقة

من أي جهاز في المستقبل، استبدل بريدك الإلكتروني وكلمة المرور برمز JWT جديد:

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

تُعيد نقطة النهاية `access_token` و`refresh_token` مباشرة، دون الحاجة إلى متصفح. بعد ذلك، استدعِ `GET /organizations/me/` لاكتشاف `org_id` (وهو `uuid` الخاص بالمؤسسة)، ثم `GET /organizations/me/{org_id}/applications/` لعرض تطبيقات المؤسسة (يمثل `uuid` في كل عنصر `app_id`)، وأخيراً `GET /organizations/me/{org_id}/applications/{app_id}/` لاسترجاع `api_key`.

> [!NOTE]
>
> يمكن للحسابات التي أُنشئت من الكونسول بالبريد الإلكتروني وكلمة المرور أن تستخدم أيضاً `POST /programmatic/login/` بعد التحقق من البريد الإلكتروني. أما حسابات الكونسول التي تعتمد على OAuth فقط، فتحتاج إلى تعيين كلمة مرور قبل استخدام نقطة نهاية تسجيل الدخول البرمجية هذه.

### عندما يطلب تسجيل الدخول المزيد

تُعيد `POST /programmatic/login/` الرموز فقط عندما لا يكون للحساب عامل تحقق ثانٍ.
توجد ثلاث إجابات أخرى ممكنة، ويجب على الوكيل الذي يكتب سكربت تسجيل الدخول التعامل معها:

| الحساب | الاستجابة |
| - | - |
| لديه تطبيق مصادقة أو مفتاح مرور | `200` مع `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` دون أي رموز |
| تفرض مؤسسته تسجيل الدخول الموحد (SSO) | `403` مع `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| استُعيد الحساب ولم تُضبط له طريقة تسجيل دخول بعد | `403` مع `"code": "recovery_setup_required"`، ويُرسل رابط إعداد طريقة تسجيل الدخول إلى عنوان الحساب |

لا يحتاج مفتاح API إلى تسجيل دخول، لذلك استخدمه في كل ما هو آلي. الحساب الذي لديه عامل تحقق ثانٍ لا يمكنه إتمام تسجيل الدخول عبر نقطة النهاية هذه.

## متطلبات كلمة المرور

تُفرض على الخادم **قاعدة واحدة في كل مرة**، إذ يوقف الفشل الأول التحقق ويُعاد خطأ بصيغة مصفوفة مباشرة، مثل `["Password must contain at least one uppercase letter."]`. (تستخدم أخطاء التحقق الأخرى في نقطة النهاية هذه الغلاف `{"password": [...]}` المفهرس بالحقول. وشكل المصفوفة المباشرة في قواعد قوة كلمة المرور عدم اتساق معروف في الخادم، فعامله معاملة `{"password": [...]}` في كود العميل.)

| القاعدة | التفاصيل |
| - | - |
| الحد الأدنى للطول | 8 أحرف |
| حرف كبير | حرف واحد على الأقل من `A–Z` |
| حرف صغير | حرف واحد على الأقل من `a–z` |
| رقم | رقم واحد على الأقل من `0–9` |
| رمز خاص | رمز واحد على الأقل من: `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## حدود المعدل والقفل

ثلاثة ضوابط مستقلة تحمي مضيف المصادقة. أيٌّ منها قد يُطلق استجابة `429`، ورأس الاستجابة `Retry-After` يخبرك بالمدة التي يجب أن تنتظرها قبل إعادة المحاولة.

| الواجهة | الحد |
| - | - |
| التسجيل | **5** محاولات لكل **IP** في **الساعة** (مشتركة مع `POST /programmatic/resend-otp/`). |
| التحقق من البريد الإلكتروني | **10** محاولات رمز لكل **بريد إلكتروني** في **الساعة** و**50** لكل **عنوان IP للمصدر** في **الساعة**، بالإضافة إلى تأخير أُسّي بين المحاولات (30 ثانية، تتضاعف مع كل إخفاق، بحد أقصى ساعة واحدة). |
| تسجيل الدخول (IP) | **20** محاولة لكل **IP** في **الدقيقة**، و**100** لكل **IP** في **الساعة**. |
| تسجيل الدخول (البريد الإلكتروني) | قفل تدريجي للحساب: **5** إخفاقات متتالية تؤدي إلى قفل لمدة 15 دقيقة؛ **10** إخفاقات تؤدي إلى قفل لمدة ساعة؛ **20** إخفاقاً تؤدي إلى قفل لمدة 24 ساعة. |

يبدو نص استجابة `429` كما يلي:

```json theme={null}
{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }
```

حدود معدل واجهة برمجة التحقق (مثلاً 600 جلسة/دقيقة) مستقلة عن هذه الحدود، وموثقة في [تحديد المعدل](https://docs.didit.me/ar/integration/rate-limiting.md).

## إدارة التطبيقات

بعد المصادقة، يمكنك استرجاع التطبيقات وإنشاؤها وتحديثها داخل مؤسستك.

هذا الخيار مناسب تماماً **للموزّعين** الذين يريدون تطبيقاً واحداً لكل عميل. لكل تطبيق `client_id` و`api_key` وبيانات وصفية وإعدادات خاصة به. ويفيد أيضاً حين تملك مؤسستك منتجات أو علامات تجارية أو مناطق أو بيئات أو حالات استخدام مختلفة تريد فصلها.

```bash theme={null}
# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'
```

استرجاع التطبيقات وإنشاؤها وتحديثها يتطلب أن يكون المستخدم **مالكاً** أو **مسؤولاً** للمؤسسة المستهدفة، وإلا فستكون الاستجابة `403`.

## ماذا يمكن للوكلاء فعله بعد التسجيل

باستخدام `api_key`، يتمتع الوكلاء بوصول كامل إلى واجهة برمجة التحقق. المسارات المدققة على `https://verification.didit.me/v3` هي:

| الواجهة | ما تفعله |
| - | - |
| `POST /v3/session/` | إنشاء جلسة تحقق. |
| `GET /v3/sessions/` | عرض الجلسات. |
| `GET /v3/session/{id}/decision/` | الحصول على قرار V3 (مصفوفات بصيغة الجمع، راجع نماذج البيانات). |
| `GET /v3/workflows/` | عرض سير عمل التحقق. |
| `GET /v3/questionnaires/` | عرض الاستبيانات المخصصة. |
| `GET /v3/users/` | عرض المستخدمين النهائيين (مفهرسين بواسطة `vendor_data`). |
| `GET /v3/billing/balance/` | التحقق من رصيد الائتمان. |
| `POST /v3/billing/top-up/` | شحن الرصيد. |
| `GET /v3/webhook/destinations/` | إدارة وجهات webhook (عرض / إنشاء / تحديث / حذف). |

راجع [مرجع واجهة برمجة الإدارة](https://docs.didit.me/ar/sessions-api/management-api.md) للاطلاع على الواجهة الكاملة.

## تكامل خادم MCP

للحصول على أفضل تجربة للوكلاء، استخدم خادم Didit MCP المستضاف على `https://mcp.didit.me/mcp`. لا يحتاج إلى مفتاح API: عند الاتصال الأول، يفتح عميلك المتصفح، وتضغط على **تسجيل الدخول باستخدام Didit** (OAuth 2.1 مع PKCE)، ويعمل الخادم نيابةً عنك بصلاحيات دورك في وحدة التحكم. العملاء الذين يدعمون MCP البعيد بشكل أصلي (Cursor وVS Code) يأخذون هذا الإدخال، أما Claude على الويب وDesktop فيضيفانه كموصل مخصص:

```json theme={null}
{
  "mcpServers": {
    "didit": {
      "url": "https://mcp.didit.me/mcp"
    }
  }
}
```

Claude Code: `claude mcp add --transport http didit https://mcp.didit.me/mcp`. العملاء الذين يدعمون stdio فقط (Windsurf وZed) يمرون عبر الجسر `mcp-remote`، الذي يُنفّذ تدفق OAuth نيابةً عنك.

مفتاح API الذي تحصل عليه من تدفق التسجيل أعلاه مخصص لاستدعاء REST API من الخلفية الخاصة بك، ولا يستخدمه MCP أبداً. للتفاصيل، راجع [نظرة عامة على MCP](https://docs.didit.me/ar/integration/mcp/overview.md) و[التثبيت الخاص بكل عميل](https://docs.didit.me/ar/integration/mcp/installation.md).

## مرجع غلاف الأخطاء

تشترك جميع endpoint الخاصة بـ `apx.didit.me/auth/v2` في أشكال الاستجابة الثلاثة نفسها (راجع `openapi-auth.json`):

* **التحقق على مستوى الحقول**: `{"field": ["message", ...]}` مع HTTP `400`.
* **التحقق على مستوى النموذج** (خصوصاً قوة كلمة المرور وأخطاء رمز التحقق): مصفوفة مجردة `["Invalid or expired verification code."]` مع HTTP `400`.
* **قواعد المصادقة أو قواعد العمل**: `{"detail": "..."}` مع `400` أو `401` أو `403` أو `404` أو `429`. تحمل استجابات `429` الرأس `Retry-After` الذي يخبرك بمدة الانتظار قبل إعادة المحاولة (ويحتوي جسم الاستجابة على `detail` فقط).

يعيد مضيف التحقق الأخطاء بصيغة `{"detail": "..."}`، وتتضمن استجابات 429 الرأسين `X-RateLimit-*` و`Retry-After`. راجع [تحديد المعدل](https://docs.didit.me/ar/integration/rate-limiting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.