مرجع واجهة فحص AML

مرجع واجهة فحص AML: افحص العملاء والأطراف المقابلة مقابل العقوبات والأشخاص السياسيين المعرضين للمخاطر وقوائم المراقبة عند التسجيل والدفع.

تنزيل Markdown

الأدلة مرجع API أمثلة الكود أفضل الممارسات

واجهة مكافحة غسل الأموال

فحص الكيانات مقابل قوائم العقوبات وقوائم المراقبة، وإرسال أحداث AML ومتابعة نتائجها.

الطريقة	المسار	الاستخدام
POST	/api/v1/aml/events	إرسال حدث AML لمراقبة معاملة أو طرف مقابل
GET	/api/v1/aml/events/:externalEventId	متابعة حالة الحدث باستخدام المعرّف الخاص بك
POST	/api/v1/aml/screen	فحص اسم فرد أو منظمة أو سفينة أو طائرة
GET	/api/v1/aml/screenings/:id	قراءة نتيجة فحص باستخدام معرّفه

فحص كيان

الحقل	النوع	مطلوب	الوصف
inputName	string	نعم	الاسم القانوني الكامل للكيان
externalId	string	نعم	معرف الكيان داخل نظامك
entityType	enum	لا	INDIVIDUAL أو ORGANIZATION أو VESSEL أو AIRCRAFT
inputDob	date	لا	تاريخ الميلاد بصيغة ISO 8601
inputNationality	string	لا	رمز الدولة ISO 3166-1 alpha-2
inputAliases	string[]	لا	الأسماء البديلة والتهجئات المعروفة
inputIdDocuments	object[]	لا	مستندات الهوية، كل منها بصيغة type وvalue
sensitivityProfile	enum	لا	CONSERVATIVE أو BALANCED أو LIBERAL

POST /api/v1/aml/screen

curl -X POST https://api.naiza.ai/api/v1/aml/screen \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputName": "John Michael Smith",
    "externalId": "cust_123456",
    "entityType": "INDIVIDUAL",
    "inputDob": "1985-04-12",
    "inputNationality": "GB"
  }'

Screening response

{
  "id": "scr_abc123",
  "externalId": "cust_123456",
  "decision": "REVIEW",
  "processingMs": 142,
  "listsHit": ["OFAC_SDN"],
  "matches": [{
    "watchlistEntityId": "wl_987",
    "score": 92,
    "classification": "STRONG",
    "matchedName": "John Michael Smith",
    "entityName": "John M. Smith",
    "source": "OFAC_SDN",
    "sanctionReason": "Designated sanctions reason",
    "matchCity": "Damascus",
    "datesOfBirth": ["1965-03-12", "1965"],
    "scoreBreakdown": { "name": 0.95, "dob": 0.8 }
  }],
  "caseId": "case_123",
  "alertId": "alert_123",
  "caseCreated": true,
  "reusedExistingCase": false
}

قد تكون datesOfBirth تاريخًا كاملًا yyyy-mm-dd أو سنة فقط yyyy. تظهر الحقول الاختيارية caseId وalertId وcaseCreated وreusedExistingCase عند إنشاء حالة أو ربط تنبيه بحالة مفتوحة.

أحداث AML والمتابعة

الحقل	النوع	مطلوب	الوصف
eventName	string	نعم	اسم الحدث كما تحدده منشأتك، مثل payment.completed
externalEventId	string	نعم	معرّف فريد داخل حساب المنشأة، يُستخدم للاستعلام ولإعادة المحاولة بأمان. إرسال المعرّف نفسه بالبيانات نفسها يعيد النتيجة المحفوظة، وإرساله ببيانات مختلفة يعيد 409. هذه الآلية مستقلة عن ترويسة Idempotency-Key؛ وعند انتهاء المهلة استعلم عبر GET /api/v1/aml/events/:externalEventId. أما الفحص المتزامن فلا يوجد له مفتاح مماثل؛ استخدم GET /api/v1/aml/screenings/:id إذا كان لديك معرّف الفحص.
eventCategory	enum	لا	CUSTOMER أو ACCOUNT أو APPLICATION أو CONTRACT أو TRANSACTION أو PAYMENT_INSTRUMENT أو COUNTERPARTY
customer	object	لا	معرفات العميل وبيانات اختيارية مثل externalId وemail
sourceReportedAt	ISO / Unix	لا	وقت الحدث في النظام المصدر
reference	string	لا	مرجع خارجي للربط بنظامك
metadata	object	لا	المبلغ والعملة وبيانات المعاملة
custom_fields	object	لا	حقول إضافية خاصة بعملك، مثل counterparty_country

POST /api/v1/aml/events

{
  "eventName": "payment.completed",
  "eventCategory": "TRANSACTION",
  "externalEventId": "aml_evt_ext_123",
  "customer": { "externalId": "user_123456" },
  "sourceReportedAt": 1672520400,
  "metadata": { "amount": 99.99, "currency": "USD" },
  "custom_fields": { "counterparty_country": "US" }
}

JavaScript — poll AML event

async function pollAmlEvent(externalEventId) {
  const response = await fetch(
    `https://api.naiza.ai/api/v1/aml/events/${encodeURIComponent(externalEventId)}`,
    { headers: { 'x-api-key': process.env.NAIZA_API_KEY } },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.json();
}

استعلم عبر GET /api/v1/aml/events/:externalEventId أو استخدم Webhook. تكون الحالة CLEAR أو ALERTED، أما السجلات القديمة التي تحمل الحالة HELD فتُعامَل على أنها ALERTED.