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

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

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

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

دليل الوسوم

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

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

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

يبدأ الخط الزمني من الإطلاق العام للواجهة v1 في 4 أكتوبر 2026، ثم تحديثاتها بتواريخها ووسومها الدقيقة.

رسائل الأخطاء بالإنجليزية وحقول أوضح في الأخطاء
  • إضافةتصدر رسالة الخطأ بالإنجليزية مع رأس الطلب 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 في الطلبات القديمة وحدها.
الإطلاق العام للواجهة v1
  • إضافةطلبات التوقيع على المسار POST /v1/signature_requests بدورة حياتها الكاملة، ونقاط النهاية send و cancel و reminders و download و certificate و evidence.
  • إضافةالقوالب عبر GET /v1/templates وإنشاء طلب التوقيع من قالب بتمرير قيم حقوله، والتحقّق العلني بالرقم المرجعي عبر GET /v1/verifications/{reference}.
  • إضافةالتوقيع المضمَّن داخل تطبيقك عبر POST /v1/signers/{id}/signing_session و /v1/sessions، وتأكيد هوية الموقّع عبر مزوّد متخصّص بالحقل require_identity والكائن identity_verification.
  • إضافةإشعارات أحداث آلية (Webhooks) موقّعة بالترويسة Wthaiq-Signature بخوارزمية HMAC-SHA256، وإعادة المحاولة على فترات متزايدة حتى 24 ساعة، ومنها أحداث مراجعة تأكيد الهوية signer.identity_in_review و signer.identity_resubmission_requested و signer.identity_declined.
  • إضافةمفاتيح حيّة بالبادئتين sk_ و pk_، ومفاتيح تجربة بالبادئتين sk_test_ و pk_test_ لا تُخصم بها قيمة ولا تُرسَل بها رسالة إلى أحد، ويبيّن الحقل livemode أيَّهما أنشأ الكائن.
  • تغييرتعود الأخطاء كلها ببنية موحّدة، ويُقبل Idempotency-Key على طلبات POST لتكون إعادة المحاولة آمنة، والحدّ 100 طلب في كل 10 ثوانٍ مع الترويسات X-RateLimit-Limit و Retry-After، وتحمل كل استجابة Wthaiq-Request-Id.
  • متاححِزم تطوير البرمجيات (SDKs) الرسمية: wthaiq/wthaiq-php (PHP) · wthaiq (Node.js) · wthaiq (Python) — تثبّت ترويسة الإصدار افتراضيًّا، وتتبع نظام الترقيم الدلالي (SemVer). ومعها مكتبتا التوقيع داخل التطبيق (iOS · Android)؛ وأوامر التثبيت في صفحة المكتبات الرسمية.
سياسة الإصدارات

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

نعتمد ترقيم الإصدارات بالتاريخ (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