المطورون

تكامل مباشر عبر API وWebhooks

تدفق التحقق الموصى به: ينشئ نظامك عملية تحقق عبر واجهة برمجة التطبيقات، يكمل المتقدّم رحلة الالتقاط عبر واثق، ويستلم نظامك نتيجة موقّعة عبر Webhook.

نظام العميل

واجهة برمجة تطبيقات واثق

التقاط بيانات المتقدّم

Webhook موقّع

استرجاع النتيجة

الحالة الظاهرة للمتقدّم واجهة استخدام فقط — لا تُعتمد كإثبات للنتيجة. النتيجة المعتمدة تصل عبر Webhook موقّع ثم تُسترجع من واجهة برمجة التطبيقات.

المصادقة

ترسل مفتاح API الخاص بك كـ Bearer token أو ترويسة X-API-Key. يُعرض المفتاح مرة واحدة فقط عند إنشائه — يجب حفظه في مدير أسرار من جانب الخادم، وليس في كود العميل أو الجوال.

Authorization: Bearer wk_live_<key-prefix>_<secret>
# or
X-API-Key: wk_live_<key-prefix>_<secret>

إنشاء عملية تحقق

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

POST /api/v1/client/verifications

{
  "verification_type": "national_id",
  "external_reference": "customer-829174",
  "expires_in_minutes": 1440
}

201 Created

{
  "id": "c767ef96-2209-4fd6-9062-97e2687886e5",
  "status": "session_created",
  "decision": null,
  "verification_url": "https://<verify-domain>/verify#session_token=...",
  "expires_at": "2026-08-02T12:00:00Z"
}

الأنواع المدعومة: الهوية الوطنية، جواز السفر (القديم)، جواز السفر الإلكتروني، وأنواع عامة حسب الاتفاق مع واثق.

استرجاع النتيجة

بعد استلام Webhook القرار، استرجع النتيجة المعتمدة. القرار إما مقبول أو قيد المراجعة أو مرفوض — عامل حالة "قيد المراجعة" كحالة معلّقة، لا كرفض.

GET /api/v1/client/verifications/{id}/result

{
  "status": "decided",
  "decision": "accepted",
  "assurance_level": "registry_matched",
  "risk_score": 0.08,
  "completed_at": "2026-08-01T12:08:31Z"
}

Webhooks

يرسل واثق طلبات HTTPS POST موقّعة بـ HMAC-SHA256. تحقق من التوقيع دائماً باستخدام النص الخام قبل تحليل JSON، وتحقق من الطابع الزمني، وامنع معالجة نفس الحدث مرتين.

Headers

X-Wathiq-Event: verification.decided
X-Wathiq-Event-Id: <event-uuid>
X-Wathiq-Timestamp: <unix-seconds>
X-Wathiq-Signature: v1=<hex-hmac-sha256>

signature verification

signed_payload = event_id + "." + timestamp + "." + raw_body
expected = "v1=" + hex(HMAC-SHA256(signing_secret, signed_payload))
# use constant-time comparison

إعادة المحاولة: حتى 3 محاولات لكل حدث، مع تأخير حوالي 30 ثم 60 ثانية بعد أول فشلين. التسليم "مرة واحدة على الأقل" — عالج التكرار بمفتاح فريد لمعرّف الحدث.

هذا ملخص عملي، وليس التوثيق الكامل. اطلب الوصول للحصول على دليل التكامل الكامل ومواصفة OpenAPI.

اطلب الوصول إلى API تواصل مع دعم التكامل