API التحقّق ومخاطر المعاملات

استخدم مفتاح API للمنصة لبدء التحقق من الأفراد (KYC) والتحقق التجاري (KYB) ومراقبة المعاملات وفحص عناوين المحافظ من أنظمتك الخاصة، وللاستعلام عن سجلات الفحص. تعمل واجهة API المفتوحة ولوحة التحكم وفق مسار الفحص نفسه: الأسعار نفسها، والقواعد نفسها للنتائج والاسترداد والمطابقة.

أولًا انقر «تفعيل» في «التحقّق ومخاطر المعاملات» بلوحة التحكم، ثم أنشئ مفتاحًا في «إدارة API» وامنحه صلاحيات «التحقق والمخاطر»: verification.read للاستعلام عن الأسعار والسجلات، و verification.write لبدء الفحوص. يُخصم كل فحص من رصيد حسابك.

نقاط النهاية

• GET /api/v1/verification/info: يُرجع ما إذا كانت الخدمة مفعّلة لحسابك، وما إذا كان كل نوع من أنواع الفحص الأربعة متاحًا وسعره (USD)، والشبكات والأصول المتاحة لمراقبة المعاملات وفحص المحافظ. الأنواع غير المتاحة لا يُعرض لها سعر.
• POST /api/v1/verification/checks: يبدأ فحصًا واحدًا؛ ويتم الخصم وإنشاء السجل في الطلب نفسه. يُرجع التحقق من الهوية رابط الانتقال handoff_url، ويكفي أن ترسله إلى الشخص المعني بالتحقق؛ أما مراقبة المعاملات وفحص المحافظ فتُرجع النتيجة مباشرةً في العادة.
• GET /api/v1/verification/checks: تُرتَّب القائمة حسب وقت البدء من الأحدث إلى الأقدم، ويمكن تصفيتها بـ kind و status و verdict و keyword (المرجع / العنوان / رقم الخصم)، مع page و page_size للتقسيم إلى صفحات (حتى 100 لكل صفحة). يتضمن الاستعلام عن سجل واحد handoff_url ما دامت الجلسة لدى الشخص المعني بالتحقق. يعيد التحديث قراءة النتيجة من المزود (لا يمكن تحديث فحص المحافظ، لأن إعادة الفحص تُحتسب برسوم جديدة).

إعادة المحاولة بقيمة idempotency_key نفسها وبالمحتوى نفسه تُرجع السجل الأصلي دون خصم جديد؛ أما استخدام المفتاح نفسه بمحتوى مختلف فيُرفض (400). وإذا بدأت التحقق من الهوية مجددًا لمرجع طرف لم تكتمل جلسته بعد، تُرجَع الجلسة الأصلية (reused تساوي true) دون خصم كذلك.

استدعاء النتيجة

اضبط عنوان استدعاء https في «إعدادات التكامل» بلوحة التحكم وفعّله. عندما تتغير حالة سجل الفحص أو نتيجته بشكل غير متزامن (اكتمال التحقق من الهوية، أو تغيير النتيجة بمراجعة يدوية، أو تحديث نتيجة المعاملة، أو الإخفاق والاسترداد)، ترسل المنصة حدثًا بطلب POST. أما الاستدعاء الذي بدأته بنفسك فلا يُرسَل، لأن استجابته المتزامنة تتضمن النتيجة بالفعل.

الترويسة X-Tovanix-Event هي نوع الحدث (check.updated، أو ping للاختبار)، و X-Tovanix-Delivery هي event_id، و X-Tovanix-Timestamp هي الوقت بثواني يونكس، و X-Tovanix-Signature هي sha256= متبوعة بالقيمة السداسية العشرية لـ HMAC-SHA256(مفتاح التوقيع السري، الطابع الزمني + "." + جسم الطلب الخام).

يُعدّ الرد 2xx تسليمًا ناجحًا؛ وما عدا ذلك (بما فيه انتهاء المهلة) يُعاد إرساله بفواصل متزايدة: 1 دقيقة، 5 دقائق، 15 دقيقة، 1 ساعة، 3 ساعات، 6 ساعات، 12 ساعة، بحد أقصى 8 مرات، ثم يتوقف الإرسال. تحمل إعادة المحاولات event_id نفسه وجسم الحدث نفسه، لذا أزل التكرار اعتمادًا على event_id. قد تصل الأحداث بغير ترتيبها: اعتمد الحدث ذا data.updated_at الأحدث، أو استدعِ نقطة الاستعلام بعد الاستلام للحصول على أحدث حالة. بعد تعطيل الاستدعاء، لا تُرسَل الأحداث التي لم تُسلَّم بعد.

صفحات ذات صلة: التحقّق ومخاطر المعاملات · التحقّق من الهوية: الأفراد والشركات · مخاطر المعاملات: المراقبة وفحص المحافظ · وثائق الواجهة البرمجية