إرسال الأحداث لتقييم المخاطر في الوقت الفعلي: دليل التكامل

للحصول على قرار بشأن المخاطر في الوقت الفعلي، يقوم نظامك الخلفي بإجراء مكالماتPOST /api/v1/transactionsلكل عملية دفع أو تحويل أو إيداع أو سحب، وPOST /api/v1/activitiesلكل عملية تسجيل دخول، أو إنشاء حساب، أو إعادة تعيين كلمة المرور، أو تغيير المستفيد، أو أي حدث مشابه في الحساب. كل استدعاء يُعيد قرارًا في نفس الطلب:allow،reviewأوblockمع تحديد النتيجة، وأقوى سبب، والخطوة التالية المقترحة. يقوم الكود الخاص بك بتقييد الإجراء بناءً على هذا القرار.

ثلاثة عوامل تحدد مدى جودة التكامل: الاتصال في الوقت المناسب (قبل تحويل الأموال، وليس بعده)، وإرسال معلومات كاملة عن المرسل والمستلم، واستخدام معرّفات ثابتة لتجنب إعادة التقييم عند إعادة المحاولة. يغطي هذا الدليل كل عامل من هذه العوامل، مع نماذج الطلبات من وثائق مراقبة الأحداث (يفتح في علامة تبويب جديدة) .

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

إلى أي نقطة نهاية ينتمي كل حدث؟

نشاطtypeهي قائمة مغلقة:login،signup،password_reset،beneficiary_added،profile_change،device_change،payoutوwithdrawalتؤكد الوثائق بشكل قاطع أن تحويل الأموال مع إثبات المرسل والمستلم يتم عبر نقطة نهاية المعاملات، وليس عبر نقطة نهاية النشاط.payout.

أين يجب أن يكون موضع المكالمة في مسار العمل الخاص بك؟

بين تأكيد العميل والخطوة غير القابلة للتراجع. لنأخذ مثالاً توضيحياً لتحويل بنكي صادر في تطبيق محفظة إلكترونية:

1. يؤكد العميل تحويل الأموال إلى مستفيد جديد.

2. يقوم نظامك الخلفي بإرسال المعاملة وينتظر الرد.

3. يقوم بتوجيه البياناتassessment.summary.outcome.

4. حصرياً علىallowهل يقوم بتحويل الدفعة إلى سكة حديد البنك؟

يُعدّ تسجيل النقاط بعد دفع المبلغ بمثابة مراقبة، لا تزال ذات قيمة للتحقيقات، لكنها لا تمنع الخسارة. إذا كان القرار هو منع أي شيء، فيجب أن يتم ذلك أولاً. Toden يقوم بإرجاع قرار؛ فهو لا يحظر الحسابات في تطبيقك، لذا فإن البوابة هي التعليمات البرمجية الخاصة بك.

كيف يبدو الطلب الأول؟

تستخدم جميع استدعاءات تحليل المخاطر مفتاحًا سريًا من نظامك الخلفي:sk_test_ضدhttps://sandbox-api.toden.co/api/v1،sk_live_ضدhttps://api.toden.co/api/v1. Node.js الرسمي SDK يكون@myazahq/trust-sdk( ESM (خاص بـ Node.js 20 أو أحدث)، ويختار المضيف منenvironmentخيار. من دليل البدء السريع لمعلومات المخاطر (يفتح في علامة تبويب جديدة) :

import { Myaza } from '@myazahq/trust-sdk';

const myaza = new Myaza({
  apiKey: process.env.MYAZA_SECRET_KEY,
  environment: 'sandbox',
});

const assessment = await myaza.transactions.create({
  externalActivityId: 'activity_txn_10001',
  subject: { type: 'individual', externalUserId: 'user_42' },
  occurredAt: new Date().toISOString(),
  transaction: {
    externalTransactionId: 'txn_10001',
    assetClass: 'fiat',
    direction: 'outbound',
    amount: '48000.00',
    currency: 'NGN',
    transactionType: 'bank_transfer',
  },
}, { idempotencyKey: 'transaction-txn_10001' });

console.log(assessment.summary?.outcome, assessment.summary?.reason);

لاحظ أنamountهو سلسلة. API يأخذ سلسلة عشرية موجبة تصل إلى ثمانية منازل عشرية، لذلك لا يتم تقريب الأموال أبدًا من خلال رقم الفاصلة العائمة عند إدخالها.

هذا الطلب صحيح، ولكنه غير مكتمل، والقسم التالي يوضح سبب أهمية ذلك.

لماذا تُعدّ الأحزاب مهمة للغاية؟

لأن الفحص يعتمد عليهم. المعاملةdirectionدائماً ما يكون ذلك من وجهة نظر العميل، و Toden يقوم بفحص الجانب الآخر من الحركة قبل اتخاذ القرار:

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

هذا هو السلوك الصحيح، ويعني أن التكامل البسيط ينتج عنه قائمة انتظار مراجعة مزدحمة. أرسلpartiesمجموعة. يحتاج كل طرف إلىrole(sender،recipient،customerأوcounterparty)، مرجع واحد مستقر (externalUserId،entityIdأوexternalPartyId)، ولفحص العملات الورقية الخارجية أdisplayNameأرفق الحساب أو المحفظة التي استخدمها كل طرف كأداة:

{
  "role": "recipient",
  "externalPartyId": "beneficiary_998877",
  "type": "individual",
  "displayName": "Amina Bello",
  "country": "NG",
  "instruments": [
    {
      "type": "bank_account",
      "externalInstrumentId": "beneficiary_account_998877",
      "identifier": "9988776655",
      "institutionName": "Recipient Bank",
      "country": "NG",
      "currency": "NGN"
    }
  ]
}

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

كيف يمكنني إرسال تقرير عن نشاط الحساب؟

نفس الظرف بدونtransactionكتلة، بالإضافة إلىtypeتسجيل الدخول عبر HTTP :

curl -X POST "https://sandbox-api.toden.co/api/v1/activities" \
  -H "Authorization: Bearer $MYAZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalActivityId": "login_10001",
    "subject": { "type": "individual", "externalUserId": "user_42" },
    "type": "login",
    "occurredAt": "2026-08-16T09:30:00.000Z",
    "channel": "mobile_app",
    "deviceRef": "device_7f53",
    "ipAddress": "102.89.12.34",
    "country": "NG",
    "customAttributes": { "trustedDevice": false, "failedAttemptsBeforeSuccess": 2 }
  }'

يحمل حقلان معظم القيمة.deviceRefهو مرجع جهازك الثابت الخاص بك؛ إعادة استخدامه تبني تاريخ الجهاز وهو ما يجعل إشارة الجهاز الجديد تعني أي شيء.ipAddressيجب أن يكون عنوان المستخدم النهائي .API لا يستبدل عنوان IP الخاص بخادمك، لذلك إذا كان نظامك الخلفي يقوم بإعادة توجيه المكالمة، فقم بتمرير عنوان العميل الذي لاحظته، وليس عنوانك الخاص.

أرسل فقط الأدلة التي جمعتها بنفسك. يجب تقديم خطوط الطول والعرض معًا، ويبقى الموقع الذي تقدمه هو الموقع الأساسي بغض النظر عن أي معلومات مستنتجة من عنوان IP.

كيف ينبغي عليك قراءة الرد؟

يقرأassessment.summaryأولاً. إنه يحملoutcome،title،reason،score،riskLevel،matchedRulesوnextActionوهذا يكفي للتوجيه العادي. كما تتضمن الاستجابة نفسها قواعد المطابقة التفصيلية، وأدلة الفحص، وتفاصيل الفواتير عند إجراء أي تحقيق. المتجرdecisionIdوalertIdمقابل معاملتك الخاصة حتى يتمكن الموظف من العثور على الدليل لاحقًا.

استخدم قيم الجهاز (allow،review،block) في الكود واكتب نسختك الخاصة الموجهة للعميل، كما تنصح الوثائق، بدلاً من تمرير نص التقييم إلى العميل.

كيف تعيد المحاولة دون أن تُسجل هدفين؟

باستخدام معرّفات ثابتة:

• واحدexternalActivityIdلكل تقييم منطقي، يتم الحفاظ على تطابقه عبر جميع المحاولات. تُعيد إعادة التشغيل التقييم الحالي معreplayed: trueولا يسجلها أو يفوتها مرة أخرى.

• واحدexternalTransactionIdلكل معاملة عميل.

• إعادة استخدام أي من المعرفين مع بيانات ثابتة مختلفة ينتج عنها409(idempotency_conflictأوtransaction_id_conflictهذا خطأ في نظام التعريف الخاص بك، وليس شيئًا يجب إعادة المحاولة.

• أرسل النسخة الأصليةoccurredAtلا يمكن أن يكون ذلك بعد أكثر من خمس دقائق، و Toden يسجل كل من وقت الحدوث ووقت الاستلام، لذلك يظل الحدث المتأخر مرئيًا دون تشويه الجدول الزمني.

ماذا ينبغي أن يحدث عندما لا يتم التوصل إلى قرار؟

حدد هذا قبل الإطلاق، لأن السلوك الموثق هو الفشل عند الإغلاق. الأخطاء التي ستواجهها:

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

هل ما زلت بحاجة إلى روابط الويب؟

بالنسبة للعمليات، نعم. اشترك فيfraud.transaction.assessedوfraud.activity.assessedلتلقي كل قرار، وscreening.match،risk.signal.createdوalert.createdلاتخاذ الإجراءات اللازمة بناءً على النتائج. تحقق من كل توقيع مقابل النص الأصلي، وقم بإزالة التكرارات باستخدام معرّف الحدث.event.flaggedيبقى هذا الخيار مجرد اسم بديل للتوافق مع قرارات عدم السماح. إذا كنت تستخدمPOST /api/identity/events، خطط للانتقال إلى نقاط النهاية v1: يمكن للشكل القديم تسجيل حدث بسيط ولكنه لا يستطيع حمل الحفلات المنظمة أو الآلات الموسيقية.

قائمة التحقق

• مفتاح سري واستضافة معلومات المخاطر على الواجهة الخلفية فقط؛sk_test_مع مضيف Sandbox أثناء البناء.

• يتم استدعاء المعاملات قبل تحويل الأموال؛ البوابة هي رمزك.

• partiesمع ذكر الأسماء أو المحافظ للجانب المحمي من كل حركة.

• عنوان IP الخاص بالمستخدم النهائي وعنوان IP الخاص بك الثابتdeviceRefبشأن الأنشطة.

• مستقرexternalActivityIdوexternalTransactionId، إبداعيoccurredAt.

• قاعدة مكتوبة لما يحدث عندما لا يتوفر قرار.

• تم الاشتراك في Webhooks والتحقق منها وإزالة التكرارات.

تصف صفحة منتج مراقبة المعاملات القواعد وأدوات التحقيق التي تقف وراء هذه القرارات، ويربط مركز المطورين المراجع الكاملة.