تخطّي إلى المحتوى
المطوّرون · مرجع الـAPI

مرجع الـAPI الكامل

مرجع تقني دقيق لواجهة برمجة التطبيقات (API) في «وثائق»، يتناول كل نقطة نهاية وكل كائن، ويشمل المصادقة والأخطاء وترقيم الصفحات ومنع التنفيذ المكرّر (Idempotency) وحدود المعدّل، وطلبات التوقيع والموقّعين والمستندات والقوالب وتأكيد الهوية والتحقّق والأحداث وإشعاراتها الآلية (Webhooks). ولكل استدعاء أمثلة جاهزة بـcURL و Node.

ابدأ خلال خمس دقائق المرجع التفاعلي (جرّب مباشرة) دليل الـAPI
BASE URL https://wthaiq.com/api/v1
الإصدار 2026-07-01 المصادقة Bearer sk_... الاستجابة application/json
create-signature-request.sh 
curl -X POST https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f3c9c2e-..." \
  -d '{
    "title": "عقد عمل — أحمد م.",
    "source": { "type": "template", "template_id": "tpl_employment" },
    "legal_level": "aes",
    "ordered": true,
    "signers": [
      { "name": "أحمد محمد", "email": "ahmed@example.com",
        "method": "draw", "require_identity": true }
    ]
  }'

نظرة عامة

تتبع واجهة برمجة التطبيقات في «وثائق» نمط REST المنظَّم حول الموارد، فتستخدم مسارات HTTP يسهل توقّعها، وترمز الأخطاء بأكواد HTTP القياسية، وتتبادل البيانات بصيغة application/json (يُستثنى من ذلك رفع الملفات بصيغة multipart/form-data). وتمرّ جميع الطلبات عبر HTTPS حصرًا.

الطوابع الزمنية أعداد صحيحة تمثّل الثواني المنقضية منذ Unix epoch. ويحمل كل مورد معرّفًا فريدًا تسبقه بادئة تدلّ على نوعه، فيسهل تتبّع الكائنات في السجلّات:

البادئةالموردمثال
sr_signature_requestsr_3n8Kd2Qa1V
sgr_signersgr_9fA2
doc_documentdoc_7Yq
tpl_templatetpl_employment
idv_identity_verificationidv_5k
evt_eventevt_2M
we_webhook_endpointwe_1a
key_api_keykey_88
العنوان الأساسي: جميع المسارات نسبية إلى https://wthaiq.com/api/v1. ويُثبَّت الإصدار بتاريخه عبر الترويسة Wthaiq-Version، وتُوثَّق التغييرات بتواريخها في سجل التغييرات.
أمثلة Node: تستعمل أمثلة Node في هذه الصفحة مكتبة wthaiq الرسمية، وأمر تثبيتها وأمثلة المكتبات الأخرى في صفحة المكتبات الرسمية.

المصادقة

تُصادَق الطلبات بمفتاح سرّي يُرسَل في الترويسة Authorization وفق نمط HTTP Bearer. ولمفاتيحك صلاحيات كاملة، فاحفظها على الخادم فقط، ولا تضعها في شيفرة جهة العميل أو المستودعات العامة أو تطبيقات الهاتف.

المفتاحالصيغةالوصف
المفتاح السرّيsk_...له صلاحيات كاملة، ويُستخدم على الخادم فقط. والمفتاح الحيّ يُرسل رسائل فعلية ويُصدر شهادات قانونية وتُفوتَر إرسالاته، أمّا مفتاح التجربة sk_test_ فلا يفعل شيئًا من ذلك. راجع قسم «مفاتيح التجربة والمفاتيح الحيّة».
المفتاح العامpk_...آمن عند كشفه في المتصفّح، ومُقيَّد بنطاقاتك، ومحصور في مجموعة ثابتة من المسارات.
سرّ إشعارات الأحداثwhsec_...يُستخدم للتحقّق من توقيع إشعارات الأحداث (HMAC-SHA256).
auth.sh 
curl https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
تحذير أمني: يُرفَض كل طلب لا يحمل مفتاحًا صالحًا بالحالة 401 ونوع الخطأ authentication_error. أدِر مفاتيحك من لوحة المطوّرين، واحذف فورًا أي مفتاح تسرَّب.

الإصدارات (Versioning)

يُثبَّت الإصدار بتاريخه، فأرسِل الترويسة Wthaiq-Version بتاريخ الإصدار الذي بنيت عليه تكاملك، ليبقى سلوك الواجهة ثابتًا وإن أطلقنا تغييرات لاحقة. وإن لم تُرسل الترويسة، اعتُمِد أحدث إصدار مثبَّت على حسابك.

version.sh 
curl https://wthaiq.com/api/v1/templates \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
يصدر كل تغيير جذري (breaking change) بتاريخ جديد، ويُوثَّق في سجل التغييرات. أما الإضافات غير الجذرية (مثل الحقول الجديدة أو قيم enum الجديدة) فقد تظهر دون تغيير التاريخ، لذا صمِّم تكاملك ليتقبّل الحقول غير المتوقَّعة.

الأخطاء

تستخدم «وثائق» أكواد استجابة HTTP المتعارف عليها: النطاق 2xx يشير إلى النجاح، والنطاق 4xx يشير إلى خطأ في المُدخلات، والنطاق 5xx يشير إلى خطأ في خوادمنا. ويُعاد كل خطأ داخل مغلّف error موحَّد يتضمّن النوع والكود والرسالة، وفي الغالب اسم المُعامل المخالف ومعرّف الطلب.

error.json 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "المعامل signers مطلوب.",
    "param": "signers",
    "request_id": "req_9f2"
  }
}
أنواع الأخطاء وأكواد HTTP
النوعكود HTTPالمعنى
authentication_error401مفتاح مفقود أو غير صالح.
invalid_request_error400 / 404مُعامل ناقص أو غير صحيح، أو مورد غير موجود.
quota_error402تجاوز الحصّة، أو الحاجة إلى خطة أعلى.
permission_error403لا تسمح باقتك أو حالة حسابك بالعملية: توثيق الشركة مطلوب للطلب الحيّ، أو الخاصية خارج باقتك، أو عنوان IP غير مسموح به للمفتاح.
rate_limit_error429تجاوز عدد الطلبات الحدَّ المسموح به.
idempotency_error409تعارض في قيمة Idempotency-Key.
api_error5xxخطأ داخلي في خوادم «وثائق».
أكواد HTTP الأخرى: 200 نجاح · 201 أُنشئ · 403 ممنوع · النطاق 5xx خطأ خادم.
حقول إضافية في بعض الأخطاء
الحقلمع الرمزالمعنى
upgrade_urlplan_required · plan_expired · plan_feature_unavailableرابط صفحة الباقات في لوحة المطوّرين، لتختار باقة أو تجدّدها أو ترقّيها.
verify_urlkyb_requiredرابط صفحة «توثيق الشركة» في لوحة المطوّرين.
feature · required_planplan_feature_unavailableالخاصية المطلوبة، وأقلّ باقة تتيحها.
max_signerstoo_many_signersالحدّ الأقصى للموقّعين في الطلب الحيّ الواحد، وهو 5.
لغة الرسالة: يصدر نصّ الرسالة بالعربية افتراضيًّا، وبالإنجليزية في ثلاث حالات: رأس الطلب Accept-Language حين تبدأ قيمته بالحرفين en، أو المعامل ?lang=en، أو المسار /en/api/v1/… الذي يعمل كالمسار /api/v1/… تمامًا. ولا يتغيّر الرمز code بتغيّر اللغة، فابنِ منطق تكاملك عليه لا على نصّ الرسالة.

Idempotency

لتكون إعادة المحاولة آمنة في طلبات POST، أرسِل ترويسة Idempotency-Key تحمل قيمة UUID فريدة لكل عملية منطقية. فإذا وصل الطلب نفسه مرّتين (بسبب انقطاع الشبكة مثلًا)، أعدنا الاستجابة الأصلية بدلًا من إنشاء مورد مكرّر. وتُحفظ المفاتيح مدة 24 ساعة.

idempotency.sh 
curl -X POST https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f3c9c2e-8b1a-4c7d-9e21-2f0a6b3d1c44" \
  -d '{ "title": "عقد عمل — أحمد م." }'
إن أعدت استخدام المفتاح نفسه مع جسم طلب مختلف، تُعاد الحالة 409 ونوع الخطأ idempotency_error.
وإن وصل التكرار والطلب الأوّل ما زال قيد التنفيذ، تُعاد الحالة 409 بالرمز idempotency_in_progress مع الترويسة Retry-After؛ فأعد المحاولة بعد لحظات لتصلك الاستجابة الأصلية دون تنفيذ ثانٍ.

حدود المعدّل (Rate limits)

الحدّ 100 طلب لكل 10 ثوانٍ لكل حساب، وهو حدّ واحد يتشاركه وضعا التجربة والحيّ. وتحمل كل استجابة ترويسات تبيّن حصّتك المتبقّية، وعند تجاوز الحدّ تُعاد الحالة 429 مع الترويسة Retry-After التي تحدّد عدد الثواني الواجب انتظارها قبل إعادة المحاولة.

الترويسةالوصف
X-RateLimit-Limitالحدّ الأقصى لعدد الطلبات في النافذة الزمنية الحالية.
X-RateLimit-Remainingعدد الطلبات المتبقّية في النافذة الزمنية الحالية.
X-RateLimit-Resetالطابع الزمني (Unix) الذي تتجدّد عنده النافذة.
Retry-Afterيظهر مع الحالة 429، ويحدّد عدد الثواني الواجب انتظارها قبل إعادة المحاولة.
429.txt 
# HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1754000010
Retry-After: 4
الممارسة الموصى بها: عند تلقّي الحالة 429، أعِد المحاولة بفواصل زمنية تتزايد أُسّيًّا (exponential backoff)، والتزم بقيمة Retry-After.

معرّفات الطلب (Request IDs)

تحمل كل استجابة الترويسة Wthaiq-Request-Id بقيمة مسبوقة بـreq_، ويظهر المعرّف نفسه في الحقل request_id عند أي خطأ. احفظ هذا المعرّف في سجلّاتك؛ فهو ما نطلبه منك عند التواصل مع الدعم لنتتبّع الطلب بدقّة.

request-id.txt 
# HTTP/1.1 200 OK
Content-Type: application/json
Wthaiq-Request-Id: req_9f2a1c

مفاتيح التجربة والمفاتيح الحيّة

لكل مفتاح صيغتان: حيّة sk_ / pk_ وتجريبية sk_test_ / pk_test_، وتختار التجريبية عند إنشاء المفتاح بعلامة «مفتاح تجربة» في لوحة المطوّرين ← مفاتيح الربط. ويبيّن الحقل livemode في كل كائن وحدث أيَّ المفتاحين أنشأه.

الجانبالمفتاح الحيّمفتاح التجربة
الفوترةيُخصم إرسال كل طلب من رصيدكلا يُخصم شيء
الرسائلتُرسَل الدعوات والتذكيرات والنسخ فعلًاتصل الدعوة والتذكير بالبريد وعليهما علامة «تجربة»، ولا تُرسَل نسخ؛ ولا تُرسَل رسائل واتساب بل تُسجَّل في أحداث الطلب «كان سيُرسَل عبر واتساب إلى …»
الحدودبحسب الباقة، والخصائص بحسبهاكل الخصائص عدا الدومين الخاص؛ و20 طلبًا و50 رسالة بريد في اليوم لكل حساب، و5 موقّعين في الطلب، و10 مستلمين في الدفعة الجماعية
الموقّعونأي بريد أو رقمبريد حسابك أو رقمه، أو بريد أحد أعضاء فريقك أو رقمه، وحده
المستوى القانونيses · aes · qesالمستوى المطلوب نفسه، وتأكيد الهوية محاكاة يختار فيها الموقّع «اعتماد» أو «رفض» دون جلسة لدى المزوّد؛ والطلب كله بلا حجّية قانونية
محضر الأدلّةيُختم عند الاكتمال، ويصدر الحدثان document.sealed و verification.createdلا يُختم ولا يُطلب له ختم زمني، ولا يصدر الحدثان؛ ويعود من GET /signature_requests/{id}/evidence محضر تجريبي غير مختوم بالحقل test، وعلى الملف النهائي علامة مائية «تجريبي — بلا حجّية قانونية»
إشعارات الأحداثتصل إلى نقاط الاستقبال الحيّةتصل إلى نقاط الاستقبال المُنشأة بمفتاح تجربة عبر POST /v1/webhook_endpoints وحدها؛ فالنقاط المضافة من لوحة المطوّرين حيّة

وبين المفتاح السرّي والعام فرقٌ آخر في صلاحية الوصول:

الجانبsk_ (سرّي)pk_ (عام)
مكان الاستخدامعلى الخادم فقط، ولا يُكشف أبدًاآمن عند كشفه في المتصفّح
الصلاحياتكاملة على كل المواردمقصورة على القراءة في مسارات محدّدة (القوالب وطلبات التوقيع والموقّعين والتدفّقات)، إضافةً إلى إنشاء طلبات التوقيع فقط
قفل النطاقلا يوجدمُقيَّد بنطاقات allowed_origins التي تحدّدها — وهذا يقلّل المخاطر لكنه ليس مصادقة: فترويسة Origin يضعها المتصفّح، ويستطيع أي برنامج نصّي يعمل خارج المتصفّح انتحالها. والحماية الفعلية هي حدّ الإنفاق اليومي للمفتاح، وتدويره فور الاشتباه في كشفه.
السقف اليوميلا يوجدلكل مفتاح سقف يومي لعمليات الإنشاء والإرسال مهما تعدّدت العناوين. عند بلوغه تُعاد الحالة 429 بالرمز daily_cap_reached حتى بداية اليوم التالي (UTC)، ويصلك إشعار في لوحتك عند 80% من السقف وعند بلوغه.
المفتاح الحيّ حقيقي ومُفوتَر. كل موقّع في طلب تُرسله به يُحتسب إرسالًا من رصيد باقتك السنوي، والحدّ الأقصى خمسة موقّعين في الطلب، وبعد نفاده يُخصم من محفظتك بسعر الزيادة في باقتك. ويُخصم تأكيد الهوية من المحفظة لكل موقّع يتطلّبه: $1.50. ولا يُستردّ ما خُصم عن الطلب بعد إرساله، ولو أُلغي قبل أن يوقّعه أحد.
الطريقة الآمنة للتجربة: ابنِ تكاملك بمفتاح تجربة واجعل بريدك الموقّع، ثم انتقل إلى المفتاح الحيّ عند الإطلاق. واستخدم sk_ على خادمك فقط، و pk_ المُقيَّد بنطاقك في أي شيفرة تعمل داخل المتصفّح.

Metadata

تقبل معظم الكائنات القابلة للإنشاء الحقل metadata: خريطة نصّية من أزواج مفتاح/قيمة تحفظ فيها مراجعك الداخلية (مثل رقم طلب الشراء، أو معرّف المستخدم في نظامك، أو وسم الحملة). لا نستخدم هذه القيم داخليًّا، وتُعاد كما هي في كل استجابة وفي إشعارات الأحداث.

القيدالحدّ
عدد المفاتيححتى 50 مفتاحًا لكل كائن.
طول المفتاححتى 40 محرفًا.
طول القيمةحتى 500 محرف.
metadata.json 
{
  "metadata": {
    "order_id": "A-1024",
    "crm_contact": "cust_58231",
    "campaign": "q3-onboarding"
  }
}

Signature Requests

طلب التوقيع هو الكائن المركزي: يمثّل مستندًا (من قالب أو ملف مرفوع) يُرسَل إلى موقّع واحد أو أكثر بمستوى قانوني (assurance) محدّد، وتُتتبَّع حالة كل موقّع تتبّعًا كاملًا حتى الإتمام، وعندها يُختم الطلب بمحضر أدلّة موثّق قابل للتحقّق المستقلّ.

/v1/signature_requests
POST/v1/signature_requests

إنشاء طلب توقيع جديد يُحفظ مسودّةً أو يُرسَل فورًا إلى الموقّعين.

الحقلالنوعالإلزامالوصف
titlestringمطلوبعنوان الطلب الظاهر للموقّعين.
sourceobjectمطلوبمصدر المستند، وقيمة الحقل type إمّا template مع template_id، أو document مع document_id. ومصدر document (ملف PDF مرفوع) غير متاح بعد (قريبًا)، ويُرفض بالخطأ 400.
legal_levelstringمطلوبالمستوى القانوني: ses أو aes أو qes.
signersarrayمطلوبقائمة الموقّعين (انظر الحقول أدناه).
formatstringاختياريمستوى الضمان المطلوب، ويُسجَّل ويُعاد ضمن الكائن: pades-b / pades-t / pades-lt / pades-lta (الافتراضي pades-lt). لا يُصدر مسار واجهة برمجة التطبيقات حاليًا توقيع PAdES مضمَّنًا داخل ملف PDF؛ فالدليل التشفيري هو محضر الأدلّة المختوم (توقيع Ed25519 يتحقّق منه أي طرف بالمفتاح العام على /trust، وختم زمني RFC 3161).
orderedbooleanاختياريتوقيع تسلسلي بترتيب الموقّعين في المصفوفة signers (الافتراضي false).
require_identitybooleanاختياريفرض تأكيد الهوية على مستوى الطلب قبل التوقيع.
ccarrayاختياريمستلمو نسخة — يستلمون العقد الموقّع عند الاكتمال دون أن يوقّعوا (حتى 20). صيغة كل عنصر: { name, email }.
remindersobjectاختياري{ "enabled": true } يرسل حتى ثلاثة تذكيرات تلقائية للموقّع الذي حان دوره، قبل انتهاء المهلة بخمسة أيام ثم ثلاثة ثم يوم، للطلبات الحيّة المُرسَلة وحدها. ويُحفظ interval_hours و max ويُعادان كما أُرسلا دون أن يُستخدما. وتنتهي صلاحية الطلب بعد 7 أيام من إرساله.
sendbooleanاختياريإرسال الطلب فور إنشائه (الافتراضي true). وقيمة false تُنشئ مسودّة لا يعمل رابط توقيعها حتى ترسلها عبر POST /v1/signature_requests/{id}/send.
metadataobjectاختياريبيانات وصفية بصيغة مفتاح/قيمة.
signers[].namestringمطلوباسم الموقّع.
signers[].emailstringاختياري*البريد الإلكتروني للموقّع. * مطلوب ما لم يُرسَل phone.
signers[].phonestringاختياري*رقم واتساب الموقّع (يُطبَّع تلقائيًّا إلى الصيغة الدولية، مثال 201012345678). إن أُرسل مع البريد وصلت الدعوة بالقناتين. وإرساله وحده لا يُقبل إلا حين يكون إيصال رمز التحقّق عبر واتساب مفعَّلًا، وإلّا رُدّ الطلب بـ400 — كي لا يقف الموقّع أمام رمز لا سبيل لإيصاله إليه.
signers[].methodstringاختياريdraw (توقيع مرسوم + رمز تحقّق) أو token (شهادة QES على توكن مادي).
signers[].require_identitybooleanاختياريفرض تأكيد الهوية على هذا الموقّع تحديدًا (AES).
signers[].fieldsobjectاختياريقيم حقول القالب المعبّأة مسبقًا.
cURLNode
request.sh 
curl -X POST https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f3c9c2e-..." \
  -d '{
    "title": "عقد عمل — أحمد م.",
    "source": { "type": "template", "template_id": "tpl_employment" },
    "legal_level": "aes",
    "ordered": true,
    "signers": [
      { "name": "أحمد محمد", "email": "ahmed@example.com", "type": "individual",
        "method": "draw", "require_identity": true,
        "fields": { "job_title": "مهندس برمجيات", "salary": "25000" } }
    ],
    "reminders": { "enabled": true, "interval_hours": 48, "max": 3 },
    "metadata": { "order_id": "A-1024" }
  }'
create.js 
import Wthaiq from 'wthaiq';
const wt = new Wthaiq('sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

const sr = await wt.signatureRequests.create({
  title: 'عقد عمل — أحمد م.',
  source: { type: 'template', template_id: 'tpl_employment' },
  legal_level: 'aes',
  ordered: true,
  signers: [
    { name: 'أحمد محمد', email: 'ahmed@example.com', method: 'draw', require_identity: true }
  ]
});
الاستجابة · 201 Created
signature_request.json 
{
  "id": "sr_3n8Kd2Qa1V",
  "object": "signature_request",
  "livemode": true,
  "status": "sent",
  "title": "عقد عمل — أحمد م.",
  "legal_level": "aes",
  "format": "pades-lt",
  "source": { "type": "template", "template_id": "tpl_employment" },
  "signers": [
    {
      "id": "sgr_9fA2",
      "object": "signer",
      "name": "أحمد محمد",
      "email": "ahmed@example.com",
      "type": "individual",
      "method": "draw",
      "require_identity": true,
      "order": 1,
      "status": "sent",
      "signing_url": "https://wthaiq.com/sign.php?token=uZ8..",
      "viewed_at": null,
      "signed_at": null,
      "identity": { "status": "required", "provider": "external", "level": "aes" },
      "fields": { "job_title": "مهندس برمجيات", "start_date": "2026-08-01" }
    }
  ],
  "ordered": true,
  "require_identity": true,
  "reference": null,
  "reminders": { "enabled": true, "interval_hours": 48, "max": 3 },
  "expires_at": 1755000000,
  "completed_at": null,
  "download_url": null,
  "metadata": { "order_id": "A-1024" },
  "created_at": 1754000000
}
POST/v1/signature_requests/bulk

إرسال جماعي: يُرسَل العقد نفسه إلى عدّة موقّعين دفعةً واحدة، ويُنشأ طلب توقيع مستقل لكل موقّع (حتى 200)، ويُتحقَّق من كفاية الرصيد للدفعة كاملةً قبل بدء الإرسال. ويُتحقَّق كذلك من بيانات كل الموقّعين قبل إنشاء أي طلب؛ فإن أخطأ أحدها رُدّت الدفعة كلّها بالخطأ 400 مع موضعه في الحقل param، ولا يُنشأ منها شيء.

المُعاملالنوعالإلزامالوصف
sourceobjectمطلوبمصدر العقد، مثل { "type": "template", "template_id": "tpl_..." }.
recipientsarrayمطلوبقائمة الموقّعين، وصيغة كل عنصر: { name, email }.
fieldsobjectاختياريقيم الحقول المشتركة بين جميع العقود.
legal_levelstringاختياريses أو aes أو qes.
ccarrayاختياريمستلمو نسخة من كل عقد.
terminal
curl -X POST https://wthaiq.com/api/v1/signature_requests/bulk \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "template", "template_id": "tpl_265" },
    "recipients": [
      { "name": "محمد سالم", "email": "m1@example.com" },
      { "name": "سارة أحمد", "email": "s2@example.com" }
    ],
    "fields": { "amount": "5000" },
    "legal_level": "ses"
  }'
الاستجابة
{
  "object": "bulk_send",
  "created": 2,
  "failed": 0,
  "requests": [
    { "signature_request": "sr_3n8Kd2Qa1V", "email": "m1@example.com", "status": "sent" },
    { "signature_request": "sr_9Kx2Ld7Pq3", "email": "s2@example.com", "status": "sent" }
  ],
  "errors": []
}
GET/v1/signature_requests

سرد طلبات التوقيع مع ترقيم الصفحات بالمؤشّر، وإمكانية التصفية حسب الحالة والتاريخ (created_after / created_before).

المُعاملالنوعالإلزامالوصف
limitintegerاختياريمن 1 إلى 100 (الافتراضي 20).
starting_afterstringاختياريمؤشّر الصفحة التالية.
statusstringاختياريالتصفية حسب الحالة: draft, sent, completed ...
cURLNode
list.sh 
curl "https://wthaiq.com/api/v1/signature_requests?limit=3&status=sent" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
list.js 
const list = await wt.signatureRequests.list({ limit: 3, status: 'sent' });
الاستجابة · 200 OK
list.json 
{
  "object": "list",
  "data": [
    {
      "id": "sr_3n8Kd2Qa1V",
      "object": "signature_request",
      "livemode": true,
      "status": "sent",
      "title": "عقد عمل — أحمد م.",
      "legal_level": "aes",
      "format": "pades-lt",
      "created_at": 1754000000
    }
  ],
  "has_more": true,
  "next_cursor": "sr_2m7Xa9"
}
GET/v1/signature_requests/{id}

استرجاع طلب توقيع بمعرّفه، مع قائمة موقّعيه وحالة كلٍّ منهم.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع (sr_).
cURLNode
retrieve.sh 
curl https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
retrieve.js 
const sr = await wt.signatureRequests.retrieve('sr_3n8Kd2Qa1V');
الاستجابة · 200 OK
signature_request.json 
{
  "id": "sr_3n8Kd2Qa1V",
  "object": "signature_request",
  "livemode": true,
  "status": "partially_signed",
  "title": "عقد عمل — أحمد م.",
  "legal_level": "aes",
  "format": "pades-lt",
  "source": { "type": "template", "template_id": "tpl_employment" },
  "ordered": true,
  "require_identity": true,
  "reference": null,
  "expires_at": 1755000000,
  "completed_at": null,
  "download_url": null,
  "metadata": { "order_id": "A-1024" },
  "created_at": 1754000000
}
POST/v1/signature_requests/{id}/send

إرسال طلب في حالة المسودّة (draft) إلى موقّعيه.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع.
send.sh 
curl -X POST https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/send \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
signature_request.json 
{
  "id": "sr_3n8Kd2Qa1V",
  "object": "signature_request",
  "status": "sent",
  "created_at": 1754000000
}
POST/v1/signature_requests/{id}/cancel

إلغاء طلب توقيع لم يكتمل بعد، فتصبح حالته canceled. والطلب المكتمل أو المُلغى سلفًا يُرفض بالحالة 409 والرمز request_not_cancelable. ولا يُستردّ ما خُصم عن الطلب بعد إرساله، ولو أُلغي قبل أن يوقّعه أحد.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع.
cancel.sh 
curl -X POST https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/cancel \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
signature_request.json 
{
  "id": "sr_3n8Kd2Qa1V",
  "object": "signature_request",
  "status": "canceled",
  "completed_at": null,
  "created_at": 1754000000
}
POST/v1/signature_requests/{id}/reminders

إرسال تذكير فوري إلى الموقّعين الذين يُنتظَر توقيعهم في هذا الطلب. والطلب المسودّة أو المُلغى يُرفض بالحالة 400.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع.
reminders.sh 
curl -X POST https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/reminders \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
reminder.json 
{
  "object": "reminder",
  "signature_request": "sr_3n8Kd2Qa1V",
  "reminders_sent": 1
}
GET/v1/signature_requests/{id}/download

يُرجع بيانات العقد الموقّع بصيغة JSON بعد اكتمال الطلب: pdf_url رابط ملف PDF النهائي (نصّ العقد المجمَّد مع شهادة التحقّق بمرجعها ورمز QR)، و pdf_status حالته: ready أو pending أو unavailable، و pdf_sha256 بصمته، و final_document_url صفحة الوثيقة النهائية، و reference مرجع التحقّق. ويُنزَّل الملف نفسه عبر GET /v1/signature_requests/{id}/download/pdf بمفتاح سرّي، وفي الوضع الحيّ يصل رابطه إلى كل الموقّعين والمُرسِل بالبريد عند الاكتمال. والدليل التشفيري المستقل هو محضر الأدلّة عبر GET /v1/signature_requests/{id}/evidence.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع المكتمل.
download.sh 
curl https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/download \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
download.json 
{
  "object": "download",
  "signature_request": "sr_3n8Kd2Qa1V",
  "pdf_url": "https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/download/pdf",
  "pdf_status": "ready",
  "pdf_sha256": "455e49ec8a9975bb6ba5500fffb0d3af1a364ab2a1b1c1335020b17aef8316ef",
  "pdf_bytes": 100993,
  "pdf_generated_at": 1791021338,
  "final_document_url": "https://wthaiq.com/final/9c1e..",
  "reference": "WTQ-1A2B3C4D5E6F",
  "format": "pades-lt",
  "legal_level": "aes"
}
إن كان الطلب غير مكتمل، تُعاد حالة 400 ونوع خطأ invalid_request_error.
GET/v1/signature_requests/{id}/certificate

بيانات شهادة الإتمام مع سجلّ التدقيق بصيغة JSON.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع.
certificate.sh 
curl https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/certificate \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
certificate.json 
{
  "object": "certificate",
  "signature_request": "sr_3n8Kd2Qa1V",
  "status": "completed",
  "reference": "WTQ-1A2B3C4D5E6F",
  "legal_level": "aes",
  "format": "pades-lt",
  "completed_at": 1754500000,
  "signers": [
    { "name": "أحمد محمد", "email": "ahmed@example.com", "phone": null, "status": "signed", "signed_at": 1754500000 }
  ],
  "audit_trail": [
    { "event": "sent", "actor": "owner", "ip": "203.0.113.7", "at": 1754000000 },
    { "event": "signed", "actor": "signer", "ip": "198.51.100.4", "at": 1754500000 }
  ],
  "verify_url": "https://wthaiq.com/verify?c=WTQ-1A2B3C4D5E6F"
}
GET/v1/signature_requests/{id}/evidence

محضر الأدلّة المختوم للطلب المكتمل، للتحقّق المستقلّ منه: النصّ المعياري للمحضر record_raw وتوقيع Ed25519 عليه والمفتاح العام والختم الزمني RFC 3161. يتطلّب مفتاحًا سرّيًا sk_، ويُرجع 404 ما لم يُختم المحضر؛ وطلبات التجربة لا يُختم لها محضر.

evidence.sh
curl https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/evidence \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
evidence.json
{
  "object": "evidence",
  "signature_request": "sr_3n8Kd2Qa1V",
  "format": "wthaiq-evidence-v1",
  "verify_ref": "WTQ-1A2B3C4D5E6F",
  "record_raw": "{\"document\":{..}}",
  "seal": {
    "signature_alg": "ed25519",
    "signature": "b64..",
    "public_key": "b64..",
    "trust_url": "https://wthaiq.com/trust",
    "timestamp_token": "b64.."
  }
}
GET/v1/signature_requests/{id}/events

سجلّ التدقيق الزمني لهذا الطلب، بكل أحداثه من الفتح حتى التوقيع.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف طلب التوقيع.
limitinteger · queryاختياريمن 1 إلى 100 (الافتراضي 20).
events.sh 
curl https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/events \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
events.json 
{
  "object": "list",
  "data": [
    {
      "id": "evt_2M",
      "object": "event",
      "type": "signer.signed",
      "signature_request": "sr_3n8Kd2Qa1V",
      "signer": "sgr_9fA2",
      "actor": "signer",
      "ip": "197.44.x.x",
      "user_agent": "..",
      "created_at": 1754500000
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Signers

يمثّل الموقّع طرفًا في طلب التوقيع، وله حالته الخاصة وطريقة توقيعه ونتيجة تأكيد هويته. يُنشَأ تلقائيًا مع إنشاء الطلب، ويمكن استرجاعه أو إنشاء جلسة توقيع مدمجة له.

/v1/signers
GET/v1/signers/{id}

استرجاع موقّع بمعرّفه.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف الموقّع (sgr_).
retrieve.sh 
curl https://wthaiq.com/api/v1/signers/sgr_9fA2 \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
signer.json 
{
  "id": "sgr_9fA2",
  "object": "signer",
  "name": "أحمد محمد",
  "email": "ahmed@example.com",
  "type": "individual",
  "method": "draw",
  "require_identity": true,
  "order": 1,
  "status": "identity_verified",
  "signing_url": "https://wthaiq.com/sign.php?token=uZ8..",
  "viewed_at": 1754000100,
  "signed_at": null,
  "identity": { "status": "approved", "provider": "external", "level": "aes" },
  "fields": { "job_title": "مهندس برمجيات", "start_date": "2026-08-01" }
}
POST/v1/signers/{id}/signing_session

إنشاء رابط توقيع مدمج صالح 30 دقيقة، لعرض صفحة التوقيع داخل تطبيقك بعلامتك التجارية (white-label). ولا يُنشأ لطلب مسودّة أو مُلغى.

الحقلالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف الموقّع.
return_urlstringاختياريرابط https كامل على دومين مقبول في حسابك، يُعاد إليه الموقّع بعد إتمام التوقيع، ومتاح في باقة «الأعمال» فأعلى. وصلاحية الجلسة ثابتة: 30 دقيقة.
modestringاختياريiframe (الافتراضي) للتضمين في إطار داخل صفحة على دومين مقبول في حسابك، أو redirect لتحويل المتصفّح إلى صفحة التوقيع ثم إعادته إلى success_url أو cancel_url. ولا يُرسَل return_url مع نمط redirect.
success_urlstringمطلوب مع redirectرابط https على دومين مقبول في حسابك (حتى 500 حرف، بلا اسم مستخدم ولا #)، يُحوَّل إليه الموقّع بعد أن يوقّع ومعه session_id (معرّف الطلب) و signer_id و status=completed. ويُستبدل {signature_request} و{signer} في الرابط بمعرّفي الطلب والموقّع.
cancel_urlstringاختياريمثل success_url، ويُحوَّل إليه الموقّع إن رفض التوقيع ومعه status=declined. وإن لم يُرسَل بقي الموقّع في صفحة التوقيع بعد الرفض. واعتمد النتيجة من الإشعار الموقَّع، لا من العودة.
signing_session.sh 
curl -X POST https://wthaiq.com/api/v1/signers/sgr_9fA2/signing_session \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://app.acme.com/done" }'
الاستجابة · 201 Created
signing_session.json 
{
  "object": "signing_session",
  "signer": "sgr_9fA2",
  "signing_url": "https://wthaiq.com/embed/sign/9Qa1V..",
  "expires_at": 1754001800
}

Documents

يمثّل المستند ملف PDF مرفوعًا يُحفظ في حسابك مع بصمته الرقمية (SHA-256) وعدد صفحاته وحجمه. واستخدامه مصدرًا لطلبات التوقيع عبر الواجهة البرمجية غير متاح بعد (قريبًا).

/v1/documents
POST/v1/documents

رفع ملف PDF عبر multipart/form-data وحفظه في حسابك، ويُحتسب ضمن حدّ العقود في باقتك. ولا يُقبل بعدُ مصدرًا لطلب توقيع؛ فالطلب الذي يشير إليه يُرفض بالخطأ 400 إلى أن يتاح (قريبًا).

الحقلالنوعالإلزامالوصف
filefileمطلوبملف PDF (حقل ضمن نموذج متعدّد الأجزاء).
kindstringاختيارينوع المستند: pdf (الافتراضي) أو contract.
field_mapstring (JSON)اختياريخريطة حقول بالإحداثيات تُطبَع بموجبها القيم في مواضعها على الصفحات. الإحداثيات نسبية (0..1) وتُقاس من أعلى يسار الصفحة.
خريطة الحقول (field_map): مصفوفة عناصر بالصيغة { "key", "label", "type", "page", "x", "y", "w", "h", "required" }. تُحفظ الخريطة مع المستند وتُعاد في الحقل fields، ولا تُطبع قيمها على الملف بعد (قريبًا).
upload.sh 
curl -X POST https://wthaiq.com/api/v1/documents \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -F "file=@agreement.pdf" \
  -F "kind=pdf" \
  -F 'field_map=[
    {"key":"signer_name","label":"اسم الموقّع","type":"text",
     "page":1,"x":0.12,"y":0.34,"w":0.30,"h":0.04,"required":true},
    {"key":"contract_date","label":"التاريخ","type":"date",
     "page":1,"x":0.62,"y":0.34,"w":0.22,"h":0.04}
  ]'
الاستجابة · 201 Created
document.json 
{
  "id": "doc_7Yq",
  "object": "document",
  "kind": "pdf",
  "filename": "agreement.pdf",
  "pages": 4,
  "bytes": 183221,
  "sha256": "a3f1..",
  "created_at": 1754000000
}

Templates

القوالب هي العقود المحفوظة في حسابك بحقولها القابلة للتعبئة. تُشير إليها طلبات التوقيع عبر source.template_id.

/v1/templates
GET/v1/templates

سرد القوالب المحفوظة في حسابك.

المُعاملالنوعالإلزامالوصف
limitinteger · queryاختياريمن 1 إلى 100 (الافتراضي 20).
categorystring · queryاختياريالتصفية حسب الفئة، مثل hr.
starting_afterstring · queryاختياريمؤشّر الصفحة التالية.
cURLNode
list.sh 
curl "https://wthaiq.com/api/v1/templates?category=hr" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
list.js 
const tpls = await wt.templates.list({ category: 'hr' });
الاستجابة · 200 OK
list.json 
{
  "object": "list",
  "data": [
    {
      "id": "tpl_employment",
      "object": "template",
      "name": "عقد عمل",
      "category": "hr",
      "languages": ["ar"],
      "created_at": 1754000000
    }
  ],
  "has_more": false,
  "next_cursor": null
}
GET/v1/templates/{id}

استرجاع قالب مع تعريف حقوله القابلة للتعبئة.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف القالب (tpl_).
cURLNode
retrieve.sh 
curl https://wthaiq.com/api/v1/templates/tpl_employment \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
retrieve.js 
const tpl = await wt.templates.retrieve('tpl_employment');
الاستجابة · 200 OK
template.json 
{
  "id": "tpl_employment",
  "object": "template",
  "name": "عقد عمل",
  "category": "hr",
  "languages": ["ar"],
  "fields": [
    { "key": "job_title", "label": "المسمى الوظيفي", "type": "text", "required": true },
    { "key": "salary", "label": "الراتب", "type": "number", "required": true }
  ],
  "created_at": 1754000000
}

Identity Verifications

يربط تأكيد الهوية توقيع الموقّع بشخص حقيقي جرى التحقّق منه عبر مزوّد متخصّص في التحقّق من الهوية (بمستند رسمي ومطابقة حيّة للوجه)، وهو شرط المستوى المتقدّم (AES).

/v1/identity_verifications
GET/v1/identity_verifications/{id}

استرجاع عملية تأكيد هوية بمعرّفها.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف تأكيد الهوية (idv_).
retrieve.sh 
curl https://wthaiq.com/api/v1/identity_verifications/idv_5k \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
identity_verification.json 
{
  "id": "idv_5k",
  "object": "identity_verification",
  "provider": "external",
  "signer": "sgr_9fA2",
  "status": "approved",
  "level": "aes",
  "verification_url": "https://verify.wthaiq.com/u/..",
  "created_at": 1754000000
}

Verifications

التحقّق العلني من سلامة مستند موقّع عبر مرجعه العام (WTQ- / WTH-)، دون كشف بيانات الأطراف كاملةً، وذلك بمقارنة البصمة الحالية للمستند ببصمته المختومة.

/v1/verifications
GET/v1/verifications/{reference}

التحقّق العلني من مستند عبر مرجعه.

المُعاملالنوعالإلزامالوصف
referencestring · pathمطلوبالمرجع العام، مثل WTQ-1A2B3C4D5E6F.
verify.sh 
curl https://wthaiq.com/api/v1/verifications/WTQ-1A2B3C4D5E6F \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
verification.json 
{
  "object": "verification",
  "reference": "WTQ-1A2B3C4D5E6F",
  "found": true,
  "status": "completed",
  "integrity": "intact",
  "document": {
    "title": "عقد عمل",
    "sha256": "a3f1..",
    "hash_alg": "hmac-sha256",
    "format": "platform-evidence",
    "legal_level": "aes"
  },
  "signed_at": 1754500000,
  "parties": [
    { "name": "أ**** م****", "role": "signer" },
    { "name": "ش**** و****", "role": "owner" }
  ],
  "qr": "https://wthaiq.com/verify?c=WTQ-1A2B3C4D5E6F"
}

Events

الحدث كائن غير قابل للتعديل، يمثّل قيدًا في سجلّ التدقيق ويعكس تغيّرًا في أحد الموارد. وهذه الأحداث نفسها هي ما تحمله إشعارات الأحداث الآلية، ويمكن سردها واسترجاعها لاحقًا.

/v1/events
GET/v1/events

سرد أحداث الحساب، مع إمكانية التصفية حسب النوع.

المُعاملالنوعالإلزامالوصف
limitinteger · queryاختياريمن 1 إلى 100 (الافتراضي 20).
typestring · queryاختياريالتصفية حسب نوع الحدث، مثل signer.signed.
starting_afterstring · queryاختياريمؤشّر الصفحة التالية.
list.sh 
curl "https://wthaiq.com/api/v1/events?limit=10&type=signer.signed" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
list.json 
{
  "object": "list",
  "data": [
    {
      "id": "evt_2M",
      "object": "event",
      "type": "signer.signed",
      "signature_request": "sr_3n8Kd2Qa1V",
      "signer": "sgr_9fA2",
      "actor": "signer",
      "ip": "197.44.x.x",
      "user_agent": "..",
      "created_at": 1754500000
    }
  ],
  "has_more": true,
  "next_cursor": "evt_1L"
}
GET/v1/events/{id}

استرجاع حدث واحد بمعرّفه.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف الحدث (evt_).
retrieve.sh 
curl https://wthaiq.com/api/v1/events/evt_2M \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
event.json 
{
  "id": "evt_2M",
  "object": "event",
  "type": "signer.signed",
  "signature_request": "sr_3n8Kd2Qa1V",
  "signer": "sgr_9fA2",
  "actor": "signer",
  "ip": "197.44.x.x",
  "user_agent": "..",
  "created_at": 1754500000
}
POST/v1/events/{id}/redeliver

إعادة إرسال إشعار حدث سابق بحمولته نفسها ومعرّفه نفسه، موقَّعًا بسرّ الوجهة الحالي. تُنشأ عملية تسليم جديدة تُحاوَل فورًا، وتتبع جدول إعادة المحاولة المعتاد إن لم يردّ خادمك برمز 2xx. والحدّ: خمس مرات للحدث الواحد وثلاثون للحساب كل عشر دقائق، ثم 429.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف الحدث (evt_).
endpointstringاختياريمعرّف وجهة مفعّلة (we_) لإعادة الإرسال إليها وحدها. وبدونه يُعاد الإرسال إلى كل وجهة مفعّلة مشتركة في نوع الحدث.
redeliver.sh 
curl -X POST https://wthaiq.com/api/v1/events/evt_2M/redeliver \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "we_8Hk2" }'
الاستجابة · 200 OK
event_redelivery.json 
{
  "object": "event_redelivery",
  "event": "evt_2M",
  "deliveries": [
    { "endpoint": "we_8Hk2", "status": "succeeded", "response_code": 200, "error": null }
  ]
}

Webhook Endpoints

تُسجِّل نقطة استقبال الإشعارات رابطًا (URL) يتلقّى إشعارات لحظية بالأحداث التي تشترك فيها. راجع دليل إشعارات الأحداث الآلية لمعرفة طريقة التحقّق من توقيع الإشعار وآلية إعادة المحاولة.

/v1/webhook_endpoints
POST/v1/webhook_endpoints

إنشاء نقطة استقبال إشعارات جديدة. تُعاد قيمة السرّ whsec_ مرّة واحدة عند الإنشاء.

الحقلالنوعالإلزامالوصف
urlstringمطلوبعنوان HTTPS الذي يستقبل رسائل POST.
enabled_eventsarrayمطلوبأنواع الأحداث المشترَك فيها، مثل signature_request.completed.
cURLNode
create.sh 
curl -X POST https://wthaiq.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/hooks/wthaiq",
    "enabled_events": ["signature_request.completed", "signer.signed"]
  }'
create.js 
const we = await wt.webhookEndpoints.create({
  url: 'https://api.acme.com/hooks/wthaiq',
  enabled_events: ['signature_request.completed', 'signer.signed']
});
الاستجابة · 201 Created
webhook_endpoint.json 
{
  "id": "we_1a",
  "object": "webhook_endpoint",
  "url": "https://api.acme.com/hooks/wthaiq",
  "enabled_events": ["signature_request.completed", "signer.signed"],
  "status": "enabled",
  "secret": "whsec_..",
  "created_at": 1754000000
}
GET/v1/webhook_endpoints

سرد نقاط استقبال الإشعارات المسجّلة.

المُعاملالنوعالإلزامالوصف
limitinteger · queryاختياريمن 1 إلى 100 (الافتراضي 20).
list.sh 
curl https://wthaiq.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
list.json 
{
  "object": "list",
  "data": [
    {
      "id": "we_1a",
      "object": "webhook_endpoint",
      "url": "https://api.acme.com/hooks/wthaiq",
      "enabled_events": ["signature_request.completed", "signer.signed"],
      "status": "enabled",
      "created_at": 1754000000
    }
  ],
  "has_more": false,
  "next_cursor": null
}
GET/v1/webhook_endpoints/{id}

استرجاع نقطة استقبال إشعارات بمعرّفها.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف نقطة استقبال الإشعارات (we_).
retrieve.sh 
curl https://wthaiq.com/api/v1/webhook_endpoints/we_1a \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
webhook_endpoint.json 
{
  "id": "we_1a",
  "object": "webhook_endpoint",
  "url": "https://api.acme.com/hooks/wthaiq",
  "enabled_events": ["signature_request.completed", "signer.signed"],
  "status": "enabled",
  "secret": "whsec_..",
  "created_at": 1754000000
}
DELETE/v1/webhook_endpoints/{id}

حذف نقطة استقبال إشعارات، فيتوقّف إرسال الأحداث إليها فورًا.

المُعاملالنوعالإلزامالوصف
idstring · pathمطلوبمعرّف نقطة استقبال الإشعارات.
delete.sh 
curl -X DELETE https://wthaiq.com/api/v1/webhook_endpoints/we_1a \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الاستجابة · 200 OK
deleted.json 
{
  "id": "we_1a",
  "object": "webhook_endpoint",
  "deleted": true
}
signature_request

الكائن المركزي الذي يمثّل طلب التوقيع.

signature_request 
{
  "id": "sr_3n8Kd2Qa1V",
  "object": "signature_request",
  "livemode": true,
  "status": "sent",
  "title": "عقد عمل — أحمد م.",
  "legal_level": "aes",
  "format": "pades-lt",
  "source": { "type": "template", "template_id": "tpl_employment" },
  "signers": [ ],
  "ordered": true,
  "require_identity": true,
  "reference": null,
  "reminders": { "enabled": true, "interval_hours": 48, "max": 3 },
  "expires_at": 1755000000,
  "completed_at": null,
  "download_url": null,
  "metadata": { "order_id": "A-1024" },
  "created_at": 1754000000
}
الحقلالنوعالوصف
idstringمعرّف الطلب.
statusstringdraft · sent · partially_signed · completed · declined · expired · canceled.
legal_levelstringses · aes · qes.
formatstringمستوى الضمان المطلوب المسجَّل على الكائن (pades-b / t / lt / lta). لا يُصدر مسار الـAPI توقيع PAdES مضمّنًا داخل الـPDF؛ الإثبات هو محضر الأدلّة المختوم القابل للتحقّق المستقل.
sourceobjectمصدر المستند (قالب أو مستند مرفوع).
signersarrayكائنات الموقّعين.
orderedbooleanتوقيع تسلسلي.
require_identitybooleanتأكيد الهوية قبل التوقيع (AES).
referencestring · nullمرجع التحقّق العامّ (WTQ-XXXXXXXXXXXX)، ويصدر عند الإتمام.
download_urlstring · nullرابط الملف الموقّع بصيغة PDF، ويظهر عند الإتمام.
created_atintegerوقت الإنشاء (طابع زمني بصيغة Unix).
signer

طرف يوقّع ضمن طلب توقيع.

signer 
{
  "id": "sgr_9fA2",
  "object": "signer",
  "name": "أحمد محمد",
  "email": "ahmed@example.com",
  "type": "individual",
  "method": "draw",
  "require_identity": true,
  "order": 1,
  "status": "identity_verified",
  "signing_url": "https://wthaiq.com/sign.php?token=uZ8..",
  "viewed_at": 1754000100,
  "signed_at": null,
  "identity": { "status": "approved", "provider": "external", "level": "aes" },
  "fields": { "job_title": "مهندس برمجيات", "start_date": "2026-08-01" }
}
الحقلالنوعالوصف
typestringindividual أو company.
methodstringdraw (توقيع مرسوم + رمز تحقّق عبر البريد الإلكتروني) أو token (شهادة QES على توكن مادي).
statusstringpending · sent · viewed · otp_verified · identity_verified · signed · declined.
signing_urlstringرابط صفحة التوقيع المستضافة أو القابلة للتضمين.
identityobjectنتيجة تأكيد الهوية عند تفعيله عبر require_identity.
identity.statusstringnone · required · in_review · resubmission_requested · declined · approved. تتغيّر القيمة مع أحداث signer.identity_*.
identity.verification_idstringمعرّف أحدث عملية تأكيد هوية للموقّع (idv_)، أو null قبل أن تبدأ.
identity.reason_codestringسبب عامّ مصنَّف عند الرفض، بلا بيانات شخصية: reviewer_decision · face_mismatch · face_unclear · document_expired · document_unreadable · document_not_original · document_not_supported · not_accepted.
identity.resubmit_stepsarrayالخطوات المطلوب إعادتها عند طلب الإعادة: document · liveness.
identity.updated_atintegerوقت آخر تغيّر في حالة تأكيد الهوية.
fieldsobjectقيم حقول القالب المعبّأة مسبقًا.
document

ملف PDF مرفوع.

document 
{
  "id": "doc_7Yq",
  "object": "document",
  "kind": "pdf",
  "filename": "agreement.pdf",
  "pages": 4,
  "bytes": 183221,
  "sha256": "a3f1..",
  "created_at": 1754000000
}
الحقلالنوعالوصف
kindstringpdf أو contract.
pagesintegerعدد الصفحات.
bytesintegerحجم الملف بالبايت.
sha256stringالبصمة الرقمية للمستند (SHA-256).
template

عقد جاهز بحقول قابلة للتعبئة.

template 
{
  "id": "tpl_employment",
  "object": "template",
  "name": "عقد عمل",
  "category": "hr",
  "languages": ["ar"],
  "fields": [
    { "key": "job_title", "label": "المسمى الوظيفي", "type": "text", "required": true },
    { "key": "salary", "label": "الراتب", "type": "number", "required": true }
  ],
  "created_at": 1754000000
}
الحقلالنوعالوصف
namestringاسم القالب.
categorystringفئة القالب، مثل hr.
languagesarrayلغات القالب المتاحة.
fieldsarrayتعريف الحقول: key, label, type, required.
identity_verification

نتيجة تأكيد هوية الموقّع عبر مزوّد متخصّص في التحقّق من الهوية.

identity_verification 
{
  "id": "idv_5k",
  "object": "identity_verification",
  "provider": "external",
  "signer": "sgr_9fA2",
  "status": "approved",
  "level": "aes",
  "verification_url": "https://verify.wthaiq.com/u/..",
  "created_at": 1754000000
}
الحقلالنوعالوصف
providerstringمزوّد التحقّق (external).
signerstringمعرّف الموقّع المرتبط.
statusstringpending · in_review · resubmission_requested · approved · declined · expired.
levelstringالمستوى القانوني المستهدف.
verification

نتيجة التحقّق العلني من سلامة مستند عبر مرجعه.

verification 
{
  "object": "verification",
  "reference": "WTQ-1A2B3C4D5E6F",
  "found": true,
  "status": "completed",
  "integrity": "intact",
  "document": {
    "title": "عقد عمل",
    "sha256": "a3f1..",
    "hash_alg": "hmac-sha256",
    "format": "platform-evidence",
    "legal_level": "aes"
  },
  "signed_at": 1754500000,
  "parties": [
    { "name": "أ**** م****", "role": "signer" },
    { "name": "ش**** و****", "role": "owner" }
  ],
  "qr": "https://wthaiq.com/verify?c=WTQ-1A2B3C4D5E6F"
}
الحقلالنوعالوصف
referencestringالمرجع العام (WTQ-/WTH-).
foundbooleanيبيّن ما إذا عُثر على المستند.
integritystringintact قُورن فطابق · modified قُورن فاختلف · recorded البصمة مسجَّلة ولم يكن الملفّ متاحًا للمقارنة · unknown لا بصمة مسجَّلة.
structurestringالالتزام البنيويّ — يغطّي الوسوم والسمات والتنسيق والصور، وهو ما لا تغطّيه بصمة النصّ: match · changed · absent لتوقيع سابق لهذا الالتزام.
document.sha256stringبصمة الوثيقة المسجّلة لحظة الختم، وخوارزميتها في الحقل hash_alg.
document.hash_algstringhmac-sha256 في مراجع WTQ-: بصمة نصّ الوثيقة بمفتاح سرّي لدى المنصّة، فلا تساوي تجزئة ملف PDF المنزَّل ولا يعيد حسابها طرف خارجي، وتُطابَق عبر صفحة التحقّق. · sha256 في مراجع WTH-: تجزئة الملف النهائي نفسه، ويعيد حسابها أي طرف.
document.formatstringمستوى توقيع PAdES المضمَّن فعلًا في الملف حين يوقّع الطرف بالتوكن: pades-b · pades-t · pades-lt · pades-lta. وفي غير ذلك platform-evidence: محضر أدلّة مختوم بالوقت، بلا توقيع مضمَّن في الملف.
partiesarrayالأطراف بأسماء محجوبة جزئيًا.
qrstringرابط صفحة التحقّق العلني.
event

قيد غير قابل للتعديل في سجلّ التدقيق.

event 
{
  "id": "evt_2M",
  "object": "event",
  "type": "signer.signed",
  "signature_request": "sr_3n8Kd2Qa1V",
  "signer": "sgr_9fA2",
  "actor": "signer",
  "ip": "197.44.x.x",
  "user_agent": "..",
  "created_at": 1754500000
}
الحقلالنوعالوصف
typestringنوع الحدث، مثل signer.signed.
actorstringowner · signer · system.
ipstringعنوان IP لمنفّذ الإجراء.
user_agentstringوكيل المستخدم (User-Agent) لمنفّذ الإجراء.
webhook_endpoint

رابط مسجَّل لتلقّي إشعارات الأحداث.

webhook_endpoint 
{
  "id": "we_1a",
  "object": "webhook_endpoint",
  "url": "https://api.acme.com/hooks/wthaiq",
  "enabled_events": ["signature_request.completed", "signer.signed"],
  "status": "enabled",
  "secret": "whsec_..",
  "created_at": 1754000000
}
الحقلالنوعالوصف
urlstringعنوان HTTPS الذي يستقبل الإشعارات.
enabled_eventsarrayأنواع الأحداث المشترَك فيها.
statusstringenabled أو disabled.
secretstringسرّ التوقيع whsec_ للتحقّق من توقيع HMAC على الإشعارات.
api_key

مفتاح وصول إلى واجهة برمجة التطبيقات (لا يُعرض السرّ كاملًا بعد إنشائه).

api_key 
{
  "id": "key_88",
  "object": "api_key",
  "name": "Production",
  "prefix": "sk_9a1b2c3d4e5f6",
  "livemode": true,
  "created_at": 1754000000,
  "last_used_at": 1754500000
}
الحقلالنوعالوصف
namestringاسم وصفي للمفتاح.
prefixstringالبادئة الظاهرة من المفتاح.
livemodebooleanيبيّن ما إذا كان المفتاح حيًّا.
last_used_atinteger · nullوقت آخر استخدام (طابع زمني بصيغة Unix).

جاهز للبناء على «وثائق»؟

ابدأ بدليل البدء السريع، وأصدر أول طلب توقيع خلال دقائق بمفتاح تجربة مجاني، واجعل بريدك الإلكتروني مستلِمَ أول اختبار.

ابدأ خلال خمس دقائق