للمطوّرين · دليل البدء السريع

من صفر إلى أول عقد موقّع في دقائق.

هذا الدليل يأخذك خطوة بخطوة من إنشاء مفتاح الـAPI حتى تنزيل عقد موقّع بحجّية قانونية والتحقّق منه — عبر خمس خطوات مباشرة. الأمثلة جاهزة للنسخ بـ cURL و Node و Python و PHP. تنبيه: لا يوجد وضع اختبار — كل مفتاح حيّ وكل نداء يُفوتَر فعليًا، فابدأ برصيد صغير وبريدك الإلكتروني كمستلم أول تجربة.

أنشئ مفتاحك التوثيق الكامل
رصيد مسبوق الدفع بالجنيه المصري SDK لـ Node و Python و PHP محضر أدلّة مختوم وقابل للتحقّق
201 Created عقد موقّع
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}
    ]
  }'
قبل أن تبدأ

ثلاثة أشياء تحتاجها للانطلاق.

تجهيزات بسيطة تُنجزها في دقيقة، ثم تنتقل مباشرة إلى أول استدعاء برمجي.

حساب على وثائق

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

مفتاح API سرّي

أنشئ مفتاحًا بصيغة sk_ من لوحة التحكّم. يمنحك الوصول الكامل للـAPI — والمفتاح حيّ منذ اللحظة الأولى، فكل نداء تنفّذه به حقيقي ويُفوتَر.

خطة تدعم الـAPI

الوصول البرمجي متاح على الخطط التي تتضمّن الـAPI. راجع صفحة الأسعار لاختيار الخطة المناسبة لحجم استخدامك.

لا يوجد وضع اختبار. كل مفتاح sk_ حيّ منذ إنشائه: يرسل رسائل بريد حقيقية للموقّعين، ويُصدر عقودًا نافذة بحجّية قانونية، ويُخصم رصيدك فعليًا (20 ج.م لكل طلب توقيع، +35 ج.م لكل موقّع يتطلّب تحقّق هوية). للتجربة الآمنة: اشحن رصيدًا صغيرًا واستخدم بريدك الإلكتروني الخاص كمستلم أول اختبار.
خمس خطوات

من المفتاح إلى العقد الموقّع — خطوة بخطوة.

اتبع الخطوات بالترتيب. كل خطوة قائمة بذاتها ومزوّدة بأمثلة جاهزة للنسخ في أربع لغات.

1 المصادقة

احصل على مفتاح الـAPI

من لوحة التحكّم، افتح Dashboard ← Developers ← API Keys وأنشئ مفتاحًا جديدًا. ستحصل على نوعين من المفاتيح، ولا وجود لوضع اختبار — كل مفتاح يعمل على بياناتك الحقيقية فورًا:

المفتاحالوصف
sk_...مفتاح سرّي، للخادم فقط، صلاحية كاملة. يرسل الرسائل فعليًا، ويُصدر عقودًا نافذة بحجّية قانونية، وتُحتسب تكلفته ضمن استخدامك من أول نداء.
pk_...مفتاح عام (Publishable)، آمن للكشف في المتصفح، مقفول على نطاقاتك (allowed_origins)، ومحدود بمجموعة مسارات (قوالب، طلبات توقيع، موقّعين، تدفّقات).

المصادقة تتم عبر ترويسة Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx مع كل طلب. ثبّت أيضًا إصدار الـAPI عبر ترويسة Wthaiq-Version: 2026-07-01 ليبقى سلوك الواجهة مستقرًّا عبر التحديثات.

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

ثبّت الـSDK وهيّئ العميل

مكتباتنا الرسمية من الفئة الأولى متاحة لـ Node و Python و PHP، وتتكفّل بالمصادقة وإعادة المحاولة وتثبيت إصدار الـAPI تلقائيًا. أو تعامل مع الواجهة مباشرة عبر cURL دون أي حزمة.

cURLNodePythonPHP
shell 
# لا يحتاج cURL أي SDK — فقط اضبط مفتاحك
export WTHAIQ_API_KEY="sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# تحقّق من الاتصال بجلب القوالب الجاهزة
curl https://wthaiq.com/api/v1/templates \
  -H "Authorization: Bearer $WTHAIQ_API_KEY" \
  -H "Wthaiq-Version: 2026-07-01"
terminal + index.js 
npm i @wthaiq/node

import Wthaiq from '@wthaiq/node';
const wt = new Wthaiq('sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
terminal + main.py 
pip install wthaiq

import wthaiq
wt = wthaiq.Client('sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
terminal + index.php 
composer require wthaiq/wthaiq-php

$wt = new \Wthaiq\Client('sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
استعرض القائمة الكاملة للمكتبات (Go و Ruby و ‎.NET أيضًا) في صفحة الـSDK. كل المكتبات تتبع SemVer وتثبّت ترويسة إصدار الـAPI تلقائيًا.
3 الإنشاء

أنشئ أول طلب توقيع

الآن أنشئ طلب توقيع من قالب جاهز. في المثال التالي نستخدم قالب عقد العمل (tpl_employment)، وموقّعًا واحدًا يوقّع برسم توقيعه (method: draw) بعد اجتياز تأكيد الهوية (require_identity: true) وهو ما يرفع الطلب إلى مستوى التوقيع المتقدّم (AES).

POST /v1/signature_requests
cURLNodePythonPHP
create.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 
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', 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' }
});

console.log(sr.signers[0].signing_url);
create.py 
sr = wt.signature_requests.create(
    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'},
)

print(sr.signers[0].signing_url)
create.php 
$sr = $wt->signatureRequests->create([
    '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'],
]);

echo $sr->signers[0]->signing_url;

الاستجابة هي كائن signature_request بحالة sent، ويحوي الموقّع مع رابط التوقيع signing_url الجاهز للفتح أو التضمين:

201 Created · application/json 
{
  "id": "sr_3n8Kd2Qa1V",
  "object": "signature_request",
  "livemode": false,
  "status": "sent",
  "title": "عقد عمل — أحمد م.",
  "legal_level": "aes",
  "format": "pades-lt",
  "source": { "type": "template", "template_id": "tpl_employment" },
  "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,
  "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://sign.wthaiq.com/s/uZ8..",
      "identity": { "status": "pending", "provider": "didit", "level": "aes" }
    }
  ]
}
idمُعرّف الطلب بالبادئة sr_. استخدمه في كل الاستدعاءات اللاحقة (المتابعة، التنزيل، الإلغاء).
statusحالة الطلب. تبدأ sent بعد الإرسال، وتمرّ عبر viewed و partially_signed حتى completed.
livemodetrue دائمًا — لا يوجد وضع اختبار. الطلب أُرسل فعليًا وستُصدر شهادة نافذة عند اكتمال التوقيع.
signers[].signing_urlرابط صفحة التوقيع المستضافة. افتحه للموقّع مباشرة، أو ضمّنه في تطبيقك عبر جلسة توقيع مصغّرة.
signers[].identityحالة تأكيد الهوية عبر Didit (مستند رسمي + مطابقة وجه حيّة) — يجب أن تُعتمد قبل أن يوقّع لأننا طلبنا require_identity.
referencenull الآن. يُسنَد رمز التحقّق العام WTQ-... تلقائيًا عند اكتمال التوقيع.
4 المتابعة

تابع الحالة

هناك طريقتان لمعرفة متى يوقّع الطرف الآخر. اختر السحب اليدوي (Polling) للتجارب السريعة، والـWebhooks للإنتاج.

الطريقة الأولى — السحب (Polling): استعلم عن الطلب متى شئت. الحالة status تعكس آخر وضع.

GET /v1/signature_requests/{id}
poll.sh 
curl https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"
الطريقة المُوصى بها: Webhooks. بدل السحب المتكرر، دع «وثائق» تُخطر خادمك لحظيًا. سجّل نقطة استقبال (endpoint) واستمع لحدث signature_request.completed، فتتفاعل فور اكتمال التوقيع دون أي استعلام يدوي. تفاصيل التسجيل والتحقّق من التوقيع في صفحة الـWebhooks.

الطريقة الثانية — Webhook: يصلك جسم الحدث كاملًا عبر POST إلى نقطتك، والمورد المتأثّر مغلَّف تحت data.object:

signature_request.completed · POST body 
{
  "id": "evt_2M",
  "object": "event",
  "type": "signature_request.completed",
  "created_at": 1754500000,
  "livemode": false,
  "data": {
    "object": {
      "id": "sr_3n8Kd2Qa1V",
      "object": "signature_request",
      "status": "completed",
      "legal_level": "aes",
      "reference": "WTQ-000123",
      "completed_at": 1754500000,
      "download_url": "https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/download"
    }
  }
}

تحقّق من ترويسة التوقيع Wthaiq-Signature على كل طلب وارد، وأعِد استجابة 2xx بسرعة، ونفّذ العمل الثقيل بشكل غير متزامن.

5 التنزيل والتحقّق

نزّل العقد الموقّع وتحقّق منه

بمجرد أن تصبح الحالة completed، نزّل ملف الـPDF النهائي الموقّع والمختوم. هذه النقطة متاحة للطلبات المكتملة فقط وتُرجع application/pdf. الدليل التشفيري المستقلّ لهذا المسار هو محضر الأدلّة المختوم (JSON) وليس توقيع PAdES مضمّنًا داخل الـPDF — نزّله عبر GET /api/evidence.php?scope=api&doc=<id>.

GET /v1/signature_requests/{id}/download
download.sh 
curl -L https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/download \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o contract-signed.pdf

للتحقّق العلني من سلامة العقد، استخدم رمز المرجع WTQ-... الذي أُسنِد عند الاكتمال. أي طرف يملك الرمز يمكنه التأكّد من أصالة الوثيقة وسلامتها — برمجيًا أو عبر الصفحة العامّة ‎/verify‎.

GET /v1/verifications/{reference}
verify.sh 
curl https://wthaiq.com/api/v1/verifications/WTQ-000123 \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# الاستجابة
{
  "object": "verification",
  "reference": "WTQ-000123",
  "found": true,
  "status": "completed",
  "integrity": "intact",
  "document": { "title": "عقد عمل", "sha256": "a3f1..", "format": "pades-lt", "legal_level": "aes" }
}
كيف تُضمن السلامة؟ يُحسب تجزئة SHA-256 للوثيقة عند الختم، ويُختم للطلب محضر أدلّة موثّق يحمل توقيع Ed25519 (يتحقّق منه أي طرف بالمفتاح العام على /trust) وختمًا زمنيًا معتمدًا RFC 3161. أي تعديل لاحق على بايت واحد يغيّر التجزئة فتتحوّل integrity إلى modified ويُكشف التلاعب فورًا. مزيد من التفاصيل في صفحة الحجّية.
الخطوات التالية

أكملت أول تكامل — إلى أين الآن؟

تعمّق في المرجع الكامل، وأمِّن نظامك بالـWebhooks، ووسّع تكاملك.

التوثيق الكامل

المرجع الشامل للمفاهيم والمصادقة وإدارة الأخطاء وترقيم الصفحات.

افتح التوثيق

الـWebhooks

استقبل الأحداث لحظيًا وتحقّق من التوقيع بترويسة Wthaiq-Signature.

اضبط الأحداث

مرجع الـAPI

كل النقاط والكائنات والحقول والأخطاء موثّقة بالتفصيل مع أمثلة حيّة.

تصفّح المرجع

المكتبات (SDKs)

مكتبات رسمية لـ Node و Python و PHP و Go و Ruby و ‎.NET‎ مع أمثلة.

اختر مكتبتك

التكاملات

اربط «وثائق» بأدواتك وأنظمتك عبر تكاملات جاهزة وسير عمل مؤتمت.

استعرض التكاملات

الحجّية والمصداقية

افهم مستويات SES و AES و QES ومعايير PAdES والإطار القانوني المصري.

اعرف المزيد
أسئلة شائعة

أسئلة المطوّرين قبل البدء.

هل توجد بيئة اختبار؟

لا. لا يوجد وضع اختبار منفصل — كل مفتاح sk_ حيّ منذ إنشائه: يرسل رسائل بريد حقيقية للموقّعين، ويُصدر شهادات قانونية نافذة، ويُخصم رصيدك فعليًا مع كل نداء. الطريقة الآمنة للتجربة: اشحن رصيدًا صغيرًا واستخدم بريدك الإلكتروني الخاص كمستلم. للاستخدام في المتصفّح دون كشف صلاحيات كاملة، استخدم مفتاحًا عامًا pk_ — محدود بمسارات معيّنة ومقفول على نطاقاتك.

ما الفرق بين SES و AES و QES بالنسبة لي كمطوّر؟

تتحكّم في المستوى عبر حقلي legal_level و method. المستوى البسيط SES = توقيع مرسوم مع رمز تحقّق عبر البريد. المستوى المتقدّم AES يضيف تأكيد هوية موثّق (مستند رسمي ومطابقة وجه حيّة عبر Didit) يربط التوقيع بشخص حقيقي — فعّله بضبط require_identity: true. المستوى المؤهّل QES يستخدم شهادة على رمز أجهزة (method: token) من جهة تصديق مرخّصة ويبلغ أعلى حجّية بموجب قانون التوقيع الإلكتروني المصري رقم 15 لسنة 2004. تفاصيل أوفى في صفحة الحجّية.

هل يحدث التوقيع داخل تطبيقي؟

لك الخياران. الأسهل هو استخدام signing_url المُستضاف الذي يعود مع كل موقّع. وإن أردت تجربة مدمجة بعلامتك دون مغادرة تطبيقك، فاطلب جلسة توقيع قصيرة الأمد عبر POST /v1/signers/{id}/signing_session وضمّنها في واجهتك. راجع مرجع الـAPI لتفاصيل التوقيع المدمج (White-label).

كيف أؤمّن مفاتيحي؟

استخدم المفتاح السرّي على الخادم فقط، ولا تضعه أبدًا في كود عميل ويب أو موبايل أو في مستودع عام. احفظه في متغيّرات بيئة أو خزنة أسرار، وقيّده بأقل صلاحية ممكنة، وبدّله دوريًا. إن اشتبهت في تسرّبه فألغِه فورًا من لوحة التحكّم وأنشئ غيره. أمّن أيضًا نقاط الـWebhooks بالتحقّق من ترويسة Wthaiq-Signature. راجع دليل الأمان.

ما لغات SDK المدعومة؟

مكتبات الفئة الأولى الرسمية هي Node.js و Python و PHP، وتتوفّر كذلك مكتبات لـ Go و Ruby و ‎.NET‎. جميعها مفتوحة على منظمة github.com/wthaiq، وتتبع إصدارًا دلاليًا (SemVer)، وتثبّت ترويسة إصدار الـAPI تلقائيًا. القائمة الكاملة وأوامر التثبيت في صفحة الـSDK.

جاهز لأول عقد موقّع؟

أنشئ مفتاحك الآن، وشغّل التدفّق كاملًا في دقائق — برصيد صغير وبريدك الخاص كمستلم أول اختبار.

أنشئ مفتاحك التوثيق الكامل