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

# التفعيل KYC/KYB/IDV للمؤسسة

> انقل مؤسستك من التسجيل إلى الاعتماد على ترسية حية: أرسل نموذج KYC، أتبع جلسة تحقق من الهوية مستضافة اختياريًا، راقب الحالة، تعامل مع الرفض، وأكمّل الأبواب الأخيرة قبل go-live.

# التفعيل KYC/KYB/IDV للمؤسسة

تذكّر الخطوة 5 من [دليل البدء السريع](/quickstart#step-5-go-live) بابين صلبين على الترسيا الحية: KYC المؤسسة المعتمد ومتبقٍ مزوّد بالأموال. KYC المؤسسة هو مراجعة مرة واحدة لكل workspace — يتحقق من *المؤسسة نفسها*، لا من أرقامها (حزم المستندات لكل رقم موضوع منفصل؛ قارن في النهاية).

يغطي هذا الدليل الحلقة الكاملة — الإرسال، جلسة تحقق من الهوية مستضافة اختياريًا، استطلاع الحالة، إعادة الإرسال عند الرفض — ثم الأبواب المتبقية قبل go-live.

***

## 1. لماذا يُغلق الترسيل الحي

تظل الإرسالات الحية مقيدة حتى يكون أحد من فريق عمليات Devotel قد نظر في ملف أعمال واقعي. حتى يصل الاعتماد:

* شراء الأرقام ما زال ممكنًا، لكن لن يغادر أي SMS أو WhatsApp أو صوت المنصة.
* تظهر لوحة التحكم الحالة كشعار؛ الصفحة نفسها التي يغطيها هذا الدليل قابلة للوصول من **الإعدادات → KYC**.

حالتين تنقلان المراجعة للأمام. `not_started` يعني أن النموذج لم يُرسل أبدًا. `pending_review` يعني أن طابور العاملين يحتفظ بالتسليم (webhook تأكيد البريد يكتب هذه الحالة مسبقًا عند التسجيل؛ النموذج أدناه يستبدله بتفاصيل غنية). بعد القرار تحصل على `approved` أو `rejected`.

## 2. أرسل النموذج

POST إلى `/api/v1/organization/kyc/submit` مع ملف الأعمال. يتحقق الـ API: اسم الشركة والبلد مطلوبان، الموقع اختياري، يجب أن يتصف وصف الغرض بعشر أحرف فأكثر، إدخالات owner-beneficial اختيارية (20 كحد أقصى).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
    -H "X-API-Key: $ORBIT_TEST_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "company_name": "Acme Logistics Ltd.",
      "company_website": "https://acme-logistics.example",
      "country": "US",
      "industry": "اللوجستيات",
      "use_case": "إشعارات حالة التسليم المرسلة إلى العملاء الذين وافقوا أثناء الدفع.",
      "estimated_monthly_volume": 45000,
      "registration_number": "DE-554433",
      "beneficial_owners": [
        { "name": "Maria Alvarez", "ownership_percentage": 100 }
      ]
    }'
  ```

  ```typescript Node.js theme={null}
  import { Devotel } from '@devotel-orbit/node';

  const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

  const result = await orbit.organization.kyc.submit({
    company_name: 'Acme Logistics Ltd.',
    company_website: 'https://acme-logistics.example',
    country: 'US',
    industry: 'اللوجستيات',
    use_case: 'إشعارات التسليم إلى عملاء راضين.',
    estimated_monthly_volume: 45000,
  });
  console.log(result.data.status); // "pending_review"
  ```
</CodeGroup>

طلب ناجح يضع المؤسسة `pending_review` ويعيد السجل المحفوظ مع نتيجة التحقق — المراجعة تدار من مشغل، لا شيء يُعتمَد أو يُرفض تلقائيًا.

**الإجابة (200):**

```json theme={null}
{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Logistics Ltd.",
      "country": "US",
      "submitted_at": "2026-09-04T09:12:33Z"
    },
    "kyb": {
      "status": "review",
      "matches": [],
      "legal_name": "Acme Logistics Ltd.",
      "country": "US",
      "screened_at": "2026-09-04T09:12:33Z"
    },
    "message": "Your KYC submission has been received and is awaiting review."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-09-04T09:12:33Z" }
}
```

`data.kyb` هو إشارة التحقق التجاري (`clear` إذا كان الكيان نظيفًا، `review` إذا تطابق بلد خاضع للعقوبات أو طرف محظور). يُرَاجَع مع النموذج — لا يُوقف الإرسال أبدًا وتحتاج `review` النتيجة نفس التوغل اليدوي. الحقل يُغفَل عندما لم يتمكن التحقق من الاشتغال (ثم تصبح المراجعة يدوية).

## 3. مناطق الاستهداف — ما يتطلبه وجهةُك واقعيًا

النموذج أعلاه يُرسَل مرة واحدة لكل مؤسسة، لكن أي الحقول يبرر المفوّض أكثر يعتمد على وجهة الترسيل. الـ `country` المُرسل يُثبت المنطقة — أجب بوجهة السوق، لا عنوان الفوترة؛ مُرسل يستهدف UK ويُبلغ `country: "US"` يفوز فقط برجوع للتصحيح. مهما يكن السوق، فإن فئتين من الحقول تصلان دائمًا إلى المفوّض: نص `use_case` الحر، وحقول KYB الهوية (`registration_number`، `beneficial_owners`). مؤسسة تستهدف عدة أسواق مغلقة تعيد نمط المستندات مرة لكل وجهة — اجمع الرفعات لكل وجهة في مكتبة المستندات بدلاً من تشذيب نموذج واحد.

الأسواق أدناه تحجز الإرسالات حتى يكتمل التسجيل المسبق. لكل منها: الحقول التي يجب تسليط الضوء عليها، وأدوار المستندات التي يطلبها المنظم. الرفعات تُسجَّل تحت **الامتثال → المستندات** وتُشار بالهوية عبر التسجيلات؛ الأدوار المرئية للمراجعة هي `business_doc`، `address_proof`، `id_proof`، `authorization`. تحمل [مصفوفة سوق Sender-ID](/guides/sender-id-country-matrix) مستوى `registration` الحي لكل بلد؛ يغطي [دليل المستندات](/compliance/documents-kyc) تدفق الرفع.

### ألمانيا — BNetzA هوية الكيان

BNetzA (Bundesnetzagentur) تتحقق من الهوية خلف كل سfm أبجدي وأي مراجعة KYC صوتية. سلّط الضوء على `registration_number` (التسجيل في سجل التجارة المحلية) واسم قانوني صحيح. المستندات المطلوبة: `business_doc` (مستقى من سجل التجارة).

### إسبانيا — CNMC sender-id

تختص CNMC كتابة الرسائل حتى يكون sender-id الأبجدي مسجلاً قبل الإرسال. سلّط الضوء على `registration_number` وـ `use_case` محمَّل إلى المستلم الإسباني. المستندات: `business_doc` (CIF/NIF للكيان).

### فرنسا — ARCEP تسجيل المرسِل

تسجل ARCEP والحاملون الهوية التي تحمل sender الأبجدي؛ العلامات غير المسجلة تلقي رفضًا لمصادرة SMS. سلّط الضوء على `registration_number` (تسجيل RCS) مع `use_case` مُغلق على الترسيل المُفصَّل. المستندات: `business_doc` (مستقى Kbis أو SIREN) بالإضافة إلى `authorization` إذا تقدم وكيل نيابة عن العلامة.

### تركيا — BTK اسم المرسِل

يسجّل BTK اسم المرسِل — لا مجرد السفر: قدّم الاسم الذي سيراه عملاؤك واذكره في `use_case`. المستندات: `business_doc` (وثائق غرفة التجارة).

### الأسواق العربية — مثال الإمارات TDRA

تتوقع بعض الأسواق العربية (مثل الإمارات، TDRA بالإضافة إلى حاملي e&/du) هوية علامة مدعومة بـ KYC مُلحَقة بـ sender — الأغشية الأكثر ترجحًا لإعادة submission ضعيفة. سلّط الضوء على `company_name` و`company_website` وـ `use_case` كاملة. المستندات: `business_doc` بالإضافة إلى إذن العلامة `authorization`.

في كل سوق الفكرة نفسها: قرر ما ستكتبه في `company_name` و`use_case` و`registration_number` **قبل** أن يعيد مرشإرسال ارسال هذه الرسلات بـ `422`. يوضح [Send Gates](/compliance/send-gates) كيف يحجز وجهة `required` الإرسالات غير المسجلة. لأسواق تحديدية باللغة الإنجليزية (UK، السعودية، الإمارات، البرازيل، الهند DLT، US 10DLC)، راجع [النسخة الإنجليزية من هذا الدليل](/guides/organization-kyc-onboarding).

## 4. اختياري: جلسة IDV مستضافة

يتطلب بعض الحاملات وثيقة هوية حكومية إضافة إلى فحص حيوي قبل التوقيع. POST `/api/v1/organization/kyc/idv/session` يفتح جلسة مستضافة مع المزود المنشأ؛ افتح الURL الوظَفية في متصفح أو سلمها للموقّع.

```bash cURL theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/idv/session \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://your-app.example/kyc/return" }'
```

**الإجابة (200):**

```json theme={null}
{
  "data": {
    "status": "pending",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:13:04Z"
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-09-04T09:13:04Z" }
}
```

حتى يُزوّد المشغل متزوّقًا يجيب الـ endpoint بـ `503`:

```json theme={null}
{ "error": { "code": "IDV_NOT_CONFIGURED", "message": "Identity verification is not available for this account", "status": 503 } }
```

تحقق من نتيجة المزوّد بـ `GET /api/v1/organization/kyc/idv/status`. يتصالح ذاتيًا: ما دامت الجلسة المخزنة `pending` فإن كل GET يستفسر المزوّد عن أحدث النتائج ويكتب الانتقال النهائي. قرار نهائي `verified` أو `declined` أو `expired` — مع `reason` كلما قدم المزوّد واحدًا — ينضم إلى الإشارة التي يزن المشغل مع التسليم. **لا** يعتمد ذاتيًا: `verified` لا يعتمد KYC، و`declined` لا يُرفضها.

```json theme={null}
{
  "data": {
    "status": "verified",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:44:12Z",
    "configured": true
  }
}
```

## 5. راقب قرار المؤسسة

استفسر `GET /api/v1/organization/kyc/status` حتى يتم اتخاذ قرار المؤسسة. الحالات المتاحة هي `not_started` و`pending` (مرحلي قبل التسليم) و`pending_review` و`approved` و`rejected`؛ الإجابة أيضًا تُردِد الحقول التجارية المُرسلة و`reviewed_at` عند اتخاذ القرار.

```bash cURL theme={null}
curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "X-API-Key: $ORBIT_TEST_KEY"
```

**الإجابة (200):**

```json theme={null}
{
  "data": {
    "status": "pending_review",
    "company_name": "Acme Logistics Ltd.",
    "country": "US",
    "industry": "اللوجستيات",
    "submitted_at": "2026-09-04T09:12:33Z",
    "reviewed_at": null,
    "source": null
  },
  "meta": { "request_id": "req_ghi789", "timestamp": "2026-09-04T09:15:00Z" }
}
```

بنى SDK قديمة ونهايات codes hand-rolled أحيانًا كانت تقرأ المسار العمل `GET /api/v1/organization/kyc`؛ يقدم نفس شكل الإجابة، فضلاً عن أن استهدف `/kyc/status` آمن ومتوافق.

الـ endpoint آمن للاستشارة من اللوحة أو from server — يتدiterr سblip قاعدة البيانات المؤقت إلى قراءة `not_started` حيادية بدلاً من إخراج 503، والاستفسار التالي يصحح نفسه.

## 6. إعادة الإرسال وحاجز «معتمد بالفعل»

POST النموذج مرة أخرى هو الخطوة الصحيحة مع `rejected`: يعيد الكتابة الحالة `pending_review`، يغطي كتلة النموذج ويعيد تشغيل screening بالإجابات المصححة. تسليم ثانٍ وما يزال `pending_review` مقبول أيضًا — يستبدل الملف القائم.

إعادة إرسال المؤسسة **approved** ترجع **409**:

```json theme={null}
{
  "error": {
    "code": "ALREADY_VERIFIED",
    "message": "KYC verification has already been approved",
    "status": 409
  }
}
```

نفس الحاجز ينطبق على جلسة IDV عندما تصبح الهوية `verified` — POST إلى endpoint الجلسة يreceive `409 ALREADY_VERIFIED`، ولا يؤدي الالتقاط إلا بعد أن يكون المؤسسة قد رُفِضت وتُدفع مجددًا.

## 7. ما يعنيه الرفض وما يجب فعله

الرفض قرار بشري — المشغل يتوقف في **لوحة عمليات Devotel**، يقرأ حقول النموذج بالإضافة إلى إشارتي screening وIDV، ثم يضغط Approve أو Reject. الوجه الموجه للعميل لا يكشف أبدًا نطرية آلية؛ رسالة القرار تسمى الفجوة والإصلاح. تعامل `rejected` كقابل للتنفيذ:

1. أعدقرأ الحقول المُرسلة للدقة (مظهَد قانوني متعانٍ أو وصف use-case ضعيف هو الإشارة الأكثر شيوعًا).
2. صحح أي تطابق `kyb` وأي نتيجة IDV `declined`.
3. أرسل من جديد بالبيانات المصححة — الـ endpoint يقبل ويعاد ترتيب الطابور.

إذا كان الرفض خطأ واضحًا — مثلاً خطأ إملائي في لوحة العامل بدلاً من في بياناتك — قدم من خلال [الدعم](/troubleshooting/auth-and-api-keys) مع معرف الحساب ومعرف `req_*` من استماع الحالة؛ صاحċ الطابور المراجعة يمكنه reabrir الملف واعتماده من جهة المشغل.

### ما لا يغطيه هذا الباب: مستندات كل رقم

KYC المؤسسة يطلق بجانب حزم المستندات التي يطلبها حامليك لكل رقم — هذه (تسجيل الأعمال، إثبات العنوان، الهوية) تغطي رقماً محدداً تملكه وتتبع دورة مراجعة مختلفة تحت **الامتثال → المستندات**. اعتماد المؤسسة لا يحسم حزمة رقمية، والعكس بالعكس. راجع [دليل مستندات KYC لكل رقم](/compliance/documents-kyc) لذلك السجل المنفصل.

## 8. بعد الاعتماد — الأبواب الأخيرة قبل go-live

الاعتماد يغير قرار المؤسسة، لذلك `GET /organization/kyc/status` يعود `approved`. أكمّل البابين المتبقيين من [قائمة فحص go-live](/guides/go-live-checklist):

* **صك المفتاح الحي.** تحت **الإعدادات → API Keys**، أنشئ سرًا ببادئة `dv_live_sk_` واستبدله بمفتاح sandbox `dv_test_sk_` — أشكال الطرف متماثئة، لا حاجة لإعادة كتابة رمز.
* **موّل المتبقي.** أضف أموالاً تحت **الإعدادات → Billing**؛ SMS وWhatsApp والصوت كلها تسحب من هذه المحفظة، وsaver الحية تفشل بخطأ فوترة ما دام المتبقي فارغًا.
* **SMS الأمريكي: أضف طبقة 10DLC.** إذا كانت الوجهة تتضمن رمزًا طويلاً أمريكيًا، أكمّل [تسجيل العلامة والحملة 10DLC](/guides/10dlc-registration). اعتماد KYC وحده لا يستبدل تسجيل الحامل، ويجب أن يكون كل الأبواب خضراء قبل أن يغادر send SMS الأمريكي طبقة sandbox.

ما إن تُتجاز الأبواب الصلبة والتسجيلات القناعية، يتصرف الإرسال الحي بالضبط مثل الإرسال sandbox — نفس الـ endpoint، نفس ال-envelope للwebhook، بدون دورة اعتماد إضافية.

***

## مراجع مرتبطة

* [قائمة فحص go-live](/guides/go-live-checklist) — الأبواب الصلبة قبل الترسيل الحي.
* [تسجيل Sender-ID](/compliance/sender-id-registration) — تسجيلات لكل بلد مدعومة بهويات `doc_`.
* [مستندات KYC لكل رقم](/compliance/documents-kyc) — مكتبة مستندات يمتلكها المستأجر.