> ## 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.
# إنشاء جلسة API: بدء التحقق من KYC أو KYB
> ابدأ جلسة تحقق عبر POST /v3/session/ مع Didit: نقطة نهاية موحدة لـ KYC وKYB، دفع حسب الاستخدام، استدلال أقل من 2 ثانية، و$10 رصيد مجاني شهرياً.
موجّه إنشاء الجلسة
نسخ الموجّه إلى الحافظة
\
\`Create a verification session via Didit's REST API.
Endpoint:
POST https://verification.didit.me/v3/session/
Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.
Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.
Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.
curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'
Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.
See /reference/data-models for the full schema.
Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.
Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.
Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
الصق في
## دعم KYC وKYBيُنشئ endpoint واحد جلسات التحقق من المستخدمين والتحقق من الشركات. يحدد **نوع سير العمل** نوع الجلسة:- إذا مرّرت `workflow_id` لـ **سير عمل KYC**، تُنشأ جلسة التحقق من المستخدمين (KYC). تكون قيمة الاستجابة `session_kind: "user"`.
- إذا مرّرت `workflow_id` لسير عمل KYB، تُنشأ جلسة التحقق من الشركات (KYB). تكون قيمة الاستجابة `session_kind: "business"`.يمكنك إعداد سير العمل من لوحة التحكم عبر *Workflows → Create workflow*. يكون سير العمل إما KYC أو KYB وقت إنشائه، ولا يمكنك تغيير نوعه لاحقًا.## الأمثلة> [tab] التحقق من المستخدمين (KYC)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **الاستجابة (201 Created):**
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
> "session_kind": "user",
> "session_number": 1024,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42"
> }
> ```> [tab] التحقق من الشركات (KYB)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **الاستجابة (201 Created):**
>
> ```json theme={null}
> {
> "session_id": "bs-01HJX1...",
> "session_kind": "business",
> "session_number": 89,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001"
> }
> ```## مستندات التوقيع الإلكترونيعندما يحتوي سير العمل على خطوة [التوقيع الإلكتروني](https://docs.didit.me/ar/core-technology/electronic-signature/overview.md) تأخذ المستندات من الجلسة (أي عند ضبط `signature_documents_source` على `session` أو `both`)، أرسلها في `sign.documents`. كل مستند هو الملف بترميز base64، حتى لا يحتاج Didit أبدًا إلى جلبه من عنوان URL.```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
```| الحقل | القواعد |
| - | - |
| `title` | يظهر للموقّع. من 1 إلى 255 حرفًا. القيمة الافتراضية هي `file_name`. |
| `file_name` | مطلوب. ينتهي بالامتداد `.pdf` أو `.docx`. من 1 إلى 255 حرفًا. |
| `content_base64` | مطلوب. يمكن أن يبلغ حجم ملف PDF 20 ميغابايت كحد أقصى، وحتى 100 صفحة، دون كلمة مرور أو نصوص برمجية أو ملفات مرفقة. يمكن أن يبلغ حجم ملف Word 20 ميغابايت كحد أقصى، ويُحوَّل إلى PDF أثناء تنفيذ الطلب خلال 25 ثانية كحد أقصى؛ ويخضع ملف PDF الناتج للحدود نفسها. يُسمح بـ 5 ملفات Word كحد أقصى لكل جلسة. |
| `fields` | اختياري. حتى 200 [حقل](https://docs.didit.me/ar/core-technology/electronic-signature/overview.md#الحقول-على-المستند) لوضعها على المستند، بالبنية نفسها دون `id`. يحتاج كل حقل إلى `key` و`type`، وإما موضع (`page` و`x` و`y` و`width` و`height`) أو [`anchor`](#وضع-الحقول-بحسب-نص-anchor). القيمة الافتراضية لـ `role` هي موقّع الخطوة، وتُحدَّد القيمتان الافتراضيتان لـ `required` و`label` من النوع. يضبط Didit القيمة `position` وفقًا لمكان الحقل. تشير الصفحات والمواضع إلى ملف PDF، أو إلى ملف PDF المحوَّل في حالة ملف Word. |إذا لم تُرسل `fields`، يقرأ الموقّع المستند ويوافق عليه.### وضع الحقول بحسب نص anchorبدلًا من الموضع، يمكن أن يحمل الحقل `anchor`: مقطع نصي في المستند يحدد مكان وضع الحقل. تناسب المراسي المستندات التي تُنشأ لكل جلسة، مثل المستندات المولَّدة من قالب Word. أما مستندات سير العمل فضَع حقولها في لوحة التحكم.| خاصية `anchor` | القواعد |
| - | - |
| `text` | من 1 إلى 64 حرفًا، يُبحث عنها في نص المستند. في حالة ملف Word، يُبحث عنها في ملف PDF المحوَّل. |
| `occurrence` | `first` (الافتراضي) يضع حقلًا واحدًا عند أول تطابق. `all` يضع حقلًا عند كل تطابق، وتحصل المفاتيح بعد الأول على اللاحقة `_2` و`_3` وهكذا. |
| `offset_x`, `offset_y` | كسور من حجم الصفحة. تكون الزاوية العلوية اليسرى للحقل هي الزاوية العلوية اليسرى لنص المرساة مضافًا إليها هذه الإزاحات. |
| `width`, `height` | حجم الحقل، ككسور من حجم الصفحة. |إذا لم يكن النص موجودًا في المستند، يعيد الاستدعاء `400` مع `field_anchor_not_found` ومفتاح الحقل. لا يزيل Didit نص المرساة من ملف PDF، لذلك اكتبه بلون مطابق للون خلفية الصفحة.### قيم الحقوليضبط `sign.field_values` قيمة كل حقل يكون `prefill` فيه هو `api.`، سواء في مستندات سير العمل أو في مستندات الجلسة. وهو كائن تكون مفاتيحه أسماء `` تلك. القيم نصوص من 1 إلى 500 حرف لحقول `text` و`data`، وقيم منطقية لحقل `checkbox`.```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
```| الخطأ (`400`) | متى يحدث |
| - | - |
| `field_value_unknown` | مفتاح لا يستخدمه أي حقل. |
| `field_value_missing` | حقل مطلوب لا توجد له قيمة لـ `api.`. |
| `field_value_invalid` | قيمة لا تجتاز [التحقق](https://docs.didit.me/ar/core-technology/electronic-signature/overview.md#التحقق-من-الصحة) الخاص بحقلها. |### الأخطاء والاستدعاءات المتكررةتقبل الجلسة 20 مستندًا كحد أقصى بإجمالي 50 ميغابايت. يعيد الاستدعاء `400` مع خطأ `sign` في الحالات التالية:- لا يحتوي سير العمل على خطوة التوقيع الإلكتروني.
- أرسلت `sign.documents` بينما تأخذ الخطوة مستندات سير العمل فقط.
- تأخذ الخطوة مستندات الجلسة فقط ولم ترسل أيًا منها، أو لا تحتوي على مستندات سير العمل ولم ترسل أيًا منها.
- المستند أكبر من الحد المسموح، أو ليس بترميز base64 صالح، أو ليس من نوع ملف مدعوم.
- يُرفض ملف Word مع `signature_document_not_supported`، أو يتعذر تحويله فيعيد `signature_document_conversion_failed`، مع كل `reason` مذكور في [الملفات المدعومة](https://docs.didit.me/ar/core-technology/electronic-signature/overview.md#الملفات-المدعومة).
- حقل غير صالح، أو لم يُعثر على المرساة (`field_anchor_not_found`)، أو تُرفض [قيمة حقل](#قيم-الحقول).تكرار استدعاء الإنشاء للقيمتين `workflow_id` و`vendor_data` نفسيهما يعيد الجلسة قيد الانتظار. وإذا أرسل هذا الاستدعاء `sign`، فيجب أن تكون مستنداته وحقوله وقيم حقوله مطابقة تمامًا للأولى (بالترتيب نفسه والعناوين وأسماء الملفات والمحتوى والحقول والقيم). وأي اختلاف يعيد `400` مع `{"sign": "signature_document_changed"}`: استخدم `vendor_data` مختلفًا، أو انتظر حتى تنتهي الجلسة قيد الانتظار.## الاختبار باستخدام سيناريوهات البيئة التجريبيةفي تطبيق يعمل في البيئة التجريبية، مرّر `sandbox_scenario` لتحميل نتيجة محددة مسبقًا (قبول، أو رفض بعينه، أو سيناريو قيد المراجعة) دون المساس بالمزودين الحقيقيين أو برصيدك:```json theme={null}
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
```يُرفض `sandbox_scenario` بالخطأ `400` في تطبيقات الإنتاج. إذا لم تكن تعرف النتيجة وقت الإنشاء، فـفعّلها (أو أعد تفعيلها) لاحقًا عبر `POST /v3/session/{session_id}/sandbox/arm/`، طالما ما زالت الجلسة في حالة `Not Started`: يستخدم منتقي السيناريو في تدفق الصفحة المستضافة قبل بدء التحقق نقطة النهاية نفسها. راجع [البيئة التجريبية وبيانات الاختبار](https://docs.didit.me/ar/integration/sandbox-testing.md) للاطلاع على كتالوج السيناريوهات الكامل، وسجل القيم السحرية، وبنية الطلب والاستجابة لـ endpoint التفعيل.## يربط `vendor_data` الجلسة بكيان- في سير عمل KYC: يُربط بـ[كيان المستخدم](https://docs.didit.me/ar/entities/users/overview.md). إذا لم يكن المستخدم موجودًا، يُنشأ تلقائيًا.
- في سير عمل KYB: يُربط بـ[كيان الشركة](https://docs.didit.me/ar/entities/businesses/overview.md). يُنشأ تلقائيًا إذا كان جديدًا.لمزيد من التفاصيل، راجع [ربط بيانات المورّد](https://docs.didit.me/ar/entities/vendor-data-linking.md).## الموافقة البيومترية في إلينوي وتكساس وكولورادويمكن للتدفق المستضاف وحزمة SDK الأصلية الإصدار 4.10.0 أو أحدث أن يعرضا خطوة موافقة بيومترية صريحة قبل أول التقاط للوجه، وذلك حسب وضع الموافقة في تطبيقك ومكان وجود الشخص. يُدخل حقلان اختياريان في هذا القرار:- `user_state`: مكان إقامة الشخص، عندما تعرفه (`US-IL` أو `IL` أو `Illinois`). في الوضع التلقائي (Auto)، تجعل الولاية المشمولة التدفق يطلب الموافقة.
- `biometric_consent`: كائن يحتوي على `given_at` و`text_version`، للموافقة التي جمعتها بالفعل. لن يطلب التدفق الموافقة مرة أخرى.لا تستطيع حزم SDK الأصلية التي تقل عن الإصدار 4.10.0 عرض هذه الخطوة. تعمل جلساتها كما كانت من قبل، ويُبلغ القرار بأن الموافقة لم تُجمع. راجع [الموافقة البيومترية](https://docs.didit.me/ar/getting-started/biometric-consent.md).## مهم: الإفصاح والموافقة ما زالا يتمّان في منتجكتُنشئ `Create Session` رابط التحقق و token الجلسة. لكنها **لا** تثبت بحد ذاتها أنك عرضت على المستخدم الإفصاحات أو حصلت على الموافقة المطلوبة لحالة الاستخدام الخاصة بك.إذا بدأت جلسة Didit من تطبيقك أو موقعك أو غلاف SDK لديك أو تدفق العلامة البيضاء، فينبغي أن تتولى الجانب القانوني في تجربة المستخدم لديك قبل أن يبدأ المستخدم التقاط البيانات.## قائمة التحقق المسبق الموصى بها1. أخبر المستخدم بأن **شركتك** هي من تطلب التحقق، وأن **Didit** هي مزود التحقق ومعالج البيانات الذي يشغّل التدفق.
2. اربط بـ **إشعار الخصوصية الخاص بك** وأي شروط قانونية خاصة بالجهة المتحكِّمة وتنطبق على هذا المسار.
3. اربط بـ [إشعار خصوصية التحقق](https://didit.me/terms/verification-privacy-notice) و[شروط المستخدم النهائي للتحقق من الهوية](https://didit.me/terms/identity-verification) الخاصين بـ Didit.
4. إذا تضمّن سير عملك التقاط المستند أو التقاط صورة السيلفي أو كشف الحيوية أو القياسات البيومترية، فاجمع **موافقة صريحة وإيجابية** حيثما يتطلب ذلك القانون المعمول به أو موقفك القانوني.
5. إذا كنت تستخدم واجهة مخصصة أو نطاقًا مخصصًا أو مسارًا يعتمد على API فقط، فاعرض هذه الإفصاحات في منتجك قبل توجيه المستخدم إلى تدفق Didit.
6. احتفظ بسجلك الخاص لنص الإشعار والموافقة وطابعها الزمني والبيانات الوصفية المرتبطة بهما، إذا اشترط فريقك القانوني وجود سجل تدقيق.> [!WARNING]
>
> تختلف المتطلبات القانونية باختلاف الولاية القضائية. لا تُلغي العلامة البيضاء دور Didit في تدفق التحقق. راجِع تطبيقك مع مستشار قانوني قبل الإطلاق إذا كنت تعمل في ولايات قضائية تطبّق قواعد خاصة بالقياسات البيومترية.
## OpenAPI
````yaml ar/openapi-25.json POST /v3/session/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/:
post:
tags:
- Sessions
summary: أنشئ جلسة تحقق
description: >-
أنشئ جلسة التحقق من المستخدمين (KYC) أو التحقق من الشركات (KYB) واحصل
على `url` لصفحة التحقق المستضافة بالإضافة إلى `session_token` لإعادة
توجيه المستخدم النهائي إليها أو تضمينها له. يحدد `workflow_id` خطوات
التحقق التي ستُنفَّذ وما إذا كانت الجلسة KYC أم KYB.
استدعِ هذا الـ endpoint من خادمك الخلفي (وليس من المتصفح مطلقًا — فمفتاح
API سرّي) كلما تطلب الأمر التحقق من مستخدم أو شركة: عند التسجيل، أو قبل
إجراء حساس، أو عند الحاجة إلى إعادة التحقق. المتطلبات المسبقة: سير عمل
منشور (تم إنشاؤه في صفحة
[Workflows](https://docs.didit.me/ar/console/workflows) في Console)
ومفتاح API للتطبيق مع رصيد متاح. تتجاوز تطبيقات البيئة التجريبية التحقق
من الرصيد.
**Idempotency:** عند توفير `vendor_data` ووجود جلسة غير مكتملة بالفعل
(`Not Started` أو `In Progress` أو `Resubmitted` أو `Awaiting User`)
تحمل نفس `vendor_data` على **أحدث إصدار منشور حاليًا** لسير العمل (وكان
لتلك الجلسة بالفعل رابط تحقق مستضاف)، يتم إرجاع الجلسة الحالية (مع بقاء
الرمز `201`) بدلاً من إنشاء جلسة مكررة — مع تحديث `callback` و`metadata`
بالقيم المقدمة حديثًا. الجلسة غير المكتملة التي تم إنشاؤها على إصدار
أقدم من سير العمل (إصدار أُعيد نشره منذ ذلك الحين) **لا** يُعاد
استخدامها؛ بل يتم إنشاء جلسة جديدة مرتبطة بأحدث إصدار منشور بدلاً من
ذلك. لا يُعاد أبدًا استخدام الجلسات التي تكون في حالات `Approved` أو
`Declined` أو `In Review` أو `Expired` أو `Abandoned` أو `Kyc Expired`.
**الآثار الجانبية:** يتم إنشاء عنوان URL لصفحة التحقق المستضافة وتخزينه؛
وإذا كان `contact_details.send_notification_emails` بقيمة `true` مع
تقديم بريد إلكتروني، فسيتم إرسال بريد إلكتروني لدعوة التحقق. تنتهي
صلاحية الجلسة بعد وقت انتهاء صلاحية الجلسة المحدّد في سير العمل. بالنسبة
لسير عمل KYB، يتم تجاهل `contact_details.phone` و`expected_details`.
operationId: post_v3_session_create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workflow_id
properties:
workflow_id:
type: string
format: uuid
description: >-
معرّف ثابت لسير العمل الذي يحدد خطوات التحقق التي ستشغلها
الجلسة. يتم إنشاء مسارات العمل وإدارتها في صفحة [مسارات
العمل](/ar/console/workflows) في Console. يحدد `workflow_id`
أيضاً بشكل ضمني ما إذا كانت الجلسة مخصصة لـ KYC أو KYB.
example: 11111111-2222-3333-4444-555555555555
x-readme-id: '0.0'
vendor_data:
type: string
description: >-
معرّف فريد للمستخدم الذي يتم التحقق منه، مثل UUID أو بريد
إلكتروني أو معرّف مستخدم داخلي. يُستخدم هذا الحقل من أجل:
(1) **تجميع المستخدمين** — يتم ربط الجلسات التي تحتوي على
نفس vendor_data بنفس الملف التعريفي للمستخدم في تبويب Users.
(2) **اكتشاف التكرار عبر الجلسات** — عند التحقق من تكرار
الوجوه أو المستندات أو أرقام الهواتف أو رسائل البريد
الإلكتروني أو عناوين IP أو بصمات الأجهزة، تُعامل الجلسات
التي تحتوي على نفس vendor_data على أنها للمستخدم نفسه ويتم
استبعادها من التطابقات. بدون vendor_data، تُعامل كل جلسة
كمستخدم فريد وتظهر جميع حالات التكرار المحتملة. نوصي بشدة
بتقديم vendor_data دائمًا لتقليل التشويش في اكتشاف التكرار.
example: user-123
x-readme-id: '0.1'
multi_account_segment:
type: string
maxLength: 64
description: >-
نطاق اختياري لكشف التكرار داخل مؤسستك. تقارن عمليات فحص
تكرار الوجوه هذه الجلسة فقط بالجلسات الأخرى التي تحمل نفس
الشريحة، بحيث لا تؤدي قواعد الحسابات المنفصلة (الحسابات
الشخصية وحسابات الشركات، أو حساب واحد لكل عميل فرعي B2B) إلى
الإبلاغ عن شخص يمتلك حساباً واحداً في كل منها بشكل مشروع.
اتركه فارغاً لاستخدام النطاق الافتراضي الموحد، وهو ما
تستخدمه كل جلسة حالياً. تتجاهل مطابقة قائمة الحظر وقائمة
السماح هذا الحقل.
example: business-accounts
callback:
type: string
description: >-
رابط URL لإعادة توجيه المستخدم إليه بعد اكتمال التحقق. يُلحق
Didit تلقائياً `verificationSessionId` و`status` (Approved،
Declined، In Review) كمعاملات استعلام. مخططات URL المخصصة
(مثل `myapp://`) مدعومة لعمليات الاستدعاء على الأجهزة
المحمولة. إذا حُذف، يُستخدم `callback_url` الافتراضي لسير
العمل. عندما يحتوي التطبيق على نطاقات مسموح بها
(`allowed_domains` في `PATCH /v3/webhook/`)، يجب أن يكون
استدعاء `http` أو `https` على أحد تلك الأصول (نفس المخطط
والمضيف والمنفذ)، وإلا سيفشل الطلب برمز 400 على `callback`:
`callback must be on one of the application's allowed
domains: https://app.example.com`. تُقبل دائماً مخططات URL
المخصصة.
example: https://example.com/verification/callback
x-readme-id: '0.2'
callback_method:
type: string
description: >-
يحدد الجهاز الذي يجب أن يتعامل مع إعادة التوجيه إلى رابط
الاستدعاء المقدم. استخدم `initiator` لإعادة توجيه الجهاز
الذي بدأ سير العمل فقط، أو `completer` للجهاز الذي ينهيه، أو
`both` للسماح لأي من الجهازين بتشغيل الاستدعاء. إذا لاحظت في
أي وقت أن الاستدعاء لا يعمل بشكل موثوق، نوصي بتعيين هذه
القيمة على `both`.
enum:
- initiator
- completer
- both
default: initiator
example: both
x-readme-id: '0.3'
metadata:
description: >-
بيانات JSON عشوائية مخزنة مع الجلسة ويتم إرجاعها في
الاستجابة وأحداث webhook. يتم قبول أي قيمة JSON (كائن، نص،
رقم، مصفوفة)، ولكن يُوصى باستخدام كائن JSON لأزواج
المفاتيح/القيم. لا تظهر للمستخدم النهائي. استخدمها لتمرير
معرّفات الارتباط الخاصة بك، أو متغيرات اختبار A/B، أو سياق
العمل.
example:
user_type: premium
account_id: ABC123
x-readme-id: '0.4'
tags:
type: array
items:
type: string
maxLength: 50
maxItems: 10
description: >-
العلامات المضافة إلى الجلسة عند إنشائها، بالاسم. ما يصل إلى
10، كل منها بحد أقصى 50 حرفاً. الأسماء غير حساسة لحالة
الأحرف وتُخزّن بأحرف كبيرة. يتم إنشاء الاسم الذي ليس له وجود
بعد في التطبيق كعلامة جديدة. تظهر العلامات على الجلسة في
لوحة التحكم، حيث يمكنك التصفية بناءً عليها.
example:
- VIP
- ONBOARDING Q4
language:
type: string
description: >-
رمز اللغة (ISO 639-1) لواجهة عملية التحقق. يتحكم في اللغة
المعروضة للمستخدم النهائي أثناء التحقق. إذا لم يتم توفيره،
فسيتم اكتشاف لغة المتصفح واستخدامها تلقائياً. تحقق من جميع
اللغات المدعومة [هنا](/ar/integration/supported-languages).
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '0.5'
contact_details:
type: object
description: >-
معلومات الاتصال الخاصة بالمستخدم التي يمكن استخدامها
للإشعارات، وملء نماذج التحقق مسبقاً، والتحقق من رقم الهاتف.
يتضمن ذلك عنوان البريد الإلكتروني، واللغة المفضلة للتواصل،
ورقم الهاتف.
example:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
properties:
email:
type: string
format: email
description: >-
عنوان البريد الإلكتروني للمستخدم (مثل
"john.doe@example.com") الذي سيتم استخدامه أثناء خطوة
[التحقق من البريد
الإلكتروني](/ar/core-technology/email-verification/overview).
إذا لم يتم توفيره، يجب على المستخدم تقديمه أثناء مسار
التحقق.
example: john.doe@example.com
x-readme-id: '1.0'
send_notification_emails:
type: boolean
default: false
description: >-
إذا كانت القيمة true وتم توفير بريد إلكتروني، فإن Didit
ترسل رسالة البريد الإلكتروني الأولية "Verify your
identity" بشكل غير متزامن عند إنشاء جلسة التحقق من
المستخدمين (KYC) أو التحقق من الشركات (KYB). ترسل Didit
أيضاً إشعارات بحالة التحقق للجلسات التي تتطلب مراجعة
يدوية إلى عنوان البريد الإلكتروني المقدّم (على سبيل
المثال، من 'In Review' إلى 'Approved' أو 'Declined').
يساعد هذا المستخدمين على العودة إلى تطبيقك بمجرد اكتمال
عملية التحقق الخاصة بهم. إذا قمت بتفعيل العلامة البيضاء
للجلسة، فستكون رسالة البريد الإلكتروني المرسلة بعلامة
بيضاء.
example: true
x-readme-id: '1.1'
email_lang:
type: string
description: >-
رمز اللغة (ISO 639-1) لإشعارات البريد الإلكتروني. يتحكم
في لغة جميع اتصالات البريد الإلكتروني (مثل "en" و"es"
و"fr"). لا يوجد افتراضي مخزن — عند حذفه، يعود البريد
الإلكتروني لدعوة التحقق تلقائياً إلى اللغة الإنجليزية
(`en`) في وقت الإرسال. التعداد أدناه هو مجرد لمحة سريعة؛
المصدر الفعلي المباشر للقيم المقبولة هو وثيقة [اللغات
المدعومة](/ar/integration/supported-languages) — ارجع
إليها دائماً قبل الاعتماد على رمز معين.
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '1.2'
phone:
type: string
description: >-
رقم الهاتف بتنسيق E.164 (على سبيل المثال،
"+14155552671") الذي سيتم استخدامه أثناء خطوة [التحقق من
رقم
الهاتف](/ar/core-technology/phone-verification/overview).
إذا لم يتم توفيره، يجب على المستخدم تقديمه أثناء سير عمل
التحقق. يتم تجاهله في سير عمل التحقق من الشركات (KYB).
**هام:** يتم فرض رقم الهاتف هذا فقط إذا كان رقم هاتف
E.164 صالحاً. إذا كان الرقم المقدم غير صالح أو تعذر
تحليله، فسيتم تجاهله وسيتمكن المستخدم من إدخال أي رقم
هاتف صالح أثناء خطوة التحقق من رقم الهاتف.
example: '+14155552671'
x-readme-id: '1.3'
x-readme-id: '0.4'
expected_details:
type: object
description: >-
تفاصيل المستخدم المتوقعة المُستخدمة للتحقق المتبادل مقابل
البيانات المستخرجة من مستند التحقق من الهوية الخاص
بالمستخدم، وإثبات العنوان، وخطوات التحقق الأخرى. تظهر حالات
عدم التطابق كتحذيرات في القرار؛ كما تؤدي بعض الحقول (مثل
`id_country` و`expected_document_types`) أيضاً إلى تعديل سير
العمل الموجه للمستخدم. بالنسبة لسير عمل التحقق من الشركات
(KYB)، تُستخدم حقول الشركة فقط (`company_name`
و`registry_country` و`registration_number`) — حيث تملأ
مسبقاً البحث في سجل الشركات للمستخدم — ويتم تجاهل جميع
الحقول على مستوى الشخص.
example:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
properties:
first_name:
type: string
description: >-
الاسم الأول للمستخدم. على سبيل المثال، `John`. تستخدم
المطابقة مقارنة تقريبية، ويمكنك ضبط مستوى الدقة من خلال
تهيئة حد درجة تطابق الأسماء في لوحة التحكم لكل من سير
عمل مستند الهوية وسير عمل إثبات العنوان.
example: John
x-readme-id: '1.0'
last_name:
type: string
description: >-
اسم عائلة المستخدم. على سبيل المثال، `Doe`. تستخدم
المطابقة مقارنة تقريبية، ويمكنك ضبط مستوى الدقة من خلال
تهيئة حد درجة تطابق الأسماء في لوحة التحكم لكل من سير
عمل مستند الهوية وإثبات العنوان.
example: Doe
x-readme-id: '1.1'
date_of_birth:
type: string
format: date
description: >-
تاريخ ميلاد المستخدم بالتنسيق: YYYY-MM-DD. على سبيل
المثال، `1990-05-15`.
example: '1990-05-15'
x-readme-id: '1.2'
gender:
type: string
nullable: true
enum:
- M
- F
default: null
description: جنس المستخدم. يجب أن يكون 'M' أو 'F' أو null.
example: M
x-readme-id: '1.3'
nationality:
type: string
description: >-
رمز الدولة وفق المعيار ISO 3166-1 alpha-3 الذي يمثل بلد
المنشأ لمقدم الطلب. على سبيل المثال، `USA`. راجع
[القائمة الكاملة لرموز الدول
المدعومة](https://docs.didit.me/ar/core-technology/id-verification/supported-documents-id-verification#المستندات-المدعومة-حسب-الدولة).
example: USA
x-readme-id: '1.4'
country:
type: string
description: >-
رمز الدولة وفق المعيار ISO 3166-1 alpha-3 المُستخدم
كخيار احتياطي لعمليات التحقق من عدم تطابق الدولة لكل من
التحقق من الهوية وإثبات العنوان. مطلوب عند تقديم
`address` وعدم تعيين أي من `id_country` أو
`poa_country`.
example: USA
x-readme-id: 1.4.1
id_country:
type: string
description: >-
رمز الدولة وفق المعيار ISO 3166-1 alpha-3 الذي يمثل
الدولة المتوقعة لمستند هوية مقدم الطلب، والتي قد تختلف
عن الجنسية. على سبيل المثال، `GBR`. يحظى بالأولوية على
`country` في عمليات التحقق من عدم تطابق دولة التحقق من
الهوية. راجع [القائمة الكاملة لرموز الدول
المدعومة](https://docs.didit.me/ar/core-technology/id-verification/supported-documents-id-verification#المستندات-المدعومة-حسب-الدولة).
example: GBR
x-readme-id: '1.5'
poa_country:
type: string
description: >-
رمز الدولة وفق المعيار ISO 3166-1 alpha-3 الذي يمثل
الدولة المتوقعة لمستند إثبات العنوان. على سبيل المثال،
`USA`. يحظى بالأولوية على `country` في عمليات التحقق من
عدم تطابق دولة إثبات العنوان (POA). راجع [القائمة
الكاملة لرموز الدول
المدعومة](https://docs.didit.me/ar/core-technology/id-verification/supported-documents-id-verification#المستندات-المدعومة-حسب-الدولة).
example: USA
x-readme-id: 1.5.1
address:
type: string
description: >-
العنوان بتنسيق مقروء للبشر، متضمناً أكبر قدر ممكن من
المعلومات. على سبيل المثال، `123 Main St, San Francisco,
CA 94105, USA`. عند تقديمه، يجب عليك أيضاً تمرير
`country` أو `poa_country`، وإلا فسيفشل الطلب بالرمز
`400`.
example: 123 Main St, San Francisco, CA 94105, USA
x-readme-id: '1.6'
identification_number:
type: string
description: >-
رقم مستند المستخدم، أو الرقم الشخصي، أو الرقم الضريبي.
على سبيل المثال، `123456789`.
example: '123456789'
x-readme-id: '1.7'
ip_address:
type: string
description: >-
عنوان IP المتوقع للجلسة، بتنسيق IPv4 أو IPv6. إذا اختلف
عنوان IP الفعلي عن هذه القيمة، فسيتم تسجيل تحذير. على
سبيل المثال، `192.168.1.100` أو `2001:db8::1`.
example: 192.168.1.100
x-readme-id: '1.8'
expected_document_types:
type: array
description: >-
يقيّد أنواع المستندات التي يمكن للمستخدم تقديمها أثناء
خطوة التحقق من الهوية (OCR). عند التعيين، تعرض شاشة
اختيار المستندات الأنواع المطلوبة فقط ويتم تصفية
`documents_allowed` المُرجعة وفقاً لذلك. القيم غير حساسة
لحالة الأحرف وتتم إزالة التكرارات منها؛ وتُرفض القيم غير
المعروفة بالرمز `400`. الرموز المسموح بها: `P` (جواز
السفر)، `ID` (بطاقة الهوية الوطنية)، `DL` (رخصة
القيادة)، `RP` (تصريح الإقامة)، `HIC` (بطاقة التأمين
الصحي)، `TC` (البطاقة الضريبية)، `SSC` (بطاقة الضمان
الاجتماعي).
items:
type: string
enum:
- P
- ID
- DL
- RP
- HIC
- TC
- SSC
example:
- P
- ID
x-readme-id: '1.9'
company_name:
type: string
maxLength: 255
description: >-
الاسم القانوني المتوقع للشركة قيد التحقق. على سبيل
المثال، `Tesco PLC`. يملأ مسبقاً حقل اسم الشركة في البحث
في السجل ضمن سير عمل التحقق من الشركات (KYB)؛ وعند تقديم
`registration_number` أيضاً، يجمع البحث في السجل بين كلا
المعرّفين. يتم تجاهله في سير عمل KYC.
example: Tesco PLC
x-readme-id: '1.10'
registry_country:
type: string
maxLength: 10
description: >-
رمز ISO 3166-1 alpha-2 للدولة التي تم تسجيل الشركة في
سجل الشركات الخاص بها. على سبيل المثال، `GB`. عندما تعمل
سجلات الشركات على مستوى الولاية أو المقاطعة، ألحق رمز
التقسيم الفرعي ISO 3166-2 بصيغة `XX-YY`: يستهدف `US-CA`
سجل كاليفورنيا. نفس تنسيق `country_code` في [KYB
Registry Search
API](https://docs.didit.me/ar/standalone-apis/kyb-registry-search).
يحدد مسبقاً دولة السجل في مهام سير عمل التحقق من الشركات
(KYB)؛ ويتم تجاهله في مهام سير عمل KYC.
example: US-CA
x-readme-id: '1.11'
registration_number:
type: string
maxLength: 100
description: >-
رقم التسجيل المتوقع للشركة في سجل الشركات. على سبيل
المثال، `00445790`. يملأ مسبقاً حقل رقم التسجيل في البحث
في السجل ضمن سير عمل التحقق من الشركات (KYB)؛ وعند تقديم
`company_name` أيضاً، يجمع البحث في السجل بين كلا
المعرّفين. يتم تجاهله في سير عمل KYC.
example: '00445790'
x-readme-id: '1.12'
x-readme-id: '0.5'
portrait_image:
type: string
format: byte
description: >-
صورة شخصية لوجه المستخدم النهائي بترميز Base64 (بحد أقصى 2
ميغابايت؛ بصيغة JPEG أو PNG أو WebP أو TIFF). تُستخدم كصورة
مرجعية لمطابقتها مع لقطة كشف الحيوية عندما يكون سير العمل
عبارة عن سير عمل `Biometric Authentication` مع تفعيل مطابقة
الوجه، أو أي سير عمل مخطط يتم فيه تشغيل مطابقة الوجه قبل
التحقق من الهوية (OCR). اختيارية عندما يكون لدى مستخدم
`vendor_data` صورة وجه مخزنة بالفعل: تعيد Didit استخدامها
تلقائياً، وفقاً لترتيب الأولوية التالي: وجه من جلسة كشف
حيوية مقبولة، صورة شريحة جواز السفر الإلكتروني، الصورة
الشخصية في مستند الهوية، وجه الملف الشخصي المُسجّل يدوياً
(يُعاد فقط استخدام الوجوه المأخوذة من جلسات مقبولة أو الوجوه
التي سجّلتها بنفسك). عند تقديمها، تكون الأولوية دائماً لـ
`portrait_image` على الوجه المخزن. في حال حذفها وعدم وجود
وجه مخزن (أو عدم إرسال `vendor_data`)، يفشل إنشاء الجلسة
بالرمز `400`. يتم تجاهلها لأنواع سير العمل الأخرى.
example: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
x-readme-id: '0.6'
sandbox_scenario:
type: string
description: >-
معرّف سيناريو مخصص للبيئة التجريبية فقط. يُقبل فقط عندما
ينتمي مفتاح API إلى تطبيق في وضع البيئة التجريبية؛ ويُرفض في
تطبيقات بيئة الإنتاج. عند تعيينه، يُوسّع تدفق الإنشاء القيم
السحرية المرفقة بالسيناريو لتُدرج في حقول إدخال الجلسة
(contact_details، expected_details) حتى يُعيد المزودون
المحاكون إنتاج نتيجة السيناريو من خلال مسار سير العمل
الفعلي. راجع كتالوج السيناريوهات عبر GET
/v1/sandbox/scenarios/ أو [Sandbox & Test
Data](/ar/integration/sandbox-testing). يمكنك أيضاً تجهيز
(أو إعادة تجهيز) سيناريو بعد الإنشاء عبر POST
/v3/session/{sessionId}/sandbox/arm/، طالما أن الجلسة لا
تزال بحالة `Not Started`. لعمليات البحث غير المعتمدة على
المستندات، استخدم `lookup_partial_match` أو
`lookup_no_match` أو `lookup_provider_error` لاختبار ميزانية
المحاولات المهيأة والرجوع التلقائي. لمحفظات الهوية، استخدم
`wallet_cancelled` أو `wallet_timeout` أو
`wallet_provider_error`؛ بينما يُحاكي `approve` محفظة تم
التحقق منها. يمكن اختبار جميع المحافظ المدرجة في الكتالوج
داخل البيئة التجريبية، بما في ذلك المخططات غير المتاحة في
تطبيقات بيئة الإنتاج. لا تُحتسب أي رسوم على المحاولات
المحاكاة.
example: decline_document_expired
sign:
type: object
description: >-
مدخلات التوقيع الإلكتروني لهذه الجلسة. `documents` هي
المستندات المطلوب توقيعها، لسير عمل تتلقى فيه خطوة التوقيع
الإلكتروني المستندات من الجلسة (`signature_documents_source`
إما `session` أو `both`): بحد أقصى 20 مستنداً و50 ميغابايت
إجمالاً. يملأ `field_values` الحقول التي يكون `prefill`
الخاص بها هو `api.`، في كل من مستندات سير العمل والجلسة
على حد سواء. تؤدي إعادة إنشاء جلسة لنفس `workflow_id`
و`vendor_data` إلى إرجاع الجلسة المعلقة؛ وإذا أرسل هذا
الاستدعاء `sign`، فيجب أن تكون مستنداته وحقوله وقيمه مطابقة
تماماً للمستندات والحقول والقيم الأولى، وأي اختلاف يُرجع
`400` مع `{"sign": "signature_document_changed"}`. راجع
[مستندات التوقيع
الإلكتروني](/ar/sessions-api/create-session#مستندات-التوقيع-الإلكتروني).
properties:
documents:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/SessionSignDocument'
field_values:
type: object
description: >-
القيم المفهرسة بواسطة `` لكل مصدر تعبئة مسبقة
`api.`: سلاسل نصية من 1 إلى 500 حرف لحقول `text`
و`data`، وقيم منطقية لحقل `checkbox`. الرمز `400` مع
`field_value_unknown` لمفتاح لا يستخدمه أي حقل،
و`field_value_missing` لحقل مطلوب بدون قيمته،
و`field_value_invalid` لقيمة تفشل في التحقق من صحة
حقلها.
additionalProperties:
oneOf:
- type: string
minLength: 1
maxLength: 500
- type: boolean
example:
credit_limit: 3,000 EUR
user_state:
type: string
maxLength: 16
description: >-
مكان إقامة الشخص، عندما يكون معروفاً لديك: رمز قسم فرعي وفق
معيار ISO 3166-2 (مثل `US-IL`، `ES-M`) أو رمز ولاية أمريكية
أو اسمها (مثل `IL`، `Illinois`). الولاية التي يشترط قانونها
الحصول على موافقة بيومترية صريحة (إلينوي، تكساس، كولورادو)
تجعل سير عمل التحقق يطلبها قبل التقاط الوجه، مع المُشغِّل
`declared_state`. تُرجع القيمة غير المعروفة الرمز `400`.
راجع [الموافقة
البيومترية](/ar/getting-started/biometric-consent).
example: US-IL
biometric_consent:
type: object
description: >-
الموافقة البيومترية الصريحة التي جمعتها بالفعل من الشخص. وهي
تستوفي المتطلب، لذا لا يطلبها سير عمل التحقق مرة أخرى،
ويسجلها القرار كـ `status: "given"` مع المُشغِّل
`customer_collected`. لا يتم مطلقاً استبدال الإجابة التي
قدمها الشخص بالفعل في سير العمل. راجع [الموافقة
البيومترية](/ar/getting-started/biometric-consent).
required:
- given_at
- text_version
properties:
given_at:
type: string
format: date-time
description: >-
متى قدم الشخص موافقة بيومترية صريحة (ISO 8601). لا يمكن
أن تكون في المستقبل.
text_version:
type: string
maxLength: 64
description: >-
معرّف إصدار نص الموافقة الذي قبله الشخص، في سجلاتك
الخاصة.
example:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
id_country: USA
expected_document_types:
- P
- ID
examples:
Create KYC session:
summary: payload الكامل للمسار الناجح لجلسة التحقق من المستخدمين (KYC)
description: >-
استدعاء إنشاء واقعي يستخدم كل حقل يُضبط عادةً: اختيار سير
العمل، وربط المورد، وتوجيه معاودة الاتصال، والبيانات الوصفية،
والإعدادات المحلية، والتعبئة المسبقة لبيانات الاتصال، وتفاصيل
المستخدم المتوقعة. انسخ هذا والصقه مباشرة في عينة cURL أعلاه.
value:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
Create KYB session:
summary: payload لمسار النجاح لجلسة التحقق من الشركات (KYB)
description: >-
الشكل نفسه لاستدعاء KYC — معرّف `workflow_id` هو ما يجعل
الجلسة مخصصة لـ KYB. يشير `vendor_data` عادةً إلى الشركة في
نظامك ويستهدف `contact_details.email` الممثل القانوني الذي
سيكمل التدفق. يقبل `expected_details` حقول الشركة
(`company_name` و`registry_country` و`registration_number`)،
والتي تملأ مسبقاً البحث في سجل الشركات؛ ويتم تجاهل الحقول على
مستوى الأفراد و`contact_details.phone` في سير عمل KYB.
value:
workflow_id: 33333333-4444-5555-6666-777777777777
vendor_data: company-acme-001
callback: https://example.com/kyb/callback
callback_method: both
metadata:
tier: enterprise
company_id: ACME-001
expected_details:
company_name: Tesco PLC
registry_country: GB
registration_number: '00445790'
language: en
contact_details:
email: legal-rep@acme.example.com
send_notification_emails: true
email_lang: en
responses:
'201':
description: >-
تم إنشاء الجلسة (أو إرجاعها، إذا كانت هناك جلسة غير مكتملة بنفس قيمة
`vendor_data` موجودة بالفعل في أحدث إصدار منشور من سير العمل).
الاستجابة هي الجلسة المُسلسَلة، بما في ذلك عنوان `url` لصفحة التحقق
المستضافة لإعادة توجيه المستخدم إليها.
content:
application/json:
schema:
type: object
required:
- session_id
- session_number
- session_token
- url
- vendor_data
- metadata
- status
- workflow_id
- workflow_version
- callback
properties:
session_id:
type: string
format: uuid
description: >-
المعرّف الفريد لجلسة التحقق. استخدم هذا المعرّف عند
استدعاء `GET /v3/session/{sessionId}/decision/`.
example: 11111111-2222-3333-4444-555555555555
session_number:
type: integer
description: >-
رقم تسلسلي ومقروء بوضوح يُعيّن للجلسة داخل تطبيقك. مفيد
للدعم ولوحات التحكم.
example: 43762
session_token:
type: string
description: >-
رمز token آمن لعناوين URL مكوّن من 12 حرفاً يمنح المستخدم
النهائي الإذن بالوصول إلى تدفق التحقق المستضاف على `url`.
صالح حتى انتهاء صلاحية الجلسة. تعامل معه كسرٍ — يمكن لأي
شخص يحمله فتح تدفق التحقق لهذه الجلسة.
example: 3FaJ9wLqX2Mz
url:
type: string
format: uri
description: >-
رابط التحقق المستضاف لإعادة توجيه المستخدم النهائي إليه.
يتضمن الرابط `session_token`، وإذا تم تكوينه، يستخدم نطاق
العلامة البيضاء الخاص بك. عندما يتضمن الطلب `language`،
يحتوي الرابط على جزء مسار اللغة —
`https://verify.didit.me/{language}/session/{session_token}`
(مثل `/es/session/...`)؛ وبدون `language`، يتم حذف هذا
الجزء.
example: https://verify.didit.me/session/3FaJ9wLqX2Mz
vendor_data:
type: string
nullable: true
description: >-
المعرّف الذي مرّرته في الطلب لربط الجلسة بمستخدم أو شركة
في نظامك الخاص. يُعاد نصياً كما هو. ويكون Null عند عدم
تقديمه.
example: user-123
metadata:
description: >-
payload بصيغة JSON عشوائية قمت بتخزينها مع الجلسة وقت
الإنشاء. يتم إرجاعها كما هي تماماً — أياً كانت قيمة JSON
التي أرسلتها (كائن، نص، رقم، مصفوفة) يتم إرجاعها بحالتها،
مع أنه يُوصى باستخدام كائن JSON. لا تظهر للمستخدم النهائي.
تظهر دائماً في الاستجابات؛ وتكون `null` عند عدم تقديمها
وقت الإنشاء.
example:
user_type: premium
account_id: ABC123
tags:
type: array
items:
type: string
description: الوسوم الموجودة في الجلسة، حسب الاسم.
example:
- VIP
- ONBOARDING Q4
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
الحالة الحالية للجلسة. ترجع الجلسات المنشأة حديثاً الحالة
`Not Started`. إذا كانت هناك جلسة غير مكتملة موجودة بالفعل
لنفس `vendor_data` في أحدث إصدار منشور من سير العمل، فإن
الحالة المرجعة تعكس تلك الجلسة الحالية.
example: Not Started
callback:
type: string
format: uri
nullable: true
description: >-
رابط إعادة التوجيه النهائي الذي يُرسل إليه المستخدم بعد
إكمال سير العمل. يلحق Didit المعاملين
`?verificationSessionId={session_id}&status={status}` بهذا
الرابط. يتم الرجوع إلى رابط الاستدعاء المهيأ لسير العمل
عند عدم تقديمه في الطلب؛ ويكون `null` إذا لم يتم تعيين أي
منهما. عندما يحتوي التطبيق على نطاقات مسموح بها وكان هذا
الرابط رابط ويب خارجها (على سبيل المثال، القيمة الافتراضية
لسير العمل التي تم تعيينها قبل تغيير القائمة)، فإن سير
العمل المستضاف لا يعيد توجيه المستخدم إليه.
example: https://example.com/verification/callback
workflow_id:
type: string
format: uuid
description: >-
معرّف ثابت لسير العمل الذي تعمل عليه هذه الجلسة. يكون
دائماً معرّف المجموعة الثابت لسير العمل — حتى إذا أشرت إلى
UUID لإصدار سير عمل محدد في الطلب (بحث متوافق مع الإصدارات
السابقة)، فإن الاستجابة تحمل `workflow_id` الثابت. استخدمه
لربط الجلسة بسير العمل الذي قمت بتهيئته في Console.
example: 11111111-2222-3333-4444-555555555555
workflow_version:
type: integer
description: >-
رقم إصدار سير العمل المنشور الذي تم تثبيت الجلسة عليه عند
الإنشاء. تحل Didit قيمة `workflow_id` إلى أحدث إصدار منشور
من سير العمل عند إنشاء الجلسة، وتستمر الجلسة في تشغيل هذا
الإصدار حتى إذا أُعيد نشر سير العمل لاحقاً.
example: 3
examples:
KYC session:
summary: تم إنشاء جلسة KYC
value:
session_id: 11111111-2222-3333-4444-555555555555
session_number: 43762
session_token: 3FaJ9wLqX2Mz
url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz
vendor_data: user-123
metadata:
user_type: premium
account_id: ABC123
status: Not Started
workflow_id: 11111111-2222-3333-4444-555555555555
workflow_version: 3
callback: https://example.com/verification/callback
KYB session:
summary: تم إنشاء جلسة KYB
value:
session_id: 22222222-3333-4444-5555-666666666666
session_number: 43763
session_token: Yk7pQ2vN8aBc
url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc
vendor_data: company-acme-001
metadata:
tier: enterprise
status: Not Started
workflow_id: 33333333-4444-5555-6666-777777777777
workflow_version: 1
callback: https://example.com/kyb/callback
'400':
description: >-
طلب غير صالح — فشل التحقق من صحة الـ payload (معرّف `workflow_id`
مفقود أو غير معروف، أو `language` غير صالحة، أو `vendor_data` مدرجة
في قائمة الحظر، أو `portrait_image` غير صحيحة، أو `address` بدون
`country`/`poa_country`، أو `sandbox_scenario` غير صالح، أو مستندات
أو حقول أو قيم `sign` ترفضها خطوة التوقيع الإلكتروني في سير العمل،
مثل `signature_document_not_supported`، أو
`signature_document_conversion_failed`، أو `field_anchor_not_found`،
أو `field_value_missing`، وما إلى ذلك) أو أن مؤسستك لا تملك رصيدًا
كافيًا لبدء الجلسة.
جسم الاستجابة هو كائن مفاتيحه اسم الحقل المخالف (أو `detail` للأخطاء
غير المرتبطة بحقل معين). تكون القيم **مصفوفة من السلاسل النصية**
لحالات فشل التحقق من صحة المدخلات (مثل حقل مطلوب مفقود، أو لغة غير
صالحة، أو صورة شخصية كبيرة الحجم) و**سلسلة نصية بسيطة** لحالات الفشل
المكتشفة أثناء إنشاء الجلسة (`workflow_id` غير معروف، أو
`vendor_data` مدرجة في قائمة الحظر، أو عدم توفر وجه مرجعي لسير عمل
مطابقة الوجه). تعامل مع كلا الشكلين.
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
detail:
type: string
description: >-
رسالة خطأ سهلة القراءة للأخطاء التي لا تتعلق بحقل معين
(مثل عدم كفاية الرصيد). تستخدم حالات الفشل على مستوى
الحقول اسم الحقل كمفتاح بدلاً من ذلك، مع قيمة نصية أو
مصفوفة من النصوص.
example: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
examples:
Missing workflow_id:
summary: تم إغفال حقل مطلوب (بصيغة مصفوفة من النصوص)
value:
workflow_id:
- This field is required.
Invalid workflow_id:
summary: workflow_id غير معروف (صيغة سلسلة نصية بسيطة)
value:
workflow_id: Invalid workflow_id.
Insufficient credits:
summary: نفد رصيد المؤسسة
value:
detail: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
Blocklisted vendor_data:
summary: vendor_data مدرج في قائمة الحظر
value:
vendor_data: >-
This user or business has been blocked and cannot create
new verification sessions.
Portrait image too large:
summary: فشل التحقق من حجم portrait_image
value:
portrait_image:
- Image size exceeds 2MB.
No stored face for vendor_data:
summary: >-
سير عمل مطابقة الوجه بدون portrait_image وبدون وجه مخزن
لمستخدم vendor_data
value:
portrait_image: >-
No stored face image was found for this user. Send a
portrait_image, or complete an approved verification with
face liveness or an ID document for this vendor_data
first.
Portrait image required without vendor_data:
summary: سير عمل مطابقة الوجه بدون portrait_image وبدون vendor_data
value:
portrait_image: >-
A portrait image is required to perform face match for
this workflow. Send a portrait_image, or provide the
vendor_data of a user with a previously stored face image
to reuse it.
'403':
description: >-
فشلت المصادقة أو التفويض. يؤدي استخدام مفتاح خاطئ أو ملغى أو منتهي
الصلاحية إلى إرجاع `401`. يُرجع endpoint الرمز `403` عندما يكون
الرأس `x-api-key` مفقوداً أو يكون مفتاح API صالحاً ولكن العميل لا
يملك إذناً لإنشاء جلسات في هذا التطبيق (على سبيل المثال، ينتمي مفتاح
API إلى مؤسسة مختلفة). تشترك حالات الفشل هذه في نص الاستجابة
`{"detail": "You do not have permission to perform this action."}`.
تأكد من وجود الرأس `x-api-key` وانتمائه إلى التطبيق المقصود، وأعد
جلب مفتاح API للتطبيق عبر [Auth API](/ar/auth-api/get-credentials)
إذا لزم الأمر، ثم أعد المحاولة.
**التطبيق المحذوف:** لبضع دقائق بعد حذف تطبيق ما، قد يستجيب الطلب
المُرسَل بأحد مفاتيح API الخاصة به بـ `{"detail": "This application
was deleted.", "code": "application_deleted"}`. لا تُعد المحاولة:
التطبيق ومفاتيح API الخاصة به لم يعودا موجودين. بعد تلك الدقائق
القليلة، يُرفض المفتاح تماماً كأي مفتاح غير صالح آخر.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You do not have permission to perform this action.
code:
type: string
description: >-
سبب مقروء آلياً، لا يتوفر إلا عند حدوث بعض حالات الفشل.
`application_deleted`: مفتاح API يخص تطبيقاً تم حذفه.
example: application_deleted
required:
- detail
examples:
Missing or invalid API key:
summary: لا يوجد رأس `x-api-key` أو مفتاح API غير صالح
value:
detail: You do not have permission to perform this action.
No permission:
summary: لا يمكن للعميل إنشاء جلسات
value:
detail: You do not have permission to perform this action.
Application deleted:
summary: مفتاح API لتطبيق محذوف
value:
detail: This application was deleted.
code: application_deleted
'429':
description: >-
تم تجاوز حد المعدل — أكثر من 600 طلب لإنشاء الجلسات خلال نافذة زمنية
مدتها 60 ثانية من نفس مفتاح API / عنوان IP. تحقق من `Retry-After`
وانتظر قبل إعادة المحاولة.
**ملاحظة:** يحدد الكود المصدري أيضاً `FREE_SESSION_RATE_LIMIT`
بمقدار 10 استدعاءات/دقيقة إلى جانب `PAID_SESSION_RATE_LIMIT=600`
(`sessions/serializers/session.py`)، ولكن هذا الحد الأقصى للمستوى
المجاني **لا يُطبق على هذا الـ endpoint في V3** — تفرض برمجية حد
المعدل الوسيطة حد `SESSION_CREATE_RATE_LIMIT` البالغ 600/دقيقة بغض
النظر عن الخطة. 600/دقيقة هو الحد الوحيد الذي يمكن أن تصل إليه هنا.
headers:
Retry-After:
description: >-
عدد الثواني التي يجب على المتصل انتظارها قبل إعادة محاولة إرسال
الطلب.
schema:
type: integer
minimum: 1
example: 42
X-RateLimit-Limit:
description: >-
الحد الأقصى لعدد الطلبات المسموح بها في نافذة الـ 60 ثانية
الحالية للحد الذي تم تجاوزه (600 لإنشاء الجلسة session-create).
غير موجود في متغير حصة البيئة التجريبية (sandbox-quota).
schema:
type: integer
example: 600
X-RateLimit-Remaining:
description: >-
عدد الطلبات التي لا تزال مسموحة في النافذة الحالية للحد الذي تم
تجاوزه. غير موجود في متغير حصة البيئة التجريبية (sandbox).
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: >-
ثواني epoch بتوقيت UTC عند إعادة تعيين نافذة حد المعدل الحالية.
غير موجود في متغير حصة البيئة التجريبية.
schema:
type: integer
minimum: 0
example: 1747497600
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: >-
تفسير سهل القراءة لتجاوز حد المعدل. استخدم هذه الرسالة
لتحديد أي من الحدود الثلاثة تم بلوغه.
example: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
examples:
Session-create limit:
summary: أكثر من 600 طلب لإنشاء الجلسات في الدقيقة
value:
detail: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
Sandbox session quota:
summary: تجاوز تطبيق البيئة التجريبية 500 جلسة خلال 24 ساعة
value:
detail: >-
Sandbox session quota exceeded (500 sessions per 24h).
Wait for the window to reset. Expected available in 3600
seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: |-
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new
SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
SessionSignDocument:
type: object
required:
- file_name
- content_base64
properties:
title:
type: string
minLength: 1
maxLength: 255
description: العنوان المعروض للموقّع. القيمة الافتراضية هي `file_name`.
file_name:
type: string
minLength: 1
maxLength: 255
description: اسم الملف، ينتهي بـ `.pdf` أو `.docx`.
content_base64:
type: string
format: byte
description: >-
الملف، بترميز base64. يمكن أن يصل حجم ملف PDF إلى 20 MB و100 صفحة،
دون كلمة مرور أو نصوص برمجية (scripts) أو ملفات مرفقة. يمكن أن يصل
حجم ملف Word (`.docx`) إلى 20 MB ويتم تحويله إلى PDF أثناء تشغيل
الطلب، في غضون 25 ثانية على الأكثر؛ ويخضع ملف PDF حينئذٍ لنفس
الحدود. بحد أقصى 5 ملفات Word لكل جلسة. يتم رفض ملف Word الذي يحتوي
على وحدات ماكرو (macros) أو تعقب التغييرات أو روابط لمحتوى خارجي أو
كائنات مضمنة مع الخطأ `signature_document_not_supported`، والملف
الذي يتعذر تحويله يُرجع `signature_document_conversion_failed`، مع
تحديد `reason` في كل حالة.
fields:
type: array
description: >-
حقول اختيارية لوضعها على هذا المستند، حتى 200 حقل. تشير الصفحات
والمواضع إلى ملف PDF، أو إلى ملف PDF المحول لملف Word. بدون حقول،
يقرأ الموقّع المستند ويوافق عليه.
items:
$ref: '#/components/schemas/SignatureField'
maxItems: 200
SignatureField:
type: object
description: >-
حقل يُوضع على مستند الجلسة: يحدد الموقّع الذي يملؤه، وكيفية ملئه،
ومكانه. حدد إما موضعاً (`page` و `x` و `y` و `width` و `height`) أو
`anchor`. المواضع هي أجزاء كسرية من الصفحة كما تُعرض، بدءاً من الزاوية
العلوية اليسرى، ومقربة إلى 4 منازل عشرية، ويجب أن يكون الحقل ملائماً
لداخل الصفحة. يستوعب المستند ما يصل إلى 200 حقل والموقّع الواحد ما يصل
إلى 500، ويتطلب كل دور له حقول على المستند حقل `signature` أو `initials`
هناك. راجع [الحقول الموجودة على
المستند](/ar/core-technology/electronic-signature/overview#الحقول-على-المستند).
required:
- key
- type
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
description: يُسمّي الحقل في النتائج وفي `sign.field_values`. فريد داخل المستند.
type:
type: string
enum:
- signature
- initials
- full_name
- date_signed
- text
- checkbox
- email
- data
description: >-
ما يحتويه الحقل. يُطبّق الموقّع توقيعه والأحرف الأولى التي اعتمدها
`signature` و `initials`، ويكتب نصاً في `text`، ويحدد خانة اختيار في
`checkbox`، ويكتب بريداً إلكترونياً في `email` عندما لا تحتوي الجلسة
على بريد إلكتروني تم التحقق منه. تملأ Didit حقل `full_name` (الاسم
الذي تم التحقق منه)، و `date_signed` (تاريخ التوقيع، وفق المنطقة
الزمنية للموقّع)، و `data` (من `prefill`)، وبريداً إلكترونياً تم
التحقق منه `email`، وتعرضها للقراءة فقط. لا يوجد نوع لمنتقي التاريخ:
استخدم `text`.
role:
type: string
enum:
- verified_person
- legal_representative
- key_people
description: >-
من يملأ الحقل، بقيم `signature_signer`. تملأ الخطوة وتختم فقط حقول
الموقّع الخاص بها. القيمة الافتراضية هي موقّع الخطوة.
page:
type: integer
minimum: 1
description: >-
رقم الصفحة، من 1 إلى إجمالي عدد صفحات المستند. بالنسبة لمستند Word،
تكون صفحة من ملف PDF المُحوَّل.
x:
type: number
minimum: 0
maximum: 1
description: الحافة اليسرى، ككسر من عرض الصفحة.
'y':
type: number
minimum: 0
maximum: 1
description: الحافة العلوية، كنسبة من ارتفاع الصفحة.
width:
type: number
minimum: 0.02
maximum: 1
description: العرض، كنسبة من عرض الصفحة. يبلغ عرض التوقيع `0.12` على الأقل.
height:
type: number
minimum: 0.012
maximum: 1
description: >-
الارتفاع، كنسبة من ارتفاع الصفحة. يبلغ ارتفاع التوقيع `0.035` على
الأقل.
anchor:
$ref: '#/components/schemas/SignatureFieldAnchor'
required:
type: boolean
description: >-
`signature` and `initials` are required unless you set `false`.
`full_name`, `date_signed` and `data` are always required. The
signer can't finish a document until its required fields have a
value, and a required checkbox must be ticked.
label:
type: string
minLength: 1
maxLength: 80
description: يظهر للموقّع وفي النتائج. القيمة الافتراضية تؤخذ من النوع.
placeholder:
type: string
nullable: true
maxLength: 80
description: '`text` و`email` فقط.'
validation:
$ref: '#/components/schemas/SignatureFieldValidation'
prefill:
type: string
nullable: true
description: >-
مصدر القيمة: `identity.full_name`، أو `identity.first_name`، أو
`identity.last_name`، أو `identity.date_of_birth` (`DD/MM/YYYY`)، أو
`identity.nationality`، أو `identity.document_number`، أو
`identity.document_type`، أو `identity.issuing_country`، أو
`identity.address`، أو `contact.email`، أو `contact.phone`، أو
`company.name`، أو `company.registration_number`، أو
`company.address`، أو `company.country` (KYB)، أو
`session.vendor_data`، أو `metadata.` (مفتاح من `metadata`
الخاصة بالجلسة) أو `api.` (مفتاح من `sign.field_values`). مطلوب
لـ `data`. يستخدم `full_name` دائماً `identity.full_name` ويستخدم
`email` القيمة `contact.email`. يتم تثبيت قيم حقول `data`
و`full_name` و`email` التي تم التحقق منها بمجرد أن يبدأ الموقّع
عملية التوقيع.
editable_when_prefilled:
type: boolean
default: false
description: '`text` و`email` فقط: يمكن للموقّع تغيير القيمة المملوءة مسبقاً.'
checked_by_default:
type: boolean
default: false
description: 'لـ `checkbox` فقط: يبدأ المربع محددًا.'
date_format:
type: string
enum:
- DD/MM/YYYY
- MM/DD/YYYY
- YYYY-MM-DD
- D MMMM YYYY
default: DD/MM/YYYY
description: '`date_signed` فقط.'
SignatureFieldAnchor:
type: object
description: >-
يضع حقلاً بالاستناد إلى نص داخل المستند بدلاً من الموضع. لا تحذف Didit
النص من ملف PDF، لذا اكتبه بنفس لون خلفية الصفحة. عندما لا يتم العثور
على النص، يُرجع الاستدعاء رمز `400` مع `field_anchor_not_found`. راجع
[وضع الحقول حسب النص
المرجعي](/ar/sessions-api/create-session#وضع-الحقول-بحسب-نص-anchor).
required:
- text
properties:
text:
type: string
minLength: 1
maxLength: 64
description: >-
النص الذي تم البحث عنه في المستند. بالنسبة لملف Word، يتم البحث في
ملف PDF المحول.
occurrence:
type: string
enum:
- first
- all
default: first
description: >-
يضع `all` حقلاً واحدًا لكل تطابق؛ وتحصل المفاتيح بعد الأول على `_2`
و`_3` وهكذا.
offset_x:
type: number
description: مُضافة إلى الحافة اليسرى للنص، كنسبة من عرض الصفحة.
offset_y:
type: number
description: مُضافة إلى الحافة العلوية للنص، كنسبة من ارتفاع الصفحة.
width:
type: number
minimum: 0.02
maximum: 1
description: عرض الحقل، كنسبة من عرض الصفحة.
height:
type: number
minimum: 0.012
maximum: 1
description: ارتفاع الحقل، كنسبة من ارتفاع الصفحة.
SignatureFieldValidation:
type: object
nullable: true
description: >-
قواعد لقيمة الحقل `text`. تطبق معاينة لوحة التحكم وسير عمل التوقيع وAPI
نفس القواعد.
properties:
kind:
type: string
enum:
- any
- letters
- number
- email
- pattern
description: >-
`letters`: أحرف بأي نظام كتابة، ومسافات، وشرطات، وفواصل عليا.
`number`: أرقام مع فاصل عشري اختياري. `pattern`: يجب أن تطابق القيمة
`pattern`.
min_length:
type: integer
minimum: 0
maximum: 500
description: من `0` حتى `max_length`.
max_length:
type: integer
minimum: 1
maximum: 500
default: 120
pattern:
type: string
nullable: true
minLength: 1
maxLength: 200
description: >-
مطلوب مع `kind: "pattern"`. تعبير نمطي يجب أن تطابقه القيمة بالكامل.
التوكيدات (lookarounds) والمراجع الخلفية (backreferences) غير
مدعومة.
message:
type: string
nullable: true
maxLength: 120
description: يظهر للموقّع بدلاً من الخطأ الافتراضي.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console.
يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك
إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.