الوصول
- مساحة عملك مفعّلة لواجهة KYC للشركاء. في Settings, API Keys يعرض نموذج المفتاح الجديد نطاقات
kyc:. وإذا ذكر أن مساحة العمل غير مفعّلة، فاطلب الوصول إلى بيئة الاختبار: يتم التفعيل لكل مساحة عمل من قِبل Sahl. - مفتاح واحد لكل نظام، بأقل النطاقات. الخادم الذي يتحقق فقط يحتاج إلى
kyc:verify. وkyc:extractوحده يستهلك القراءات. - المفاتيح محفوظة في مدير أسرار على خادمك. لا مفتاح في متصفح أو تطبيق جوال أو مستودع شيفرة. انظر المصادقة.
- بدّلت مفتاحًا مرة واحدة في بيئة الاختبار. بدّل مع فترة سماح، وانشر المفتاح البديل، وتأكد أن المفتاح القديم يُرجع 401
API key expiredبعد انتهاء فترة السماح. - أُبطلت مفاتيح الاختبار. المفاتيح التي لصقتها في ساحة التجربة أو في Postman للاختبار أُبطلت في قائمة المفاتيح.
- اختياري: المفاتيح مرتبطة بحساب خدمة Google الخاص بك. عندئذٍ يرسل كل استدعاء
X-Partner-Identity.
السياسة
- توجد سياسة KYC لبيئة
productionإن أردت قواعد غير الافتراضية. تُحفظ السياسة لكل نوع عميل ولكل بيئة، فلا تنتقل سياسة بيئة الاختبار. راجعها في Settings, KYC policy: العتبات والمستندات المطلوبة والبنود المقفلة. - تعرف المفاتيح المقفلة. أرسل استدعاءً بـ
screen: falseفي بيئة الاختبار واقرأpolicy.overrides_refusedفي الاستجابة. - الإعداد المسبق للنظام التنظيمي هو ما تتوقعه. يخبرك
policy.sourceوpolicy.regimeفي الاستجابة بالسياسة التي طُبّقت.
التكامل
- كل استدعاء يحمل
referenceثابتًا. من 1 إلى 64 حرفًا منA-Z a-z 0-9 _ . : -، واحد لكل عميل، وهو نفسه في/extractو/verifyو/assessو/eid. وبدونه لا يُحفظ شيء في مساحة عملك ولا يُرسل webhook. - تعيد إرسال عناصر
documents[]دون تغيير. انظر كيف تترابط الاستدعاءات. - تتفرع بحسب
critical_failuresوflags، لا بحسبpassedفقط. الملف الذي فيه تنبيهات تبقى قيمةpassedفيهtrue. - تطابق الفحوص بحسب
idلا بحسبlabel. - تعالج
reader_unavailable: true. أعد المحاولة لاحقًا ولا تعامله كمستند فارغ. - تعالج أشكال الأخطاء الثلاثة جميعها، بما فيها 422 التي يكون
detailفيها قائمة. انظر الأخطاء. - لا تعيد محاولة 4xx (باستثناء 429 لحد المعدل مع
Retry-After)، وتعيد محاولة 5xx بتراجع زمني محدود السقف. لا يوجد مفتاح idempotency. انظر إعادة المحاولة. - تسجّل
X-Request-IDمن كل استجابة، وتستطيع العثور على الاستدعاء في Developers, Call log.
الحدود
- تعرف حصة القراءة الشهرية لديك (2,000 افتراضيًا) وتعالج 429
kyc_extract_cap_reached. وتُحتسب منها قراءات بيئة الاختبار أيضًا. - تبقى خوادمك دون 100 طلب في الدقيقة لكل IP للعميل. الخوادم خلف عنوان واحد تتشارك الحد.
- خطوة الرفع لديك تفرض قواعد الملفات قبل الإرسال: من 1 إلى 5 ملفات، JPEG أو PNG أو WebP أو TIFF أو PDF، بحد 30 MB لكل ملف افتراضيًا.
Webhooks، إن كنت تستخدمها
- نقطة النهاية https وعامة. أضفها في Settings, Webhooks واضغط Test.
- تتحقق من
X-Sahl-Signature-V2على الجسم الخام وترفض الطوابع الزمنية القديمة. انظر Webhooks. - معالجك idempotent بالاعتماد على
X-Sahl-Deliveryأوevent_id، ويرد بـ 2xx سريعًا.
eID، إن كنت تستخدمه
- لدى مساحة عملك حساب لدى مزوّد eID. بدونه يُرجع
POST /v1/kyc/eidالحالة 404. - عملاؤك كنديون. الدول الأخرى تحصل على 422.
- تستخدم
referenceوenvironmentنفسيهما في/eidوفي/verifyاللاحق. - تتابع الفحص بالاستعلام الدوري حتى نهايته وتحفظ ملف PDF خلال نحو سبعة أيام.
وحدة التحكم
- يستطيع موظفوك رؤية بيانات الإنتاج. تعرض وحدة التحكم قضايا ومستندات الإنتاج في كل الخطط. تتيح خطة Free عشر (10) قضايا إنتاج شهريًا وتتطلب بريدًا إلكترونيًا مهنيًا موثّقًا (وليس Gmail أو Yahoo)؛ وتحصل Starter وما فوقها على حصة خطتها. وبيئة الاختبار غير محدودة في جميع الخطط.
- أرسلت أول استدعاء إنتاج بعميل وهمي ووجدت قضيته في Cases بالبيئة
production. - المستندات الحقيقية تذهب إلى الإنتاج فقط. استخدم بيانات وهمية في بيئة الاختبار.