واجهة Khatm Developer Sandbox API

ادمج مسار توقيع Khatm مباشرة في تطبيقك.

أنشئ الطلبات واكتشف الحقول وأكدها وأرسل التذكيرات وألغِ المسارات واسترجع المستندات المكتملة مع أدلتها.

البدء السريع

1. أنشئ مفتاح Sandbox من تبويب API Sandbox في مساحتك. انسخ المفتاح khatm_test_… وسرّ الـ Webhook whsec_…: يظهران مرة واحدة فقط.
2. أنشئ طلباً مع ملف PDF والموقّعين:

curl "$KHATM_BASE_URL/v1/signature-requests" \
  -H "Authorization: Bearer $KHATM_API_KEY" \
  -F "document=@contract.pdf;type=application/pdf" \
  -F 'request={
    "client_reference": "contract-123",
    "signers": [{ "reference": "customer", "name": "Alice Martin",
      "email": "alice@example.com", "order": 1 }],
    "fields": [{ "signer_reference": "customer", "type": "signature",
      "page": 1, "x": 90, "y": 610, "width": 170, "height": 55 }]
  }'

1. فعّله عبر POST /signature-requests/{id}/activate للحصول على signing_url لكل موقِّع.
2. تابع الحالة عبر Webhook أو GET /signature-requests/{id}، ثم نزّل PDF الموقَّع والأدلة من /artifacts/{type}.

لا تملك الإحداثيات؟ احذف fields، واستدعِ POST /signature-requests/{id}/detect-fields، ثم أكّد الاقتراحات عبر PUT /signature-requests/{id}/fields.

العودة إلى تطبيقك

أضف return_url عند الإنشاء: بعد التوقيع (أو الرفض) يعود الموقِّع تلقائياً إلى تطبيقك. يضيف Khatm المعاملات khatm_status (signed أو declined أو cancelled أو expired) وsignature_request_id وclient_reference وsigner_reference. استخدمها للعرض، ثم أكّد النتيجة عبر API أو Webhook.

خيارات مفيدة أخرى:

• locale (fr أو en أو ar) لكل موقِّع يحدّد لغة صفحة التوقيع.
• sequential_signing: true يفرض ترتيب الموقّعين (order).
• GET /signature-requests يعرض طلباتك (مرشّحا status وclient_reference وتصفّح عبر cursor).
• POST /templates ينشئ قالباً قابلاً لإعادة الاستخدام عبر API.

تغيير موقّع

عنوان خاطئ أو غادر الشخص؟ استدعِ POST /v1/signature-requests/{id}/signers/{reference}/replace مع email (وname وlocale وsend_email). قبل التفعيل يُصحَّح الموقّع ببساطة. بعد التفعيل يُلغى الرابط السابق ويحتفظ الموقّع الجديد بالمرجع والترتيب والحقول نفسها، وتعيد الاستجابة رابط signing_url الجديد. لا يمكن استبدال موقّع سبق أن وقّع أو رفض (409).

تخصيص الرسائل الإلكترونية

أضف الكائن email عند الإنشاء: sender_name (اسم شركتك) وsubject وmessage (نص عادي مع الحفاظ على الأسطر) وlogo_url (صورة عبر HTTPS). يستخدمه Khatm في الدعوة والتذكيرات واستبدال الموقّع. تُكتب كل رسالة بلغة الموقّع locale (fr أو en أو ar، مع اتجاه من اليمين إلى اليسار للعربية) وتوضّح أنها مرسلة نيابةً عنك.

الإرسال الجماعي

يرسل POST /v1/bulk-sends قالباً واحداً إلى 50 مستلماً كحد أقصى في استدعاء واحد: يصبح كل مستلم (client_reference وsigners وfield_values) طلباً يُنشأ ويُفعَّل. تُعرض النتيجة لكل سطر (active أو already_exists أو error)، ولا يوقف سطر غير صالح بقية الأسطر. إعادة إرسال الدفعة نفسها لا تُنشئ تكراراً ولا تعيد إرسال الرسائل.

التحقق من هوية الموقّع

أضف "verification": "email_otp" إلى الموقّع. قبل رؤية المستند يتلقى رمزاً من 6 أرقام عبر البريد الإلكتروني (صالح 10 دقائق، 5 محاولات). يبقى المستند والتوقيع والرفض مقفلة على الخادم حتى إدخال الرمز. يظهر التحقق في الحالة (verified_at) وفي ملف الإثبات.

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

حدّد embed_origin (مثلاً https://app.example.com) عند الإنشاء. عندها يعيد التفعيل embed_url لكل موقّع لتحميله داخل <iframe> على هذا المصدر فقط، ولا يمكن لأي موقع آخر عرضه. ترسل الصفحة إلى نافذتك رسائل postMessage (signing.loaded وsigning.verification_required وsigning.signed وsigning.declined، وsigning.closed مع status عندما لا يعود الرابط صالحاً) تتضمّن signatureRequestId وclientReference وsignerReference. تحقّق من event.origin وأكّد النتيجة عبر webhook أو نقطة الحالة.

حزم SDK

تتوفر عملاء Node.js وPython وPHP دون أي اعتماديات في المستودع (sdks/). تضيف Idempotency-Key تلقائياً، وتعيد محاولة الردود 429 و503، وتتحقق من الـ webhooks.

المصادقة

يرسل كل طلب المفتاح في الترويسة Authorization: Bearer khatm_test_…. تعامل معه ككلمة مرور: احفظه على الخادم، وليس في المتصفح أو في رابط أو في السجلات. يُرفض المفتاح الملغى فوراً.

التحقق من الـ Webhooks

يوقّع Khatm القيمة webhook-id + "." + webhook-timestamp + "." + الجسم الخام بـ HMAC-SHA256 وسرّك whsec_…. قيمة الترويسة webhook-signature هي v1, متبوعة بالتوقيع بترميز base64.

• تحقّق من البايتات الخام بمقارنة ثابتة الزمن.
• ارفض الطوابع الزمنية القديمة.
• أزل التكرار عبر webhook-id: التسليم «مرة واحدة على الأقل» مع إعادة المحاولة (فوراً، ثم بعد نحو دقيقة و5 و30 دقيقة وساعتين).

الأحداث: signature_request.activated وsigner.viewed (أول فتح للرابط) وsigner.completed وsigner.declined وsigner.replaced وsigner.expired، ثم signature_request.completed أو .declined أو .cancelled أو .expired. تتضمّن أحداث الموقّع الحقل data.signer (المرجع والبريد والحالة). ترتيب الوصول غير مضمون: عند الشك اقرأ GET /v1/signature-requests/{id}.

التتبّع وإعادة الإرسال: يعرض GET /v1/webhook-deliveries كل حدث مع حالته (pending أو delivered أو failed) وآخر خطأ. بعد إصلاح المستقبِل، يعيد POST /v1/webhook-deliveries/{id}/replay إرسال الحدث فوراً بالقيمة نفسها لـ webhook-id.

الحدود والاحتفاظ

• ملف PDF حتى 8 MiB، وحتى 10 موقّعين و100 حقل لكل طلب.
• عند تجاوز الحد: استجابة 429 مع الترويستين X-RateLimit-Limit وX-RateLimit-Remaining.
• انقطاع مؤقت: استجابة 503 temporarily_unavailable. أعد المحاولة بفواصل متزايدة؛ إعادة طلب الإنشاء بنفس client_reference لا تنشئ نسخة مكررة أبداً.
• يُحذف المحتوى بعد 10 أيام من الرفع: نزّل PDF الموقَّع والأدلة قبل retention_expires_at.