تخطّي إلى المحتوى
للمطوّرين · سجل التحديثات

سجل التحديثات — كل جديد في الـAPI أولًا بأول.

تتطوّر واجهة «وثائق» البرمجية باستمرار دون أن تُعطّل تكاملك، ويُثبَّت الإصدار بترويسة مؤرّخة Wthaiq-Version: 2026-07-01: فالتغييرات المتوافقة — مثل نقطة نهاية جديدة أو حقل اختياري أو نوع حدث جديد — تُطرح تباعًا على إصدارك نفسه، أما التغييرات الجذرية فتأتي في إصدار مؤرّخ جديد لا يسري عليك حتى تقرّر الترقية إليه بنفسك. وتوثّق هذه الصفحة كل تغيير بتاريخه ووسمه.

اقرأ الوثائق
الإصدار المستقر الحالي: v1 · 2026-07-01
الإصدار المؤرّخ المثبّت Wthaiq-Version: 2026-07-01
إضافةتغييرأمان
إضافةإصلاح
إضافة
تغييرإيقاف
الإصدار المستقر الحالي · v1
اللون والنوع والأثر في تكاملك

دليل الوسوم

يحمل كل تغيير في السجل وسمًا بلونه ونوعه، لتعرف أثره في تكاملك من النظرة الأولى.

إضافة تغيير إصلاح إيقاف تدريجي أمان
الخط الزمني

الإصدارات الأحدث أولًا.

يضمّ الخط الزمني الإصدار المستقر v1 وتحديثاته، ثم الإصدارات التجريبية (beta) التي سبقته، بتواريخها ووسومها الدقيقة.

رسائل الأخطاء بالإنجليزية وحقول أوضح في الأخطاء
  • إضافةتصدر رسالة الخطأ بالإنجليزية مع رأس الطلب Accept-Language: en أو المعامل ?lang=en، وتبقى العربية افتراضيًّا، ولا تتغيّر رموز الأخطاء.
  • إصلاحصار المسار /en/api/v1/… يعمل كالمسار /api/v1/… تمامًا، ورسائل أخطائه بالإنجليزية.
  • إضافةupgrade_url صار حقلًا في الخطأين 402 plan_required و 402 plan_expired، و verify_url حقلًا في الخطأ 403 kyb_required، و max_signers حقلًا في الخطأ 400 too_many_signers.
  • تغييرGET /v1/verifications/{reference} لمرجع غير موجود يعود بخطأ 404 بالصيغة الموحّدة والرمز not_found، بدل جسم يشبه ردّ النجاح.
  • إصلاحGET /v1/webhook_endpoints صار يعيد next_cursor ويقبل starting_after، فتصل إلى كل نقاط الاستقبال صفحةً بعد صفحة.
  • إصلاحيشير الحقل docs في GET /v1 إلى التوثيق في لوحة المطوّرين.
مطابقة اسم الموقّع بوثيقة هويته
  • إضافةبعد تأكيد الهوية نطابق الاسم في وثيقة الموقّع بالاسم المرسَل في الطلب. وحين يختلفان يُوقَف التوقيع حتى قرارك، ويصلك الحدث signer.identity_match_hold ثم signer.identity_match_decided بعد القرار.
  • إضافةنقطة جديدة للقرار: POST /v1/signers/{id}/identity_match بالقيمة approve أو reject، وصفحة «مراجعة الهوية» في لوحة المطوّرين بدور جديد «مراجع الهوية».
  • إضافةيحمل كائن الموقّع identity.name_match بحالة المطابقة والاسمين، ويمكنك من الصفحة نفسها اختيار «سجّل الاختلاف فقط» بدل إيقاف التوقيع.
حسابات المطوّرين والباقات السنوية
  • تغييرصارت لوحة المطوّرين منتجًا مستقلًّا بحساب مطوّر منفصل يُنشأ من صفحة التسجيل فيها، ولا يرتبط بحسابات منصّة وثائق في الدخول ولا في البيانات ولا في الأرصدة.
  • تغييريتطلّب الإرسال الحيّ باقة سنوية مدفوعة وشركة موثّقة، وإلّا عاد الخطأ 402 plan_required أو 402 plan_expired أو 403 kyb_required. ويبقى مفتاح التجربة مجانيًّا بحدود يومية.
  • تغييريُحتسب كل موقّع في الطلب الحيّ إرسالًا من رصيد باقتك السنوي، والحدّ الأقصى خمسة موقّعين في الطلب الواحد، وبعد نفاده تُخصم الزيادة من المحفظة بسعر باقتك، ويُخصم تأكيد الهوية من المحفظة دائمًا. وإن لم يكفِ الرصيد عاد الخطأ 402 insufficient_balance ولا يُنشأ الطلب.
  • إضافةيعود الخطأ 403 plan_feature_unavailable حين يطلب الطلب قدرة لا تتضمّنها باقتك، ويحمل الحقول feature و required_plan و upgrade_url.
  • تغييرتعيد نقطتا GET /v1/usage و GET /v1/balance المبالغ كائناتٍ بعملة محفظتك ومعها الباقة وأسعارها، وأُزيلت المفاتيح amount_egp و month_spent_egp و send_egp. وصار الحقل cost في الجلسة كائنًا بالمبلغ والعملة والمصدر.
  • إيقاف تدريجيأُلغيت الطلبات الحيّة المجانية التي كانت تُتاح قبل توثيق الحساب، ويبقى الحقل trial في الطلبات القديمة وحدها.
أحداث مراجعة تأكيد الهوية
  • إضافةثلاثة أحداث جديدة تتابع بها تأكيد هوية الموقّع قبل اعتماده: signer.identity_in_review و signer.identity_resubmission_requested و signer.identity_declined. يُطلَق كل حدث مرّة واحدة لكل تغيّر في الحالة.
  • تغييرأُضيف الحقل identity.verification_id إلى كائن signer، واتّسعت قيم الحقلين identity.status و identity_verification.status.
مفاتيح التجربة
  • إضافةأُعيدت مفاتيح التجربة بالبادئتين sk_test_ و pk_test_ إلى جانب المفتاحين الحيّين sk_ و pk_. ويُختار نوع المفتاح عند إنشائه، ويبيّن الحقل livemode في كل كائن وحدث أيَّ المفتاحين أنشأه.
  • تغييرلا يُخصم بمفتاح التجربة شيء من رصيدك، ولا تُرسَل به دعوة ولا تذكير ولا نسخة إلى أحد، ويقتصر الموقّعون فيه على بريد حسابك أو رقمه وبريد أعضاء فريقك أو أرقامهم.
  • تغييريقتصر مفتاح التجربة على التوقيع البسيط ses بلا تأكيد هوية، ولا يُختم لطلباته محضر أدلّة، ولا يصدر له الحدثان document.sealed و verification.created.
  • تغييرتصل أحداث التجربة إلى نقاط الاستقبال المُنشأة بمفتاح تجربة عبر POST /v1/webhook_endpoints وحدها.
إلغاء وضع الاختبار وتوحيد صيغة المفاتيح
  • تغيير جوهريأُزيل نظام البيئتين sk_live_/sk_test_. وأصبح لكل مفتاح سرّي صيغة موحّدة: البادئة sk_ يليها 40 محرفًا بالنظام السداسي العشري، ويعمل المفتاح فعليًّا منذ لحظة إنشائه؛ فلا يوجد وضع اختبار منفصل، والحقل livemode يساوي true دائمًا. ملاحظة (2026-09-26): أُعيدت مفاتيح التجربة لاحقًا؛ راجِع التحديث في أعلى السجل.
  • إضافةمفاتيح عامة (Publishable) بالبادئة pk_ يمكن كشفها في المتصفّح بأمان، إذ تقتصر على نطاقات محدّدة عبر allowed_origins، وعلى مجموعة ثابتة من المسارات (القوالب وطلبات التوقيع والموقّعين والتدفّقات)، مع منع الكتابة على القوالب والموقّعين والتدفّقات.
  • أمانيُحتسب فعليًّا كل استدعاء لواجهة برمجة التطبيقات، أيًّا كان نوع المفتاح، على رصيدك المدفوع مسبقًا: سعر لكل طلب توقيع، وسعر إضافي لكل موقّع يتطلّب التحقّق من هويته. ولا توجد بيئة تجريبية معفاة من الفوترة. ملاحظة (2026-09-26): لم يعد هذا ساريًا على مفاتيح التجربة بعد إعادتها؛ راجِع التحديث في أعلى السجل.
الإصدار المستقر v1
  • إضافةأُطلقت للعموم واجهة طلبات التوقيع على المسار POST /v1/signature_requests بدورة الحياة الكاملة (draft ثم sent ثم completed) ونقاط النهاية send و cancel و reminders و download و certificate.
  • إضافةإشعارات أحداث آلية (Webhooks) موقّعة عبر الترويسة Wthaiq-Signature (HMAC-SHA256 بصيغة t=..,v1=..)، مع هامش سماح زمني قدره 300 ثانية، وإعادة المحاولة على فترات متزايدة مدةً تصل إلى 24 ساعة.
  • إضافةمفاتيح الواجهة البرمجية بصيغتَي sk_live_ و sk_test_، وسرّ توقيع إشعارات الأحداث whsec_؛ ولا يُرسل وضع الاختبار بريدًا حقيقيًّا ولا يُصدر شهادات قانونية. ملاحظة (2026-07-26): أُزيل نظام البيئتين هذا لاحقًا؛ راجِع التحديث في أعلى السجل.
  • متاححِزم تطوير البرمجيات (SDKs) الرسمية: wthaiq/wthaiq-php (PHP) · wthaiq (Node.js) · wthaiq (Python) — تثبّت ترويسة الإصدار افتراضيًّا، وتتبع نظام الترقيم الدلالي (SemVer). ملاحظة: نُشرت هذه الحِزم مع الإطلاق الرسمي، ومعها مكتبتا التوقيع داخل التطبيق (iOS · Android)؛ وأوامر التثبيت في صفحة المكتبات الرسمية.
  • تغييرأصبح Wthaiq-Version: 2026-07-01 هو الإصدار المؤرّخ الافتراضي لكل الحسابات الجديدة، مع ترويسة Wthaiq-Request-Id في كل استجابة.
  • أمانأصبح استخدام TLS 1.2 أو أعلى إلزاميًّا، وأُتيح تدوير سرّ توقيع إشعارات الأحداث whsec_ من لوحة التحكّم دون انقطاع الخدمة.
قوالب العقود beta
  • إضافةنقطتا نهاية للقوالب: GET /v1/templates و GET /v1/templates/{id} مع تعريف الحقول (key و label و type و required).
  • إضافةإنشاء طلب توقيع مباشرة من قالب عبر source.type = "template" مع تمرير قيم الحقول في signers[].fields.
  • إصلاحتصحيح احتساب القيم الافتراضية للحقول عند غياب كائن fields من جسم الطلب.
التحقّق العلني بالرقم المرجعي beta
  • إضافةنقطة نهاية للتحقّق العلني بالرقم المرجعي: GET /v1/verifications/{reference} (بالبادئتين WTQ- و WTH-) دون مصادقة، لفحص سلامة المستند وأطرافه.
  • إضافةحقل integrity بقيم intact و modified و unknown في كائن verification، مع تقنيع أسماء الأطراف.
  • إضافةحدث verification.created إلى قائمة أحداث الإشعارات الآلية.
جلسات التوقيع المضمّن beta
  • إضافةجلسات توقيع مضمّنة بعلامتك التجارية: POST /v1/signers/{id}/signing_session تُصدر رابط توقيع أو رمز جلسة قصير الصلاحية لتضمينه داخل تطبيقك.
  • تغييرأُضيف الحقل signing_url إلى كائن signer لدعم صفحة التوقيع المستضافة والمضمّنة بالحقل نفسه.
  • إصلاحالتزام رموز الجلسات المضمّنة الصارم بموعد expires_at وإبطالها فور اكتمال التوقيع أو رفضه.
تأكيد الهوية (AES) عبر مزوّد متخصّص في التحقّق منها beta
  • إضافةتأكيد الهوية للمستوى المتقدّم (AES) عبر مزوّد متخصّص في التحقّق منها: الكائن identity_verification ونقطة النهاية GET /v1/identity_verifications/{id} (مستند رسمي ومطابقة وجه حيّة).
  • إضافةشرط require_identity على مستوى الطلب والموقّع، والحدثان signer.otp_verified و signer.identity_verified.
  • إضافةدعم legal_level = "aes" الذي يربط التوقيع بشخص حقيقي مؤكَّد الهوية قبل فتح صفحة التوقيع.
PAdES-LT و DSS لتوقيعات التوكن beta
  • إضافةختم pades-lt مع DSS/LTV في توقيعات التوكن (بتضمين الشهادات وقوائم الإبطال CRL) للحفظ طويل الأمد، وللتحقّق دون الرجوع إلى جهة الإصدار.
  • تغييرأصبح format = "pades-lt" القيمة الافتراضية لطلبات المستوى aes بدلًا من pades-t.
  • إضافةحدث document.sealed يُطلَق عند ختم محضر الأدلّة للطلب بعد اكتمال جميع التواقيع.
أساسيات المنصّة (أول beta عام) beta
  • إضافةختم زمني وفق RFC 3161 على محضر أدلّة كل طلب مكتمل لإثبات لحظة الختم إثباتًا مستقلًّا.
  • تغييرتُعيد كل نقاط النهاية الأخطاء ببنية موحّدة { error: { type, code, message, param, request_id } } مع رموز HTTP قياسية (400/401/402/409/422/429).
  • إضافةدعم ترويسة Idempotency-Key على طلبات POST (تُخزَّن 24 ساعة) لجعل إعادة المحاولة آمنة.
  • إضافةحدّ للمعدّل قدره 100 طلب لكل 10 ثوانٍ، مع الترويسات X-RateLimit-Limit و Remaining و Reset، ورمز 429 مصحوبًا بـRetry-After.
  • إيقاف تدريجيإيقاف تدريجي لمسار المعاينة القديم غير المؤرّخ /v1/preview لصالح الإصدار المؤرّخ الجديد؛ وستُزال نقطة النهاية هذه في إصدار مؤرّخ لاحق.
سياسة الإصدارات

كيف نُصدر التغييرات دون أن نكسر تكاملك.

نعتمد ترقيم الإصدارات بالتاريخ (date-based versioning)، فلا يتغيّر سلوك إصدارك المثبّت أبدًا بسبب تغيير جذري، وأنت وحدك من يقرّر موعد ترقيته.

تغييرات جذرية

تتطلّب إصدارًا مؤرّخًا جديدًا

  • حذف نقطة نهاية أو حقل أو قيمة enum، أو إعادة تسميتها.
  • تغيير نوع حقل قائم (مثلًا من string إلى integer).
  • إضافة معامل إلزامي جديد (required) إلى طلب قائم.
  • تشديد قواعد التحقّق بحيث تُرفض طلبات كانت تُقبل سابقًا.
  • تغيير المعنى الافتراضي لاستجابة، أو تغيير ترتيب عناصر قائمة.

تغييرات متوافقة

تُطرح تباعًا على إصدارك نفسه

  • إضافة نقطة نهاية جديدة كليًّا.
  • إضافة حقل جديد اختياري إلى جسم استجابة.
  • إضافة قيمة enum جديدة (احرص على معالجة القيم غير المعروفة بمرونة).
  • إضافة نوع حدث جديد إلى قائمة الإشعارات الآلية.
  • إضافة معامل اختياري جديد إلى طلب قائم.
مهلة الإيقاف التدريجي: نُعلن أي إيقاف تدريجي في هذا السجل بوسم «إيقاف تدريجي»، ونُرسل ترويسة Wthaiq-Deprecation مع الاستجابات المعنيّة، ونُبقي السلوك القديم عاملًا مدةً لا تقل عن 6 أشهر قبل إزالته في إصدار مؤرّخ جديد، ليتّسع لك الوقت للترقية بأمان.

ثبّت الإصدار بإرسال ترويسة Wthaiq-Version مع كل طلب. وإن لم تُرسلها، فسيُستخدم آخر إصدار مؤرّخ مثبّت على حسابك (أو أحدث إصدار افتراضي). ولا يتغيّر سلوك إصدارك المثبّت أبدًا بسبب تغيير جذري. مثال:

pin-version.sh 
curl https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01"

# الاستجابة تعيد الإصدار المستخدم فعليًّا في الترويسة:
# Wthaiq-Version: 2026-07-01
# Wthaiq-Request-Id: req_9f2a1c
ترقية مدروسة: حين تستعدّ لاعتماد إصدار مؤرّخ أحدث، راجِع فروقه في هذا السجل، ثم جرّبه أولًا بطلب صغير على حسابك (لا يوجد مفتاح اختبار منفصل، فالطلب حقيقي ويُفوتَر)، وبعد ذلك غيّر قيمة Wthaiq-Version في بيئة الإنتاج. ولا حاجة إلى ترقية كل تكاملاتك دفعة واحدة؛ فكل تكامل يُرقّى بالإيقاع الذي يناسبه.
من السجل إلى الوثائق

جاهز لبناء تكاملك؟

ابدأ من الوثائق الكاملة للواجهة البرمجية، وثبّت إصدارك المؤرّخ، واشترك لتصلك كل التحديثات أولًا بأول.

اقرأ الوثائق مرجع الـAPI