تخطّي إلى المحتوى
وثائقوثائقصفحات الشرح
المكتبات الرسمية · متاح · v1.0.0

خمس مكتبات رسمية بواجهة الموارد نفسها.

مكتبات للخادم (PHP · Node.js · Python) تنشئ طلبات التوقيع وتتابعها وتتحقّق من إشعارات الأحداث، ومكتبتان للتوقيع داخل التطبيق (iOS · Android) تعرضان صفحة التوقيع داخل تطبيقك دون أي مفتاح سرّي فيه. وما تتعلّمه في مكتبة ينطبق على بقيّتها.

المكتبات كلها متاحة الآن على GitHub ومصادر الحزم القياسية بالإصدار v1.0.0.

متاح · v1.0.0 ترخيص MIT ترقيم SemVer
المكتبات الرسمية

كل مكتبة في صندوقها: التثبيت والمتطلّبات والمصدر.

يحمل كل صندوق أمر التثبيت ومتطلّبات التشغيل ومصدر الحزمة، وزرّا GitHub والحزمة يفتحان المستودع ومصدر الحزمة.

PHP

مكتبة الواجهة
متاح · v1.0.0

مكتبة الخادم الرسمية لـPHP: أنشئ طلبات التوقيع وتابعها وتحقّق من إشعارات الأحداث.

الطرفية
composer require wthaiq/wthaiq-php
  • PHP 8.1 فأعلى · الإضافتان curl / json
  • Packagist · wthaiq/wthaiq-php

Node.js

مكتبة الواجهة
متاح · v1.0.0

مكتبة الخادم الرسمية لـNode.js بتعريفات TypeScript كاملة، وبلا اعتماديات تشغيل.

الطرفية
npm install wthaiq
  • Node.js 18 فأعلى · تعريفات TypeScript مضمّنة · ESM / CommonJS
  • npm · wthaiq

Python

مكتبة الواجهة
متاح · v1.0.0

مكتبة الخادم الرسمية لـPython بعميلَين متزامن وغير متزامن، وبلا اعتماديات إلزامية.

الطرفية
pip install wthaiq
  • Python 3.10 فأعلى · بلا اعتماديات إلزامية
  • PyPI · wthaiq

iOS

مكتبة التوقيع داخل التطبيق
متاح · v1.0.0

واجهات لـSwiftUI ولـUIKit تعرض صفحة التوقيع داخل تطبيقك وتُبلغه بنتيجة الجلسة، دون أي مفتاح سرّي في التطبيق.

Package.swift
.package(url: "https://github.com/wthaiq/wthaiq-ios", from: "1.0.0")
  • iOS 15 فأعلى · Swift 5.9 فأعلى
  • Swift Package · WthaiqSigning

Android

مكتبة التوقيع داخل التطبيق
متاح · v1.0.0

واجهات لـJetpack Compose ولـFragment ولـActivity Result تعرض صفحة التوقيع داخل تطبيقك، دون أي مفتاح سرّي في التطبيق.

build.gradle.kts
implementation("com.wthaiq:signing:1.0.0")
  • Android 7.0 (minSdk 24) فأعلى · Kotlin / Java
  • Maven Central · com.wthaiq:signing
الدليل التفصيلي

مكتبةً مكتبة: التثبيت والبدء السريع.

لكل مكتبة أمر تثبيتها ومثال بدء سريع مأخوذ من دليلها، وما تغطّيه، ومتطلّبات تشغيلها.

PHP

مكتبة الواجهة
متاح · v1.0.0

مكتبة الخادم الرسمية لـPHP: أنشئ طلبات التوقيع وتابعها وتحقّق من إشعارات الأحداث.

التثبيت

الطرفية
composer require wthaiq/wthaiq-php

البدء السريع

quickstart.php
require 'vendor/autoload.php';

$wthaiq = new \Wthaiq\Client(getenv('WTHAIQ_API_KEY'));
$request = $wthaiq->signatureRequests->create([
    'source'  => ['type' => 'template', 'template_id' => 'tpl_123'],
    'signers' => [['name' => 'Noha Hassan', 'email' => 'noha@example.com']],
]);

echo $request->id . ' ' . $request->status; // sr_3n8Kd2Qa1V... sent
يقرأ المثال المفتاح من متغيّر البيئة الظاهر في الكود. استعمل مفتاح sk_test_ أثناء البناء، فلا يُخصم رصيد ولا تُرسَل رسالة إلى أحد.

ما تغطّيه المكتبة

  • إنشاء طلبات التوقيع وإرسالها ومتابعة حالتها
  • القوالب ومسارات العمل
  • جلسات التوقيع المضمَّن في موقعك أو تطبيقك
  • تنزيل الوثيقة النهائية ومحضر الأدلّة المختوم
  • التحقّق من توقيع إشعارات الأحداث (Webhooks)
  • وضع اختبار مجاني بمفتاح sk_test_، ثم الوضع الحيّ بتغيير المفتاح وحده

ما يميّزها: تعمل بـcURL افتراضيًا وتقبل أي عميل PSR-18 (Guzzle · Symfony HttpClient)، وكائنات الاستجابة ثابتة بأنواعها، وتدعم PHP 8.1 إلى 8.4.

Node.js

مكتبة الواجهة
متاح · v1.0.0

مكتبة الخادم الرسمية لـNode.js بتعريفات TypeScript كاملة، وبلا اعتماديات تشغيل.

التثبيت

الطرفية
npm install wthaiq

البدء السريع

quickstart.js
import Wthaiq from 'wthaiq';

const wt = new Wthaiq(process.env.WTHAIQ_API_KEY);

const sr = await wt.signatureRequests.create({
  title: 'Employment contract',
  source: { type: 'template', template_id: 'tpl_123' },
  legal_level: 'aes',
  signers: [{ name: 'Ahmed Ali', email: 'ahmed@example.com', method: 'draw', require_identity: true }],
});

console.log(sr.id, sr.status); // sr_3f1c… sent
يقرأ المثال المفتاح من متغيّر البيئة الظاهر في الكود. استعمل مفتاح sk_test_ أثناء البناء، فلا يُخصم رصيد ولا تُرسَل رسالة إلى أحد.

ما تغطّيه المكتبة

  • إنشاء طلبات التوقيع وإرسالها ومتابعة حالتها
  • القوالب ومسارات العمل
  • جلسات التوقيع المضمَّن في موقعك أو تطبيقك
  • تنزيل الوثيقة النهائية ومحضر الأدلّة المختوم
  • التحقّق من توقيع إشعارات الأحداث (Webhooks)
  • وضع اختبار مجاني بمفتاح sk_test_، ثم الوضع الحيّ بتغيير المفتاح وحده

ما يميّزها: مكتوبة بـTypeScript بتعريفات كاملة، وتُصدر ESM أو CommonJS، وتقبل AbortSignal لإلغاء النداء، والتحقّق من الإشعارات متزامن ويعمل في بيئات الحوسبة الطرفية أيضًا.

Python

مكتبة الواجهة
متاح · v1.0.0

مكتبة الخادم الرسمية لـPython بعميلَين متزامن وغير متزامن، وبلا اعتماديات إلزامية.

التثبيت

الطرفية
pip install wthaiq

البدء السريع

quickstart.py
import os
import wthaiq

wt = wthaiq.Client(os.environ["WTHAIQ_API_KEY"])  # sk_test_... while you build

sr = wt.signature_requests.create(
    title="عقد عمل — أحمد سامي",
    source={"type": "template", "template_id": "tpl_123"},
    legal_level="aes",
    signers=[{"name": "أحمد سامي", "email": "ahmed@example.com", "method": "draw"}],
)

print(sr.id, sr.status)  # sr_3n8Kd2Qa1V... sent
يقرأ المثال المفتاح من متغيّر البيئة الظاهر في الكود. استعمل مفتاح sk_test_ أثناء البناء، فلا يُخصم رصيد ولا تُرسَل رسالة إلى أحد.

ما تغطّيه المكتبة

  • إنشاء طلبات التوقيع وإرسالها ومتابعة حالتها
  • القوالب ومسارات العمل
  • جلسات التوقيع المضمَّن في موقعك أو تطبيقك
  • تنزيل الوثيقة النهائية ومحضر الأدلّة المختوم
  • التحقّق من توقيع إشعارات الأحداث (Webhooks)
  • وضع اختبار مجاني بمفتاح sk_test_، ثم الوضع الحيّ بتغيير المفتاح وحده

ما يميّزها: عميل متزامن Client وغير متزامن AsyncClient بالدوالّ نفسها، وأنواع كاملة (py.typed)، ومكتبة httpx اختيارية للإدخال والإخراج غير المتزامن.

iOS

مكتبة التوقيع داخل التطبيق
متاح · v1.0.0

واجهات لـSwiftUI ولـUIKit تعرض صفحة التوقيع داخل تطبيقك وتُبلغه بنتيجة الجلسة، دون أي مفتاح سرّي في التطبيق.

التثبيت

Package.swift
.package(url: "https://github.com/wthaiq/wthaiq-ios", from: "1.0.0")

البدء السريع

OrderView.swift
import SwiftUI
import WthaiqSigning

struct OrderView: View {
    @State private var signingURL: URL?
    @State private var isSigning = false

    var body: some View {
        Button("Sign the contract") {
            Task {
                signingURL = try? await MyBackend.signingURL(forOrder: 42) // your API call
                isSigning = signingURL != nil
            }
        }
        .wthaiqSigning(isPresented: $isSigning, url: signingURL) { result in
            if case .signed = result { /* confirm on your backend via webhooks */ }
        }
    }
}
رابط التوقيع يأتي من خادمك (بإحدى مكتبات الخادم أو بالواجهة مباشرة) ولا يُوضع أي مفتاح في التطبيق. والنتيجة التي تبلّغها المكتبة تحرّك واجهتك، وإشعار الحدث على خادمك هو الإثبات.

ما تغطّيه المكتبة

  • عرض صفحة التوقيع داخل التطبيق بشاشة كاملة، لا في متصفّح خارجي
  • إبلاغ التطبيق بالنتيجة مرّة واحدة: وُقِّع · رُفض · أُلغي · انتهت الصلاحية · تعذّر
  • أحداث أثناء الجلسة لتحديث واجهتك
  • شاشات التحميل والخطأ وإعادة المحاولة، والوضع الليلي، والعربية من اليمين إلى اليسار والإنجليزية
  • مرفقات الهوية والكاميرا وتأكيد الهوية داخل الصفحة
  • لا مفتاح في التطبيق: خادمك ينشئ رابط التوقيع، وإشعار الحدث لديه هو الإثبات

ما يميّزها: معدِّل SwiftUI ‎.wthaiqSigning(isPresented:url:)‎ أو WthaiqSigningSheet، وفي UIKit الدالّة presentWthaiqSigning(url:) أو WthaiqSigningViewController بمفوَّض، والتوزيع عبر Swift Package Manager وحده.

Android

مكتبة التوقيع داخل التطبيق
متاح · v1.0.0

واجهات لـJetpack Compose ولـFragment ولـActivity Result تعرض صفحة التوقيع داخل تطبيقك، دون أي مفتاح سرّي في التطبيق.

التثبيت

build.gradle.kts
implementation("com.wthaiq:signing:1.0.0")

البدء السريع

OrderActivity.kt
class OrderActivity : ComponentActivity() {

    private val signing = registerForActivityResult(WthaiqSigning.Contract()) { result ->
        when (result) {
            is SigningResult.Signed -> showConfirming(result.outcome.reference.signatureRequestId)
            is SigningResult.Declined -> showDeclined(result.outcome.reason)
            SigningResult.Canceled -> Unit
            SigningResult.Expired -> requestNewLink()
            is SigningResult.Failed -> showError(result.error)
        }
    }

    private fun sign(signingUrl: String) {
        signing.launch(signingUrl)
    }
}
رابط التوقيع يأتي من خادمك (بإحدى مكتبات الخادم أو بالواجهة مباشرة) ولا يُوضع أي مفتاح في التطبيق. والنتيجة التي تبلّغها المكتبة تحرّك واجهتك، وإشعار الحدث على خادمك هو الإثبات.

ما تغطّيه المكتبة

  • عرض صفحة التوقيع داخل التطبيق بشاشة كاملة، لا في متصفّح خارجي
  • إبلاغ التطبيق بالنتيجة مرّة واحدة: وُقِّع · رُفض · أُلغي · انتهت الصلاحية · تعذّر
  • أحداث أثناء الجلسة لتحديث واجهتك
  • شاشات التحميل والخطأ وإعادة المحاولة، والوضع الليلي، والعربية من اليمين إلى اليسار والإنجليزية
  • مرفقات الهوية والكاميرا وتأكيد الهوية داخل الصفحة
  • لا مفتاح في التطبيق: خادمك ينشئ رابط التوقيع، وإشعار الحدث لديه هو الإثبات

ما يميّزها: Activity Result API عبر WthaiqSigning.Contract() · Jetpack Compose عبر rememberWthaiqSigningLauncher أو WthaiqSigningSheet بالحزمة الإضافية com.wthaiq:signing-compose · WthaiqSigningFragment داخل شاشتك · Kotlin أو Java · اعتماديات AndroidX فقط.

سلوك مشترك

سلوك واحد في مكتبات الخادم.

لا تحتاج إلى بناء منطق الشبكة والأمان من جديد؛ فمكتبات الخادم (PHP · Node.js · Python) تنفّذ القدرات التالية بالطريقة نفسها، لتحصل على تجربة متّسقة في مشاريعك كلها.

إعادة محاولة تلقائية آمنة

عند أخطاء الاتصال والمهلات والردود العابرة (429 أو 5xx) تُعيد المكتبة المحاولة بتراجع أُسّي يحترم ترويسة Retry-After، وترفق تلقائيًا مفتاح Idempotency-Key مع كل طلب POST وتعيد استعماله في محاولاتها، فلا يُنشأ المورد نفسه مرّتين.

ترقيم تلقائي للصفحات

استعرض آلاف السجلات دون أن تدير المؤشّرات بنفسك: دالّة القائمة تُرجع صفحة واحدة، والمُكرِّر يجلب الصفحات التالية تلقائيًا حتى آخر عنصر.

التحقّق من توقيع إشعارات الأحداث

دالّة مساعدة جاهزة تتحقق من ترويسة Wthaiq-Signature بمقارنة ثابتة الزمن، وترفض الطابع الزمني الأقدم من 300 ثانية، ثم تُعيد كائن الحدث بأنواعه بعد التحقّق منه.

أخطاء بأنواع مضمّنة

تُحوَّل أخطاء واجهة برمجة التطبيقات إلى استثناءات مُصنَّفة بحسب نوعها: المصادقة، والطلب غير الصحيح، وحدّ المعدّل، والتعارض، والاتصال؛ وتحمل الحقول code · param · request_id لتشخيص سريع.

تثبيت إصدار الواجهة

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

مهلات قابلة للضبط

اضبط المهلة لكل محاولة وعدد مرّات إعادة المحاولة لكل عميل أو لكل نداء، وأوقف النداء في Node.js بـAbortSignal، واستعمل عميل HTTP الخاصّ بك في PHP (PSR-18) أو Python (httpx).

ومكتبتا التوقيع داخل التطبيق

— iOS · Android: تعرضان الصفحة وتبلّغان النتيجة، ولا تحملان أي مفتاح.

لا مفتاح سرّي في التطبيق

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

نتيجة واحدة واضحة

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

جاهزة للعربية والوضع الليلي

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

الإصدارات والدعم

سياسة واضحة ومستقرّة للترقية.

نفصل بين إصدار المكتبة وإصدار واجهة برمجة التطبيقات، ونبقي التغييرات ضمن حدود يمكن توقّعها لتخطّط ترقياتك بثقة.

ترقيم SemVer

تتبع كل مكتبة الترقيم الدلالي MAJOR.MINOR.PATCH. لا تُدخَل أي تغييرات كاسِرة إلا في إصدار رئيسي (MAJOR) جديد، أما الإضافات المتوافقة وإصلاحات الأخطاء فتصدر بأمان في الإصدارات الفرعية (MINOR) وإصدارات التصحيح (PATCH).

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

سجلّ تغييرات لكل مكتبة

لكل مكتبة ملفّ CHANGELOG في مستودعها يدوّن ما أُضيف وما تغيّر في كل إصدار، أمّا تغييرات واجهة برمجة التطبيقات فتُؤرَّخ بترويسة الإصدار ويبقى كل إصدار مطروح مدعومًا.

تابع سجل التغييرات لتعرف مبكرًا ما يحتاج إلى تحديث.

الحد الأدنى لإصدارات بيئات التشغيل

المكتبةالحد الأدنى لبيئة التشغيلمصدر الحزمةالإصدار
PHPPHP 8.1 فأعلى · الإضافتان curl / jsonPackagist · wthaiq/wthaiq-phpمتاح · v1.0.0
Node.jsNode.js 18 فأعلى · تعريفات TypeScript مضمّنة · ESM / CommonJSnpm · wthaiqمتاح · v1.0.0
PythonPython 3.10 فأعلى · بلا اعتماديات إلزاميةPyPI · wthaiqمتاح · v1.0.0
iOSiOS 15 فأعلى · Swift 5.9 فأعلىSwift Package · WthaiqSigningمتاح · v1.0.0
AndroidAndroid 7.0 (minSdk 24) فأعلى · Kotlin / JavaMaven Central · com.wthaiq:signingمتاح · v1.0.0
الأساس المشترك: تثبّت مكتبات الخادم الترويسة Wthaiq-Version: 2026-07-01 افتراضيًا، وتتصل بـhttps://wthaiq.com/api/v1، وتصادِق عبر Authorization: Bearer sk_.... والمفتاح الحيّ sk_ يُرسل فعلًا ويُفوتَر، ونسخته التجريبية sk_test_ لا تخصم رصيدًا ولا تُرسل رسالة إلى أحد. أمّا مكتبتا التوقيع داخل التطبيق فلا تحملان أي مفتاح.
أسئلة شائعة

أسئلة المطوّرين حول المكتبات.

ما اللغات والمنصّات المدعومة رسميًا؟

خمس مكتبات رسمية: مكتبات للخادم (PHP · Node.js · Python) تستدعي واجهة برمجة التطبيقات كاملة، ومكتبتان للتوقيع داخل التطبيق (iOS · Android) تعرضان صفحة التوقيع داخل تطبيقك. وتتشارك مكتبات الخادم واجهة الموارد وأسماء العمليات نفسها، فما تتعلّمه في لغة ينطبق على بقيّتها.

هل المكتبات مفتوحة المصدر؟

نعم، بترخيص MIT على منظّمة github.com/wthaiq، وتُوزَّع عبر مصادر الحزم القياسية: Packagist · npm · PyPI · Swift Package · Maven Central.

كيف تتعامل مكتبات الخادم مع إعادة المحاولة والتكرار الآمن؟

تُعيد المكتبة المحاولة تلقائيًا (مرّتان افتراضيًا) على أخطاء الاتصال والمهلات والردود العابرة (429 أو 5xx)، بتراجع أُسّي يحترم ترويسة Retry-After. وترفق مع كل طلب POST مفتاح Idempotency-Key وتعيد استعماله في محاولاتها، فلا يُنشأ المورد نفسه مرّتين، ويمكنك تمرير مفتاحك الخاصّ لكل نداء.

كيف أثبّت إصدار الواجهة البرمجية داخل المكتبة؟

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

ماذا تحتاج مكتبتا التوقيع داخل التطبيق من خادمي؟

رابط توقيع ينشئه خادمك بإحدى مكتبات الخادم أو بالواجهة مباشرة، ولا يُوضع أي مفتاح في التطبيق. تعرض المكتبة الصفحة وتبلّغ تطبيقك بالنتيجة مرّة واحدة، وإشعار الحدث الذي يصل خادمك هو الإثبات النهائي.

ما الحد الأدنى لبيئات التشغيل وسياسة الإصدارات؟

PHP: PHP 8.1 فأعلى · الإضافتان curl / json؛ Node.js: Node.js 18 فأعلى · تعريفات TypeScript مضمّنة · ESM / CommonJS؛ Python: Python 3.10 فأعلى · بلا اعتماديات إلزامية؛ iOS: iOS 15 فأعلى · Swift 5.9 فأعلى؛ Android: Android 7.0 (minSdk 24) فأعلى · Kotlin / Java. وتتبع المكتبات كلها الترقيم الدلالي (SemVer): الإضافات المتوافقة في إصدارات فرعية، وأي تغيير كاسر في إصدار رئيسي جديد.

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

ثبّت مكتبتك، واتبع دليل البدء السريع لإنشاء أول طلب توقيع خلال دقائق.