> ## 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

> يتيح Didit للشخص الذي تم التحقق منه، أو لممثلي الشركة، توقيع مستندات PDF وWord ضمن مسار التحقق، بمستوى التوقيع الإلكتروني البسيط أو المتقدم (AES).

يتيح التوقيع الإلكتروني للشخص توقيع مستنداتك ضمن سير العمل نفسه. حيث يطّلع على كل مستند، ويضيف توقيعه، والأحرف الأولى من اسمه، وأي بيانات تطلبها، وفي المستوى المتقدم (AES)، يؤكد التوقيع برمز لمرة واحدة يُرسل إلى البريد الإلكتروني أو رقم الهاتف الذي تم التحقق منه مسبقاً. يُعيد Didit كل مستند موقّعاً، بالإضافة إلى ملف PDF للأدلة يسجّل مَن وقّع وكيف تم ذلك.يشتمل التوقيع الإلكتروني على ثلاثة مستويات. **بسيط** هو المستوى الافتراضي ولا يتطلب التحقق من الهوية أو البريد الإلكتروني أو رقم الهاتف. ويتطلب **متقدم (AES)** عملية تحقق من الهوية مقبولة وبريداً إلكترونياً أو رقم هاتف تم التحقق منه، كما يربط التوقيع بالهوية التي تم التحقق منها. أما **مؤهل (QES)** فهو إضافة ليست متوفرة بعد. راجع [مستويات التوقيع](#مستويات-التوقيع).يعمل هذا مع التحقق من المستخدمين (KYC)، حيث يوقّع الشخص الذي تم التحقق منه، ومع التحقق من الشركات (KYB)، حيث يوقّع الممثلون القانونيون للشركة أو الأشخاص الرئيسيون نيابةً عنها.

تعليمات دمج التوقيع الإلكتروني
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\`Goal:
Add Didit E-signature to a verification workflow: the verified person (KYC) or a company's representatives (KYB) sign PDF or Word documents inside the Didit flow, and your backend receives the signed PDFs and the evidence.

Delivery mode:
E-signature is a workflow step (feature SIGNATURE). There is no standalone signing API: the signer signs inside the hosted Didit flow, the Web SDK or a native SDK.

Prerequisites in the workflow (Advanced (AES) level only; the default Simple level needs no earlier step and no code):
\- KYC: an ID Verification step before the signature step (the signer's identity must be Approved), plus Email Verification (email codes, the default) or Phone Verification (SMS codes) so the code goes to a verified contact. If the workflow has Liveness, it must be Approved too.
\- KYB: a Key People step whose people complete their own KYC with the same prerequisites. signature_signer "legal_representative" picks the key people with the role representative or authorized_signatory; "key_people" picks every eligible key person (1 to 20 signers). For these KYB signers always set signature_level to "aes": "simple" is refused with signature_simple_requires_verified_person, so the workflow cannot be saved.

Steps:
1\. Add the E-signature step to the workflow in the Business Console (or POST /v3/workflows/ with {"feature": "SIGNATURE", "config": {...}}). Upload the documents in the console, or set signature_documents_source to "session" (or "both") to send them per session.
2\. Optional: place fields on each document: signature, initials, full_name, date_signed, text, checkbox, email and read-only data. Workflow documents get their fields in the console's template editor. Session documents carry them in sign.documents[].fields, placed by page and position or by anchor text. Every field has a key; a field with prefill "api.<key>" takes its value from sign.field_values.
3\. Create a session. For per-session documents, send sign.documents with base64 content:

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_WORKFLOW_ID",
"vendor_data": "user-1234",
"sign": {
  "documents": [
    \{
      "title": "Account agreement",
      "file_name": "agreement.pdf",
      "content_base64": "<base64 of the PDF>",
      "fields": [
        \{ "key": "signature", "type": "signature", "page": 3, "x": 0.09, "y": 0.62, "width": 0.36, "height": 0.085 },
        \{ "key": "credit_limit", "type": "data", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.credit_limit" }
      ]
    }
  ],
  "field_values": { "credit_limit": "3,000 EUR" }
}
}'

4\. Send the user to session.url (or open it with the Web or native SDK). Documents with fields need a native SDK release that supports fields; the hosted page and the Web SDK always do.
5\. Wait for the status.updated webhook, then GET /v3/session/{session_id}/decision/.

Decision surface:
signatures[] (one item per signer and signature step). Read:
\- status: the signing stage (intro, review, code, signing, signed, declined).
\- verdict: Not Finished | Approved | In Review | Declined.
\- level ("simple" or "aes"), format ("pdf" for simple, "pades" for aes), profile ("PAdES-B-LT" once an aes step is signed, otherwise null).
\- signer, identity_used, confirmation, certificate, timestamp, adopted_signature, electronic_signature_consent_at.
\- documents[]: mode ("fields" or "read_and_agree"), sha256_original, sha256_signed, status, signed_file (download path), source_format, conversion, fields[] (key, type, value, display_value, value_source, filled_at, image_url).
\- evidence_file (download path), warnings[] ({code, node_id}).

Downloads (x-api-key works):
\- GET /v3/session/{session_id}/signatures/{node_id}/documents/{document_id}/file/ -> signed PDF
\- GET /v3/session/{session_id}/signatures/{node_id}/evidence/?signature_id={id} -> evidence PDF
\- GET /v3/session/{session_id}/signatures/{node_id}/fields/{field_id}/image/ -> applied signature or initials (PNG); use the image_url of the field
\- POST /v3/session/{session_id}/signatures/{node_id}/validate/ -> re-checks the stored signatures

Warnings:
SIGNATURE_DECLINED (default REVIEW), SIGNATURE_OTP_FAILED, SIGNATURE_NAME_MISMATCH, SIGNATURE_IDENTITY_NOT_VERIFIED, SIGNATURE_DOCUMENT_CHANGED (default DECLINE). Each maps to a signature_*_action setting.

Rules:
\- Level: "simple" (default) or "aes". "qes" is an add-on that is not available yet and saving it returns 400 qes_not_available. While signature_availability.aes is false on the workflow, saving a new "aes" step returns 400 aes_not_available.
\- PDF: up to 20 MB and 100 pages each, no password, scripts or attachments. Up to 20 documents and 50 MB per signer.
\- Word: .docx only (.doc, .docm, .odt and .rtf are refused with unsupported_type), up to 20 MB, converted to PDF while the upload or create-session request runs. Fields refer to the converted pages. Macros, tracked changes, external links and embedded objects are refused with signature_document_not_supported; a file that can't be converted returns signature_document_conversion_failed. Both carry a reason.
\- Fields: key matches ^[a-z][a-z0-9_]{0,63}$ and is unique in its document; role defaults to the step's signer; up to 200 fields per document and 500 per signer. Every role with fields on a document needs a signature or initials field. There is no date picker type: use text.
\- Never show success until status is "signed". That is the check at every level. For an aes signature a null certificate, timestamp or signed_file also means "not signed"; a signed simple signature has a signed_file but a null certificate and timestamp.

See also:
\- /core-technology/electronic-signature/report-electronic-signature
\- /core-technology/electronic-signature/warnings-electronic-signature
\- /management-api/workflows/feature-configs#e-signature`

\</pre>



      
      

الصق في

## مستويات التوقيع| المستوى | المتطلبات | ما هو |
| - | - | - |
| **بسيط** | افتراضي. لا يتطلب التحقق من الهوية أو البريد الإلكتروني أو رقم الهاتف | يوقّع الشخص عبر رابط الجلسة دون التحقق من الهوية أو البريد الإلكتروني أو رقم الهاتف أو رمز. إذا كانت الجلسة تتضمن بالفعل اسماً تم التحقق منه، فسيتم استخدامه؛ وإلا فإنه يكتب اسمه، ويشير التوقيع والتقرير إلى أن الاسم قد تمت كتابته ولم يتم التحقق منه. يمكن لأي شخص لديه رابط الجلسة التوقيع، لذا اختر بسيط للاتفاقيات منخفضة المخاطر؛ بينما يجب أن تستخدم العقود الخاضعة للتنظيم أو ذات القيمة العالية المستوى المتقدم (AES). الملف الموقّع هو عبارة عن ملف PDF يتضمن صفحة أدلة ولا يحمل أي توقيع رقمي أو ختم أو طابع زمني. يحتفظ Didit بـ SHA-256 الخاص بالسجل ولكل ملف موقّع، بحيث يمكن اكتشاف أي تغيير لاحق. |
| **متقدم (AES)**، التوقيع الإلكتروني المتقدم | عملية تحقق من الهوية مقبولة وبريد إلكتروني أو رقم هاتف تم التحقق منه في الجلسة نفسها | يتم توقيع كل مستند بتنسيق PAdES، وهو تنسيق توقيع PDF، مع ملف تعريف التحقق طويل الأجل (`PAdES-B-LT`): يحمل التوقيع طابعاً زمنياً وفقاً للمعيار RFC 3161 صادراً عن Didit وبيانات الإلغاء اللازمة للتحقق من صحته لاحقاً. وهو مرتبط بشكل فريد بالموقّع من خلال هويته التي تم التحقق منها والرمز لمرة واحدة الذي أكده، وأي تغيير في المستند بعد التوقيع يبطله. |
| **مؤهل (QES)**، التوقيع الإلكتروني المؤهل | إضافة، غير متوفر بعد | سيتم التوقيع بشهادة مؤهلة صادرة للموقّع. تُظهر لوحة التحكم الخيار كـ **قريباً**، ويؤدي حفظ `signature_level: "qes"` عبر API إلى إرجاع `400` مع `qes_not_available`. ولا يتم استبداله مطلقاً بـ AES تلقائياً دون إشعار. |يتم التوقيع في المستوى المتقدم (AES) بتنسيق PAdES فقط. وتُرفض قيم `signature_format` التالية `xades` و `cades` بالنسبة لـ AES مع إرجاع `signature_format_not_supported`. تحقق من `signature_availability` في سير العمل قبل حفظ خطوة AES: فعندما تكون قيمة `aes` هي `false`، فإن حفظ خطوة جديدة يُرجع `400` مع `aes_not_available`.## كيف يعمل**1. بالنسبة للمستوى المتقدم (AES)، يتحقق سير العمل من الموقّع أولاً**في المستوى المتقدم (AES)، يتم تشغيل خطوة التوقيع بعد الخطوات التي تحدد هوية الموقّع: التحقق من الهوية، والتحقق من البريد الإلكتروني أو التحقق من رقم الهاتف لجهة الاتصال التي يُرسل إليها الرمز. راجع [قبل البدء](#قبل-البدء). ولا يتطلب المستوى البسيط أي خطوة سابقة.**2. يجهّز Didit المستندات**عندما يصل الموقّع إلى هذه الخطوة، ينسخ Didit المستندات وحقولها إلى الجلسة ويسجّل قيمة SHA-256 لكل مستند. ولا يمكن للتغييرات اللاحقة في سير العمل تغيير ما يراه هذا الموقّع.**3. يطّلع الموقّع على كل مستند**بالنسبة للمستند الذي يحتوي على حقول، يتم توجيه الموقّع من حقل إلى آخر. حيث يعتمد توقيعاً مرة واحدة ويتم تطبيقه على كل حقل توقيع وأحرف أولى، ويملأ الحقول النصية ومربعات الاختيار. وتكون القيم التي يأخذها Didit من الهوية التي تم التحقق منها أو الجلسة أو نظامك موجودة بالفعل في الصفحة. أما بالنسبة لمستند بدون حقول، فيقرأه ويوافق عليه.**4. بالنسبة للمستوى المتقدم (AES)، يؤكد الموقّع برمز**عندما يحتوي أي مستند على حقول، يوافق الموقّع أولاً على توقيع المستندات إلكترونياً. وفي المستوى المتقدم (AES)، يرسل Didit بعد ذلك رمزاً مكوناً من ستة أرقام إلى البريد الإلكتروني أو الهاتف الذي تم التحقق منه مسبقاً في الجلسة، ويؤدي إدخاله إلى تفويض التوقيع على كل مستند في الخطوة. أما في المستوى البسيط، فلا يوجد رمز: فالموافقة هي ما يفوّض التوقيع.**5. يوقّع Didit ويختم**يملأ Didit تاريخ التوقيع، ويثبّت قيمة كل حقل في كل ملف PDF ويرفق صفحة الأدلة. وفي المستوى المتقدم (AES)، يطبّق بعد ذلك توقيع PAdES والطابع الزمني، بحيث يشمل التوقيع كل شيء في الصفحة. وفي المستوى البسيط، يكون الملف عبارة عن ملف PDF يتضمن صفحة الأدلة دون توقيع رقمي أو ختم أو طابع زمني.**6. تحصل على النتائج**تحمل أحداث webhook الخاصة بالقرار وبالجلسة مصفوفة `signatures[]` مع الموقّع، والتأكيد، والشهادة، والطابع الزمني، وقيم التجزئة لكل مستند، وقيمة كل حقل. يمكنك تنزيل ملفات PDF الموقّعة وملف PDF للأدلة، ويمكن لـ Didit إرسال نسخة عبر البريد الإلكتروني إلى الموقّع.## قبل البدءفي المستوى المتقدم (AES)، يجب التحقق من المُوقّع قبل أن يتمكن من التوقيع. تأخذ Didit اسمه وبيانات الاتصال الخاصة به من السجلات المتحقق منها للجلسة نفسها، ولا تأخذها أبداً مما تدخله أنت أو المُوقّع كتابةً. لا يتطلب المستوى البسيط (Simple) أيّاً من ذلك: فهو لا يتضمن التحقق من الهوية، أو التحقق من البريد الإلكتروني، أو التحقق من رقم الهاتف، أو أي رمز، ويتم رفضه لمُوقّعي KYB.**بالنسبة إلى التحقق من المستخدمين (KYC)**، ضع هذه الخطوات قبل التوقيع الإلكتروني في سير العمل:- **التحقق من الهوية**، وتكون مقبولة، وباسم يمكن قراءته. ومن دونها، تُسجّل الخطوة `SIGNATURE_IDENTITY_NOT_VERIFIED`.
- **التحقق من البريد الإلكتروني** عندما يُرسل الرمز عبر البريد الإلكتروني (الوضع الافتراضي)، أو **التحقق من رقم الهاتف** عندما يُرسل عبر الرسائل القصيرة (SMS). يُرسل الرمز فقط إلى وسيلة اتصال تم التحقق منها في الجلسة نفسها.
- إذا كان سير العمل يتضمن أيضاً **كشف الحيوية**، فيجب أن تكون مقبولة.لإرسال نسخة من المستندات الموقعة إلى المُوقّع عبر البريد الإلكتروني، تحتاج الجلسة أيضاً إلى بريد إلكتروني تم التحقق منه، حتى عندما يُرسل الرمز عبر الرسائل القصيرة (SMS).**بالنسبة إلى التحقق من الشركات (KYB)**، يكون المُوقّعون هم الأشخاص الرئيسيون في الشركة، ولكل منهم جلسة KYC مقبولة خاصة به:| `signature_signer` | من يُوقّع |
| - | - |
| `legal_representative` | كل شخص رئيسي يحمل الدور `representative` أو `authorized_signatory` |
| `key_people` | كل شخص رئيسي من الأفراد لديه جلسة KYC |تتضمن خطوة KYB ما بين 1 و20 مُوقّعاً، ويحتاج كل منهم إلى KYC مقبولة بحلول وقت التوقيع. يُوقّع كل شخص نسخته الخاصة من المستندات ويؤكد ذلك برمز يُرسل إلى وسيلة الاتصال التي تم التحقق منها في جلسة KYC الخاصة به. يجب أن يتطابق الاسم المُصرّح به للشخص الرئيسي مع اسمه المتحقق منه، مع تجاهل حالة الأحرف والمسافات، وإلا تُسجّل الخطوة `SIGNATURE_NAME_MISMATCH`. تكتمل الخطوة بمجرد أن يُوقّع كل مُوقّع أو يرفض.## المستندات### مصدر المستنداتيحدد `signature_documents_source` من أين تحصل الخطوة على مستنداتها:| القيمة | المستندات |
| - | - |
| `workflow` (الافتراضي) | المستندات التي قمت برفعها إلى سير العمل في لوحة التحكم. توقّع كل جلسة على نفس المستندات. |
| `session` | المستندات التي ترسلها في `sign.documents` عند [إنشاء الجلسة](https://docs.didit.me/ar/sessions-api/create-session.md#مستندات-التوقيع-الإلكتروني). توقّع كل جلسة مستنداتها الخاصة. |
| `both` | مستندات سير العمل أولاً، تليها مستندات الجلسة. |المستندات المخصصة لكل جلسة هي الطريقة لجعل الشخص يوقع عقداً يتضمن اسمه أو مبلغه أو شروطه المعبأة مسبقاً بواسطة نظامك.### الملفات المدعومة| | الحد الأقصى |
| - | - |
| PDF | ما يصل إلى 20 MB و100 صفحة لكل مستند. بدون كلمة مرور أو برمجيات نصية أو ملفات مرفقة. |
| Word (`.docx`) | ما يصل إلى 20 MB. يتم تحويله إلى PDF عند رفعه أو إنشاء الجلسة، ويخضع ملف PDF المحوَّل لنفس قيود PDF. يتم رفض ملفات `.doc` و`.docm` و`.odt` و`.rtf` بالرمز `unsupported_type`. |
| لكل موقّع | ما يصل إلى 20 مستنداً و50 MB إجمالاً. |عند رفع مستند Word، تقوم Didit بتحويله إلى PDF أثناء تنفيذ عملية الرفع، في غضون 60 ثانية كحد أقصى. الصفحات المحوَّلة هي ما يراه الموقّع ويوقّع عليه، لذا تحقق منها قبل وضع الحقول: قد تختلف فواصل الأسطر قليلاً مقارنة بـ Word. ينتمي ملف Word وملف PDF الخاص به إلى نفس المستند ويتم حذفهما معه. يسجل ملف PDF الخاص بالأدلة عملية التحويل وقيمة SHA-256 لكلا الملفين.ترفض Didit ملف Word مع `signature_document_not_supported` و`reason` عندما يكون ما سيتم توقيعه مبهماً: كأن يحتوي على وحدات ماكرو (`macros`)، أو تغييرات متعقَّبة غير مقبولة (`tracked_changes`)، أو روابط لمحتوى خارجي (`external_links`)، أو كائنات مضمّنة (`embedded_objects`). اقبل التغييرات المتعقَّبة أو ارفضها قبل الرفع، حتى يعرض ملف PDF النص الذي وافقت عليه.يتم رفض الملف الذي يتعذر تحويله بالرمز `signature_document_conversion_failed` وأحد هذه الأسباب:| `reason` | سبب المشكلة |
| - | - |
| `docx_password_protected` | الملف محمي بكلمة مرور. أزلها ثم ارفعه مجدداً. |
| `docx_unreadable` | الملف ليس مستند Word قابلاً للقراءة. |
| `docx_too_many_pages` | يحتوي ملف PDF المحوَّل على أكثر من 100 صفحة. |
| `docx_too_large` | الملف كبير جداً ولا يمكن تحويله. |
| `conversion_timeout` | استغرق التحويل وقتاً طويلاً جداً. أعد المحاولة، أو ارفع المستند كملف PDF. |### الحقول على المستندتحوّل الحقول المستند إلى قالب يملؤه الموقّع، تماماً كما تُعد مظروفاً في أداة توقيع مكتبية. يحافظ المستند الخالي من الحقول على المسار الأبسط: يقرأه الموقّع ويوافق عليه.| النوع | ما يفعله الموقّع | القيمة |
| - | - | - |
| `signature` | ينقر عليه لتطبيق توقيعه المعتمد. يفتح أول حقل توقيع أو حقل أحرف أولى الخطوة التي يعتمد فيها الموقّع توقيعه. | `true` بمجرد تطبيقه |
| `initials` | ينقر عليه لتطبيق أحرفه الأولى المعتمدة. | `true` بمجرد تطبيقها |
| `text` | يكتب قيمة، يتم فحصها وفقاً لـ [التحقق من صحة](#التحقق-من-الصحة) الحقل. يمكن ملؤها مسبقاً. | String |
| `checkbox` | يحدده أو يلغي تحديده. يجب تحديد مربع الاختيار الإلزامي. | Boolean |
| `email` | لا يفعل شيئاً عندما تتضمن الجلسة بريداً إلكترونياً تم التحقق منه، حيث يتم ملؤه للقراءة فقط. وبخلاف ذلك، يقوم بكتابته. | String |
| `full_name` | لا يفعل شيئاً: تملأ Didit الاسم الذي تم التحقق منه، للقراءة فقط. | String |
| `date_signed` | لا يفعل شيئاً: تملأ Didit تاريخ توقيع المستندات. | String |
| `data` | لا يفعل شيئاً: تملأ Didit قيمة من الهوية التي تم التحقق منها أو الجلسة أو نظامك، للقراءة فقط. حدد مصدرها في `prefill`. | String |لا يوجد منتقي تاريخ في هذا الإصدار. استخدم حقل `text` للتاريخ الذي يدخله الموقّع.يحتوي الحقل على هذه الخصائص:| الخاصية | القواعد |
| - | - |
| `id` | تحدده Didit. |
| `key` | يسمي الحقل في النتائج وفي `sign.field_values`. أحرف صغيرة وأرقام وشرطات سفلية، تبدأ بحرف، حتى 64 حرفاً (`^[a-z][a-z0-9_]{0,63}$`)، وفريد داخل المستند. |
| `type` | أحد الأنواع المذكورة أعلاه. |
| `role` | من يملؤه، بقيم `signature_signer`: إما `verified_person` أو `legal_representative` أو `key_people`. في مستند الجلسة، تكون قيمته الافتراضية هي موقّع الخطوة. |
| `page` | من 1 إلى عدد صفحات المستند. بالنسبة لمستند Word، تكون صفحة من ملف PDF المحوَّل. |
| `x`, `y`, `width`, `height` | أجزاء من الصفحة كما يتم عرضها (من `0` إلى `1`)، مقاسة من الزاوية العلوية اليسرى ومقربة إلى 4 منازل عشرية. يجب أن يتسع الحقل داخل الصفحة. يبلغ عرضه `0.02` على الأقل وارتفاعه `0.012` على الأقل، والتوقيع على الأقل `0.12` في `0.035`. |
| `required` | الحقول `signature` و`initials` إلزامية ما لم تعيّن القيمة `false`. والحقول `full_name` و`date_signed` و`data` إلزامية دائماً. |
| `label` | من 1 إلى 80 حرفاً، يظهر للموقّع وفي النتائج. |
| `placeholder` | لـ `text` و`email` فقط. حتى 80 حرفاً. |
| `position` | الترتيب الذي يتم توجيه الموقّع من خلاله، بدءاً من `0`. تحدده Didit بناءً على موضع الحقل: حسب الصفحة، ثم من الأعلى إلى الأسفل، ثم من اليسار إلى اليمين. |
| `validation` | لـ `text` فقط. راجع [التحقق من الصحة](#التحقق-من-الصحة). |
| `prefill` | مصدر القيمة. راجع [القيم المملوءة مسبقاً](#القيم-المعبأة-مسبقاً). |
| `editable_when_prefilled` | لـ `text` و`email` فقط: يمكن للموقّع تغيير القيمة المملوءة مسبقاً. القيمة الافتراضية `false`. |
| `checked_by_default` | لـ `checkbox` فقط: يبدأ المربع محدداً. |
| `date_format` | لـ `date_signed` فقط: `DD/MM/YYYY` (الافتراضي)، أو `MM/DD/YYYY`، أو `YYYY-MM-DD`، أو `D MMMM YYYY`. |```json theme={null}
{
  "id": "6a2f1c0e-4d8b-4f5e-9a51-0c7b2e9d3f10",
  "key": "occupation",
  "type": "text",
  "role": "verified_person",
  "page": 1,
  "x": 0.34,
  "y": 0.4618,
  "width": 0.57,
  "height": 0.0325,
  "required": true,
  "label": "Occupation",
  "placeholder": "For example, nurse",
  "position": 5,
  "validation": { "kind": "any", "min_length": 0, "max_length": 80, "pattern": null, "message": null },
  "prefill": null,
  "editable_when_prefilled": false,
  "checked_by_default": false,
  "date_format": null
}
```يستوعب المستند ما يصل إلى 200 حقل، ويصل الحد الأقصى للموقّع الواحد إلى 500 حقل عبر مستنداته.تملأ الخطوة وتختم فقط حقول الموقّع الخاص بها. يمكن أن يحتوي المستند على حقول لأدوار متعددة فقط عندما تستخدمه عدة خطوات توقيع في سير العمل: تملأ كل خطوة حقول الدور الخاص بها وتترك الحقول الأخرى فارغة في نسختها. يتم رفض أي حقل لدور لا تستخدمه أي خطوة توقيع في سير العمل بالرمز `role_not_used`. يحتاج كل دور له حقول على المستند إلى حقل `signature` أو `initials` واحد على الأقل هناك، وإلا فلن يمكن نشر إصدار سير العمل (`signature_field_missing`).#### التحقق من الصحةينطبق `validation` على حقول `text`:```json theme={null}
{ "kind": "any", "min_length": 0, "max_length": 80, "pattern": null, "message": null }
```- `kind`: إما `any`؛ أو `letters` (أحرف بأي نظام كتابة، ومسافات، وشرطات وعلامات فاصلة عليا)؛ أو `number` (أرقام مع فاصل عشري اختياري)؛ أو `email`؛ أو `pattern`.
- `min_length`: من `0` حتى `max_length`.
- `max_length`: من `1` إلى `500`. القيمة الافتراضية `120`.
- `pattern`: مطلوب عندما يكون `kind: "pattern"`. تعبير نمطي يصل إلى 200 حرف يجب أن تتطابق القيمة بأكملها معه. لا تُدعم مجموعات البحث المسبق/اللاحق والمراجع الخلفية.
- `message`: ما يصل إلى 120 حرفاً، يُعرض بدلاً من الخطأ الافتراضي.تُطبق معاينة لوحة التحكم وتدفق التوقيع وواجهة API القواعد نفسها.#### القيم المعبأة مسبقاًيحدد `prefill` مصدر قيمة الحقل:| `prefill` | القيمة |
| - | - |
| `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` | قيمة `vendor_data` الخاصة بالجلسة. |
| `metadata.<key>` | قيمة `<key>` في `metadata` الخاصة بالجلسة، كسلسلة نصية. |
| `api.<key>` | قيمة `<key>` في `sign.field_values`، المرسلة عند [إنشاء الجلسة](https://docs.didit.me/ar/sessions-api/create-session.md#قيم-الحقول). |يجب أن يحتوي حقل `data` على `prefill`. يستخدم حقل `full_name` دائماً `identity.full_name` ويستخدم حقل `email` القيمة `contact.email`، ويمكن لحقل `text` أن يحتوي على واحد أيضاً. تُثبَّت قيم حقول `data` و`full_name` وحقول `email` المتحقق منها عند بدء الموقّع في التوقيع: أي تغييرات لاحقة على الجلسة لن تغيّرها. يكون حقل `text` أو `email` المعبأ مسبقاً للقراءة فقط ما لم تقم بتعيين `editable_when_prefilled`.عندما لا يحتوي مصدر حقل مطلوب على قيمة في تلك اللحظة، على سبيل المثال جلسة بدون عنوان، يظل الحقل فارغاً ويظل بإمكان الموقّع التوقيع. لا يتم إصدار أي تحذير، ويوضح `value_unavailable_reason` في [التقرير](https://docs.didit.me/ar/core-technology/electronic-signature/report-electronic-signature.md) السبب.## إعداد الميزة في لوحة التحكم1) انتقل إلى **سير العمل**، وافتح سير عمل وأضف خطوة **التوقيع الإلكتروني** بعد الخطوات التي تتحقق من الموقِّع.
2) في **المستندات**، حدد **رفع** لإضافة ملفات PDF أو Word، واسحبها بالترتيب الذي يراها به الموقِّع. تُحوَّل ملفات Word إلى PDF: تحقق من الصفحات المحوَّلة قبل وضع الحقول. يؤدي خيار **استبدال** إلى تبديل ملف المستند مع الاحتفاظ بحقوله، باستثناء تلك الموجودة في صفحات لم تعد متوفرة في الملف الجديد.
3) تحت **ضع الحقول على المستندات**، حدد **فتح المحرر**. اسحب حقلاً من اللوحة وضعه على الصفحة، أو حدده وانقر في المكان المخصص له، ثم انقله وغير حجمه. لكل حقل، عيّن **من يملؤه**، وتسميته، وما إذا كان **مطلوب**، وما يقبله، ومن أين تأتي قيمته و**مفتاح API** الخاص به (قيمة `key` للحقل). تعرض **معاينة كموقّع** المستند كما يراه الموقِّع على الهاتف أو سطح المكتب. يحفظ المحرر التغييرات أثناء عملك (**حُفظ في المسودة**) ويسرد ما يجب إصلاحه قبل أن تحدد **تم**.
4) في **المستندات** أيضاً، اختر مصدر المستندات: **سير العمل هذا**، أو **كل جلسة**، أو **كلاهما**. بالنسبة للمستندات التي لا تحتوي على حقول، اختر ما إذا كان يجب على الموقِّع **القراءة حتى النهاية قبل التوقيع** وتقديم **موافقة مستقلة لكل مستند**.
5) في **التوقيع**، اختر **الموقِّع**، و**المستوى** (**بسيط**، وهو الافتراضي، أو **متقدم (AES)**؛ بينما يظهر **مؤهل (QES)** كـ **قريباً**)، و**الصيغة** وطريقة إرسال الرمز (**إرسال الرمز أحادي الاستخدام عبر**).
6) في **القواعد**، حدد ما يحدثه كل [تحذير](https://docs.didit.me/ar/core-technology/electronic-signature/warnings-electronic-signature.md) في القرار النهائي.
7) في قسم **متقدم**، اختر ما إذا كنت تريد **إرسال النسخة الموقعة بالبريد الإلكتروني** و**إضافة صفحة أدلة**، وعدد الأيام التي يظل فيها رابط التوقيع صالحاً. يمكنك أيضاً إضافة قواعد حالة مخصصة.
8) احفظ سير العمل.لتهيئة الخطوة نفسها عبر واجهة API، راجع [إعدادات ميزات سير العمل](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#التوقيع-الإلكتروني). تُدار مستندات سير العمل وحقولها في لوحة التحكم؛ بينما عبر واجهة API، يتم إرسال المستندات والحقول لكل جلسة.## تجربة التوقيعتعمل خطوة التوقيع في صفحة التحقق المستضافة، و[Web SDK](https://docs.didit.me/ar/integration/web-sdks/overview.md)، و[حزم SDK الأصلية](https://docs.didit.me/ar/integration/native-sdks/overview.md)، على أجهزة سطح المكتب والهواتف المحمولة. لست بحاجة إلى بناء أي واجهة مستخدم للتوقيع.1) **المقدمة.** يرى الموقّع المستندات التي هو على وشك توقيعها.
2) **كل مستند على حدة، بالترتيب.** بالنسبة للمستند الذي يحتوي على حقول، يتم إرشاد الموقّع عبر حقوله وفق ترتيب `position`. يفتح أول حقل توقيع أو حقل أحرف أولى نافذة منبثقة حيث [يعتمد توقيعاً](#اعتماد-توقيع). الحقول الاختيارية تحمل علامة **اختياري**. تظهر القيم التي ملأتها Didit على الصفحة مع رمز قفل وليست خطوات تفاعلية. يؤدي النقر فوق أي حقل على الصفحة إلى الانتقال إليه مباشرة. على الهاتف المحمول، يظهر حقل واحد في كل مرة داخل لوحة تبقى أعلى لوحة المفاتيح. وعلى شاشة بعرض 1200 بكسل على الأقل، تظهر الصفحة بجانب قائمة الحقول. عند إنهاء مستند مع بقاء حقل إلزامي فارغاً، يظهر عدد الحقول المتبقية ويتم الانتقال إلى أول حقل منها. والمستند غير المتضمن لحقول تتم قراءته والموافقة عليه، وفقاً لما قمت بتهيئته.
3) **المراجعة.** يرى الموقّع المستندات مرة أخرى، وفي حال احتواء أي منها على حقول، يوافق على توقيعها إلكترونياً.
4) **الرمز (Advanced (AES) فقط).** يطلب الموقّع رمزه. ويكون الرمز صالحاً لمدة 5 دقائق، ويمكن إرسال رمز جديد بعد 60 ثانية، ويحصل الموقّع على ما يصل إلى 5 رموز و3 محاولات خاطئة. يؤدي استنفاد الرموز أو المحاولات إلى تسجيل `SIGNATURE_OTP_FAILED`. في المستوى Simple، لا يوجد رمز: ينتقل الموقّع مباشرة من المراجعة إلى التوقيع.
5) **تم التوقيع.** بعد التوقيع، يمكن للموقّع تنزيل مستنداته الموقّعة. وإذا قمت بتمكين هذا الخيار، ترسل Didit أيضاً نسخة عبر البريد الإلكتروني.
6) **الرفض.** يمكن للموقّع الرفض بدلاً من التوقيع. يؤدي ذلك إلى تسجيل `SIGNATURE_DECLINED`. يمكن إعادة فتح حالة الرفض طالما كان رابط التوقيع صالحاً، بحيث يظل بإمكان الموقّع التوقيع إذا غير رأيه.يخبر سير العمل الموقّع في حال انتهاء صلاحية الرمز، أو تعديل مستند، أو فشل التوقيع، أو انتهاء صلاحية رابط التوقيع.يظل رابط التوقيع صالحاً طوال فترة `signature_link_validity_days` (من 1 إلى 30، القيمة الافتراضية 7)، وتُحتسب بدءاً من وقت إنشاء الجلسة. وتظل الجلسة مفتوحة لهذه المدة على الأقل.> [!NOTE]
>
> تعرض حزم SDK الأصلية خطوة التوقيع بدءاً من الإصدار الذي يضيفها، والمذكور في [نظرة عامة على حزم SDK الأصلية](https://docs.didit.me/ar/integration/native-sdks/overview.md) عند طرحه. تتطلب المستندات التي تحتوي على حقول إصداراً يدعم الحقول: فالإصدارات الأقدم لا يمكنها عرضها، وتُظهر الخطوة خطأً بدلاً من ذلك. أما المستندات الخالية من الحقول فتعمل في كل إصدار يتضمن خطوة التوقيع. وإلى أن يشغّل تطبيقك إصداراً يدعم ما يستخدمه سير العمل لديك، وجّه المستخدمين إلى الصفحة المستضافة أو Web SDK.### اعتماد توقيعيعتمد الموقّع توقيعه والأحرف الأولى مرة واحدة، في نافذة واحدة، في أول مرة يطلب فيها المستند أياً منهما:- **مكتوب**: اسمه الذي تم التحقق منه بأسلوب كتابة يدوية يختاره، مع علامة **من هويتك**. لا يمكنه كتابة اسم مختلف. والأحرف الأولى المكتوبة هي الحروف الأولى من ذلك الاسم.
- **مرسوم**: يتم رسمه بالإصبع أو بالماوس، لكل من التوقيع والأحرف الأولى.يتم تطبيق أي حقل توقيع أو أحرف أولى لاحق بنقرة واحدة، ويؤدي النقر فوق حقل مطبق إلى إزالته مجدداً.## النتائجتكون نتيجة كل موقّع عنصراً ضمن `signatures[]` في [قرار الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session.md) وضمن `decision` في [webhooks الجلسة](https://docs.didit.me/ar/integration/webhooks.md). لا يوجد webhook منفصل للتوقيع: يخبرك حدث webhook للجلسة `status.updated` بموعد جلب القرار.تحصل على ملف PDF موقّع لكل مستند، وملف PDF للإثباتات لكل موقّع، وتجزئة SHA-256 لكل ملف أصلي وموقّع، بحيث يمكنك إثبات عدم تغيير أي شيء لاحقاً. بالنسبة للمستندات التي تحتوي على حقول، تحصل أيضاً على قيمة كل حقل، ومصدره، ووقت ملئه، بالإضافة إلى التوقيع المعتمد ووقت موافقة الموقّع على التوقيع إلكترونياً. راجع [تقرير التوقيع الإلكتروني](https://docs.didit.me/ar/core-technology/electronic-signature/report-electronic-signature.md) للاطلاع على كل حقل، وعمليات التنزيل، وكيفية التحقق من صحة التوقيع مرة أخرى.في لوحة التحكم، تعرض علامة تبويب **التوقيع** الخاصة بالجلسة المستندات، ثم كتلة **الحقول** مع معاينة لكل صفحة، والتوقيع والأحرف الأولى المعتمدة، وقيمة كل حقل ووقته ومصدره. يتضمن [تقرير PDF](https://docs.didit.me/ar/sessions-api/generate-pdf.md) قسماً للتوقيع، وصفحة **التوقيع الإلكتروني · الحقول** عندما تحتوي المستندات على حقول.## الأسعارتبلغ تكلفة التوقيع الإلكتروني \$0.10 لكل جلسة موقّعة، وتكون مشمولة في رصيدك المجاني، بصرف النظر عن عدد المستندات في عملية التوقيع الواحدة وسواء كان المستوى Simple أو Advanced (AES). لا يتم احتساب أي رسوم على التوقيع المرفوض، أو الذي يفشل، أو الذي تنتهي صلاحيته. يُعد Qualified (QES) ميزة إضافية غير متاحة بعد وليس لها سعر حالياً.## حذف بيانات التوقيععندما تقوم بـ [حذف جلسة](https://docs.didit.me/ar/sessions-api/delete-session.md)، تُحذف بيانات التوقيع الخاصة بها معها: المستندات المرسلة مع الجلسة وملفات Word الأصلية الخاصة بها، والنسخ المعدة لكل موقّع، وملفات PDF الموقّعة، وملفات PDF للإثباتات، وصور التوقيع والأحرف الأولى المعتمدة، وكل قيم الحقول. وتتوقف روابط تنزيلها عن العمل. ويحدث الشيء نفسه عند حذف جلسة في نهاية فترة الاحتفاظ بالبيانات الخاصة بك. لا يمكن التراجع عن الحذف، لذا قم بتنزيل أي شيء تحتاج إلى الاحتفاظ به أولاً.- المستندات الموقّعة الخاصة بالتحقق من الشركات (KYB) تتبع جلسة الشركة. ويؤدي حذف تلك الجلسة إلى حذفها.
- تؤدي إزالة مستند من سير العمل إلى حذفه، مع حقوله وملف Word الأصلي الخاص به. ويحتفظ الموقّع الذي بدأ التوقيع بالفعل بالنسخة التي عُرضت عليه، كجزء من جلسته، حتى تقوم بحذف تلك الجلسة. لا تقم بإزالة المستندات إلا من سير العمل الذي لا توجد به جلسات تنتظر التوقيع.
- النسخة التي أرسلتها Didit بالفعل عبر البريد الإلكتروني إلى الموقّع تظل في صندوق بريده ولا تتأثر.## مواضيع ذات صلة- [تقرير التوقيع الإلكتروني](https://docs.didit.me/ar/core-technology/electronic-signature/report-electronic-signature.md): `signatures[]`، وملف PDF الموقّع، وملف PDF للإثباتات، وعمليات التنزيل.
- [تحذيرات التوقيع الإلكتروني](https://docs.didit.me/ar/core-technology/electronic-signature/warnings-electronic-signature.md): كل تحذير والقاعدة التي تتحكم فيه.
- [إنشاء جلسة](https://docs.didit.me/ar/sessions-api/create-session.md#مستندات-التوقيع-الإلكتروني): إرسال المستندات والحقول وقيم الحقول لكل جلسة.
- [تكوينات ميزات سير العمل](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#التوقيع-الإلكتروني): كل إعداد من إعدادات الخطوة.


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