PHP
مكتبة الواجهةمكتبة الخادم الرسمية لـPHP: أنشئ طلبات التوقيع وتابعها وتحقّق من إشعارات الأحداث.
composer require wthaiq/wthaiq-php مكتبات للخادم (PHP · Node.js · Python) تنشئ طلبات التوقيع وتتابعها وتتحقّق من إشعارات الأحداث، ومكتبتان للتوقيع داخل التطبيق (iOS · Android) تعرضان صفحة التوقيع داخل تطبيقك دون أي مفتاح سرّي فيه. وما تتعلّمه في مكتبة ينطبق على بقيّتها.
المكتبات كلها متاحة الآن على GitHub ومصادر الحزم القياسية بالإصدار v1.0.0.
يحمل كل صندوق أمر التثبيت ومتطلّبات التشغيل ومصدر الحزمة، وزرّا GitHub والحزمة يفتحان المستودع ومصدر الحزمة.
مكتبة الخادم الرسمية لـPHP: أنشئ طلبات التوقيع وتابعها وتحقّق من إشعارات الأحداث.
composer require wthaiq/wthaiq-php مكتبة الخادم الرسمية لـNode.js بتعريفات TypeScript كاملة، وبلا اعتماديات تشغيل.
npm install wthaiqمكتبة الخادم الرسمية لـPython بعميلَين متزامن وغير متزامن، وبلا اعتماديات إلزامية.
pip install wthaiqواجهات لـSwiftUI ولـUIKit تعرض صفحة التوقيع داخل تطبيقك وتُبلغه بنتيجة الجلسة، دون أي مفتاح سرّي في التطبيق.
.package(url: "https://github.com/wthaiq/wthaiq-ios", from: "1.0.0") واجهات لـJetpack Compose ولـFragment ولـActivity Result تعرض صفحة التوقيع داخل تطبيقك، دون أي مفتاح سرّي في التطبيق.
implementation("com.wthaiq:signing:1.0.0") لكل مكتبة أمر تثبيتها ومثال بدء سريع مأخوذ من دليلها، وما تغطّيه، ومتطلّبات تشغيلها.
مكتبة الخادم الرسمية لـPHP: أنشئ طلبات التوقيع وتابعها وتحقّق من إشعارات الأحداث.
composer require wthaiq/wthaiq-phprequire '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ما يميّزها: تعمل بـcURL افتراضيًا وتقبل أي عميل PSR-18 (Guzzle · Symfony HttpClient)، وكائنات الاستجابة ثابتة بأنواعها، وتدعم PHP 8.1 إلى 8.4.
مكتبة الخادم الرسمية لـNode.js بتعريفات TypeScript كاملة، وبلا اعتماديات تشغيل.
npm install wthaiqimport 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ما يميّزها: مكتوبة بـTypeScript بتعريفات كاملة، وتُصدر ESM أو CommonJS، وتقبل AbortSignal لإلغاء النداء، والتحقّق من الإشعارات متزامن ويعمل في بيئات الحوسبة الطرفية أيضًا.
مكتبة الخادم الرسمية لـPython بعميلَين متزامن وغير متزامن، وبلا اعتماديات إلزامية.
pip install wthaiqimport 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ما يميّزها: عميل متزامن Client وغير متزامن AsyncClient بالدوالّ نفسها، وأنواع كاملة (py.typed)، ومكتبة httpx اختيارية للإدخال والإخراج غير المتزامن.
واجهات لـSwiftUI ولـUIKit تعرض صفحة التوقيع داخل تطبيقك وتُبلغه بنتيجة الجلسة، دون أي مفتاح سرّي في التطبيق.
.package(url: "https://github.com/wthaiq/wthaiq-ios", from: "1.0.0")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 وحده.
واجهات لـJetpack Compose ولـFragment ولـActivity Result تعرض صفحة التوقيع داخل تطبيقك، دون أي مفتاح سرّي في التطبيق.
implementation("com.wthaiq:signing:1.0.0")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).
خادمك ينشئ رابط التوقيع بمفتاحه السرّي ويعيده إلى التطبيق، والمكتبة تعرض الصفحة فقط. ولا تقبل إلا روابط https على نطاقات وثائق، وتُبقي ملفّات الجلسة في الذاكرة افتراضيًا.
تبلّغ المكتبة تطبيقك مرّة واحدة بإحدى خمس نتائج: وُقِّع، أو رُفض، أو أُلغي، أو انتهت الصلاحية، أو تعذّر. وتحرّك هذه النتيجة واجهتك، أمّا الإثبات فإشعار الحدث الذي يصل خادمك.
واجهة المكتبة بالعربية من اليمين إلى اليسار أو بالإنجليزية، وتتبع الوضع الليلي للنظام، ومعها شاشات التحميل والخطأ وإعادة المحاولة، ومرفقات الهوية والكاميرا وتأكيد الهوية داخل الصفحة.
نفصل بين إصدار المكتبة وإصدار واجهة برمجة التطبيقات، ونبقي التغييرات ضمن حدود يمكن توقّعها لتخطّط ترقياتك بثقة.
تتبع كل مكتبة الترقيم الدلالي MAJOR.MINOR.PATCH. لا تُدخَل أي تغييرات كاسِرة إلا في إصدار رئيسي (MAJOR) جديد، أما الإضافات المتوافقة وإصلاحات الأخطاء فتصدر بأمان في الإصدارات الفرعية (MINOR) وإصدارات التصحيح (PATCH).
إصدار المكتبة مستقلّ عن إصدار واجهة برمجة التطبيقات المثبَّت بالترويسة Wthaiq-Version، فيمكنك ترقية المكتبة دون أن يتغيّر سلوك الواجهة.
لكل مكتبة ملفّ CHANGELOG في مستودعها يدوّن ما أُضيف وما تغيّر في كل إصدار، أمّا تغييرات واجهة برمجة التطبيقات فتُؤرَّخ بترويسة الإصدار ويبقى كل إصدار مطروح مدعومًا.
تابع سجل التغييرات لتعرف مبكرًا ما يحتاج إلى تحديث.
| المكتبة | الحد الأدنى لبيئة التشغيل | مصدر الحزمة | الإصدار |
|---|---|---|---|
| PHP | PHP 8.1 فأعلى · الإضافتان curl / json | Packagist · wthaiq/wthaiq-php | متاح · v1.0.0 |
| Node.js | Node.js 18 فأعلى · تعريفات TypeScript مضمّنة · ESM / CommonJS | npm · wthaiq | متاح · v1.0.0 |
| Python | Python 3.10 فأعلى · بلا اعتماديات إلزامية | PyPI · wthaiq | متاح · v1.0.0 |
| iOS | iOS 15 فأعلى · Swift 5.9 فأعلى | Swift Package · WthaiqSigning | متاح · v1.0.0 |
| Android | Android 7.0 (minSdk 24) فأعلى · Kotlin / Java | Maven 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): الإضافات المتوافقة في إصدارات فرعية، وأي تغيير كاسر في إصدار رئيسي جديد.
ثبّت مكتبتك، واتبع دليل البدء السريع لإنشاء أول طلب توقيع خلال دقائق.