ربط حالات التحقق بحالات منتجك

يجب أن يتغير وضع منتجك في حقل واحد:statusإنها نتيجة عملية تحقق، وتأخذ إحدى عشر قيمة، منnot_startedلapproved. محلcheckStatusبجانبه، لأنه يسجل ما توصلت إليه الفحوصات الآلية، وهو التفسير الوحيد الذي ستملكه عندما يختلف الاثنان. يختلفان أكثر مما يتوقعه المهندسون، وهذا مقصود.

عملياً، هذا يعني ثلاثة أشياء: رسم خريطة لكل من العشرةstatusقم بتعيين القيم إلى حالة واحدة فقط في نظامك الخاص، واعتمد أحدثها.statusمنverification.status_updatedاستخدم webhook أو من خلال الاستقصاء بدلاً من الحدث الأول الذي تتلقاه، واستخدمreasonCode(لا يُعتمد على الحالة الأولية وحدها أبدًا) لتحديد ما يجب إخبار المتقدم به. بقية هذه المقالة تُحوّل ذلك إلى جدول يمكنك اعتماده ورمز يمكنك تعديله.

لماذا يوجد حقلان بدلاً من حقل واحد؟

لأن هناك عاملين مختلفين يحددان عملية التحقق. تقوم عمليات الفحص الآلية بقراءة المستند، والاستعلام عن السجل الحكومي، ومطابقة الوجه، وقراءة الشريحة. بعد ذلك، تحدد قواعد اتخاذ القرار في سير العمل، أو أحد أعضاء الفريق، الإجراء المناسب بشأن الشخص. وتخصص وثائق دورة حياة التحقق (يفتح في علامة تبويب جديدة) حقلاً مستقلاً لكل سؤال.

statusيتم تحديدها بترتيب ثابت، والقاعدة الأولى التي يتم تطبيقها هي التي تفوز: قرار المراجع، ثم قرار سير العمل الخاص بك، ثم عمليات التحقق وحدها.checkStatusلا يتغير شيء بسبب قاعدة أو مُراجع. لذا، فإن المتقدم الذي لم تتطابق ملامحه مع ملامح المتقدم، ولكن تمت الموافقة عليه من قِبل مُراجع بعد مكالمة فيديو، ينتهي به الأمر بـstatus: "approved"وcheckStatus: "failed"كلاهما صحيح، وتخزين الأول فقط سيجعلك غير قادر على شرح سبب السماح بالاستثناء لاحقًا.

كيف ينبغي أن يرتبط كل وضع بمنتجك؟

هذا مخطط توضيحي لتطبيق إقراض. حالات الحساب والرسائل هي أمثلة؛ أما الأعمدة الموجودة على اليمين فهي الجزء الذي يجب نسخه.

هناك خياران تصميميان في ذلك الجدول يستحقان النسخ حتى لو قمت بإعادة تسمية كل ولاية.

أولاً، حالة واحدة لكل قيمة، حتى عندما تبدو قيمتان متشابهتين . من المغري طيّها.in_reviewداخلprocessingلأن كليهما يعني "انتظر". أبقِهما منفصلين:in_reviewيعني ذلك أن أحد أعضاء فريقك مدين باتخاذ قرار، وهو مقياس داخلي لقائمة الانتظار، بينماprocessingهل تعمل المنصة؟

ثانية،declinedهي حالة واحدة، مع وجود السبب المصاحب لها . الهوية التي لا تحتوي عليها قاعدة بيانات الحكومة هيdeclinedمعreasonCode: "identity_not_found"ليس وضعاً منفصلاً. يجب التركيز على الكود، وليس على انتشار الحالات.

ما الذي تنتظره عملية المعالجة فعلياً؟

عادةً، تقتصر العملية على عمليات التحقق فقط. ولكن عندما يتأخر سير العمل في اتخاذ القرار بشأن أمر ما،processingيمكن أن يستمر لفترة أطول، وتشمل نقطة نهاية الحالةwaitingOnبمعنى آخر. تشمل القيم"screening"(العقوبات، PEP أو فحص وسائل الإعلام السلبية) و"key_people"(المديرون والمالكون في تطبيق تجاري ينهون عمليات التحقق الخاصة بهم)؛nullهذا يعني أن عمليات التحقق لا تزال جارية. ويعرض مرجع نقطة نهاية الحالة (يفتح في علامة تبويب جديدة) هذه العمليات.

هذا الحقل هو ما يسمح لفحص المتقدمين بقول شيء أكثر فائدة من مجرد مؤشر تحميل، ويتيح لفريق العمليات لديك معرفة سبب رفض طلب العمل.processingلمدة يومين.

لماذا لا تكون عبارة "verification.completed" هي الإجابة النهائية دائمًا؟

لأنها تصف عمليات التحقق، وليس القرار. الأحداثverification.completed،.failed،.not_foundو.errorيتم إرسالها فور انتهاء عمليات التحقق. إذا كان سير العمل الخاص بك يحتوي على قواعد اتخاذ قرار، فهذا يعني قبل أن يتخذ سير العمل قراره، وstatusيعكس ذلك عمليات التدقيق وحدها.

يصدر الحكم لاحقاًverification.status_updated، معsource: "workflow"يتم تشغيل الحدث نفسه أيضًا عندما يقرر المراجع ذلك في لوحة التحكم (source: "dashboard") أو يقرر نظامك الخلفي ذلك من خلال المراجعة API (source: "api"). يحملpreviousStatusوالجديدstatusوعلى عكس معظم الفعاليات، يتم تسليمها مسطحة بدلاً من أن تكون مغلفة.dataالكائن، كما توضح وثائق webhooks (يفتح في علامة تبويب جديدة) .

يُوضّح مثال عملي الفخّ بشكل ملموس. يرفض نظام العمل أي شخص لديه تطابق مؤكد مع قائمة المراقبة. يجتاز المتقدم جميع الفحوصات:verification.completedيأتي معstatus: "approved"وبعد ثوانٍ، ينتهي انتظار الفحص ويتراجع سير العمل، لذاverification.status_updatedيأتي معstatus: "declined"وsource: "workflow"إذا قام المسؤول عن معالجة الطلبات بتسجيل العميل في الحدث الأول، فهذا يعني أنك قمت بتسجيل شخص ترفضه سياستك الخاصة.

القاعدة: إذا كانت عملية سير العمل لديك تتضمن قواعد اتخاذ القرار، فتعامل معهاverification.status_updated(أو استطلاع رأي جديد) كمصدر لـstatusبدون قواعد اتخاذ القرار، تصبح الضوابط هي القرار وverification.completedيُعتبر هذا التقييم نهائياً ما لم يقم أحد المراجعين بتغييره لاحقاً.

ما الذي يجب أن تخبر به المتقدم؟

يستخدمreasonCodeلاختيار الرسالة، واستخدامreasonبعناية.

فيfailedأوnot_foundيفحص،reasonيُكتب هذا التقرير للمتقدم بلغة بسيطة توضح أوجه الاختلاف والخطوات التالية، دون تحديد درجة أو حد أدنى أو الرجوع إلى سجلات الحكومة. يمكنك عرضه كما هو.

فيerrorحصيلة،reasonمكتوب خصيصًا لك. قد يقول "اشحن رصيدك" أو "اتصل بنا" Toden وهذا لا يعني شيئًا للمتقدم. اعرض عليه رسالة عامة وقم بتوجيههاreasonإلى فريقك.

قد تتم إضافة رموز جديدة بمرور الوقت، لذا قم بربط الرمز غير المعروف برسالة فشل عامة بدلاً من ربطه بخطأ في التعليمات البرمجية الخاصة بك.

كيف يبدو هذا في الكود؟

معالج يطبق القواعد المذكورة أعلاه، بلغة تايب سكريبت.accountsالمكالمات هي مجرد عناصر نائبة لمثابرتك الخاصة.

type Status =
  | 'not_started' | 'in_progress' | 'processing' | 'in_review'
  | 'awaiting_resubmission' | 'approved' | 'declined'
  | 'abandoned' | 'expired' | 'error';

const ACCOUNT_STATE: Record<Status, string> = {
  not_started: 'kyc_invited',
  in_progress: 'kyc_in_progress',
  processing: 'kyc_checking',
  in_review: 'kyc_manual_review',
  awaiting_resubmission: 'kyc_action_needed',
  approved: 'kyc_passed',
  declined: 'kyc_failed',
  abandoned: 'kyc_dropped',
  expired: 'kyc_link_expired',
  error: 'kyc_retry',
};

export async function applyVerificationStatus(event: {
  verificationId: string;
  status: Status;
  checkStatus?: string;
  reasonCode?: string | null;
  reason?: string | null;
}) {
  const state = ACCOUNT_STATE[event.status] ?? 'kyc_checking'; // unknown value: keep waiting
  await accounts.updateByVerificationId(event.verificationId, {
    kycState: state,
    kycStatus: event.status,
    kycCheckStatus: event.checkStatus ?? null, // the explanation, kept for audit
    kycReasonCode: event.reasonCode ?? null,
    kycReason: event.reason ?? null,
  });
}

يمكن تسميته من كلا الجانبينverification.status_updatedيجب ربط معالج البيانات ومسار الاستقصاء الخاص بك، حتى لا ينحرف أحدهما عن الآخر. قم بإزالة عمليات تسليم Webhook المكررة علىX-Myaza-Deliveryقم بتمرير رأس الصفحة قبل استدعائها.

ماذا يحدث عند إرسال رد التحقق؟

يحتفظ النظام برقم تعريفه. عندما يُرسل المراجع تأكيدًا ويعيد مقدم الطلب تقديم الطلب، يبدأ نفس التأكيد محاولة جديدة:attemptيرتفع بمقدار واحد،checkStatusالعودة إلىpendingثم تُعاد عمليات التحقق. تتعامل عملية الربط الخاصة بك مع هذا الأمر دون حالات خاصة: ينتقل الوضع منawaiting_resubmissionلprocessingثم يستقر الوضع مرة أخرى. إدخال سجلاتك علىverificationId، وليس على استعلام "آخر تحقق لهذا المستخدم"، هو ما يجعل ذلك يعمل.

للحصول على الصورة الكاملة، بما في ذلك كل محاولة سابقة وكل قرار، اقرأGET /api/kyc/verifications/:idمن خادمك الخلفي باستخدام مفتاح سري. ثم يُعيدreviewوstatusHistory، الأحدث أولاً، كما هو موضح في مرجع نتيجة التحقق (يفتح في علامة تبويب جديدة) .

قائمة التحقق

• حالة منتج واحدة لكلstatusقيمة، معin_reviewوprocessingتم إبعادهم عن بعضهم البعض.

• checkStatus،reasonوreasonCodeمخزنة بجوارstatus، دائماً.

• أحدثstatusمقتبس منverification.status_updatedأو إجراء استطلاعات الرأي عندما تتضمن سير العمل الخاص بك قواعد اتخاذ القرار.

• نسخة مقدم الطلب المختارة من قبلreasonCode؛reasonيعرض فقط علىfailedوnot_found.

• مجهولstatusأوreasonCodeيتم التعامل مع القيم على أنها "استمر في الانتظار" أو "فشل عام"، وليس على أنها عطل.

• تم تسجيل المفاتيحverificationIdلذا فإن عمليات إعادة الإرسال تُحدّث نفس الصف.

يربط مركز المطورين بين روابط الويب هوك ومراجع الحالة المستخدمة هنا.