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

نقاط نهاية فحص العقوبات والأشخاص المعرّضين سياسيًا وقوائم المراقبة.

الأدلة مرجع 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 (مع APPROVED/REJECTED كحالات كتابة مستقبلية).