إشارات السياق

قبل أن تبدأ

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

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

تتم مصادقة طلبات API الخاصة بك باستخدام رمز وصول. أي طلب لا يتضمن رمز وصول صالحًا سيُعيد خطأ. تعرف على المزيد في المصادقة.

الوصول الخاضع للصلاحيات

يخضع الوصول إلى نقطة النهاية هذه لصلاحية (دور) مخصصة لشركتك. بدونها، تُعيد نقطة النهاية 403. اطلب التفعيل من فريق Unico.

Base URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• الإنتاج (Production): https://transactions.transactional.unico.app/api/public/v1

الحصول على إشارات السياق

GET /transactions/{transaction_id}/signals — يُعيد تقييم المخاطر لمعاملة مكتملة.

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

Path parameters

المعامل	النوع	إلزامي	الوصف
transaction_id	string	نعم	معرّف المعاملة (UUID v4). على سبيل المثال، 6ab1771e-dfab-4e47-8316-2452268e5481.

Headers

Header	القيمة
Authorization	Bearer {token} — رمز وصول صالح.
Accept	application/json

Request example

GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json

200 OK

{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

الحقل	النوع	الحضور	الوصف
signals.auto_fraud_risk	string (enum)	اختياري	مستوى مخاطر الاحتيال الذاتي. يظهر فقط عند اكتشافه.
signals.social_eng_risk	string (enum)	اختياري	مستوى مخاطر الهندسة الاجتماعية. يظهر فقط عند اكتشافه.
signals.more_info.limited_data	boolean	دائمًا	تكون القيمة true عندما لا تتوفر بيانات كافية لإجراء تقييم موثوق.
signals.more_info.holder_identified	boolean	دائمًا	تكون القيمة false عندما يتعذر تحديد هوية حامل البطاقة.

القيم الممكنة للمخاطر: very_low، low، medium، high، very_high.

معلومة

يستبعد كل من auto_fraud_risk وsocial_eng_risk الآخر — فهما لا يظهران معًا أبدًا في نفس الاستجابة. عندما تكون قيمة limited_data هي true، من المتوقع أن يغيب كلا حقلي المخاطر، نظرًا لعدم توفر بيانات كافية لإجراء التقييم.

Response examples

تم اكتشاف مخاطر هندسة اجتماعية:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

لم يتم تحديد أي مخاطر — معاملة عادية:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

بيانات غير كافية:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

لم يتم تحديد هوية حامل البطاقة:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}

Other response codes

تُعاد الأخطاء بتنسيق الخطأ القياسي الموضح في الأخطاء.

رمز HTTP	الرمز	الموقف	ماذا تفعل
202	—	لم يتم حساب النتيجة بعد — المعالجة غير المتزامنة لا تزال جارية.	كرر الاستدعاء (polling) حتى تحصل على 200.
400	40004	قيمة transaction_id غير صالحة (ليست UUID v4) أو أن أحد المعاملات مشوّه.	صحّح تنسيق المعرّف قبل إرسال الطلب مرة أخرى.
403	40305	لا تمتلك الشركة الصلاحية (الدور) المفعّلة لهذه النقطة النهائية.	اطلب التفعيل من فريق Unico.
404	40401	لم يتم العثور على المعاملة.	تحقق من معرّف المعاملة.
404	40484	لم يتم العثور على المعاملة لإجراء التقييم.	تعامل مع الأمر على أنه "لن تكون هناك نتيجة" وتوقف عن الاستعلام.
409	40983	لم تصل المعاملة إلى حالتها النهائية بعد.	انتظر وصولها إلى الحالة النهائية قبل الاستعلام مرة أخرى.
500	—	خطأ داخلي في الخدمة.	أعد المحاولة مع تأخير تصاعدي (backoff). إذا استمر الخطأ، تواصل مع دعم Unico.

القواعد وأفضل الممارسات

• استعلم عن نقطة النهاية فقط بعد وصول المعاملة إلى حالتها النهائية. الاستعلام قبل ذلك يُعيد 409.
• يتم تقييم معاملات الائتمان فقط. المعاملات التي تُلتقط في الوضع الصامت (silent mode) لا تخضع للتقييم.
• عند استلام 202، كرر الاستدعاء حتى تحصل على 200. أرسل الطلب الأول بعد ثانية واحدة من استجابة المعاملة، ثم طبّق تأخيرًا تصاعديًا: 2 ثانية، 4 ثوانٍ، 8 ثوانٍ، 16 ثانية — بحد أقصى 5 محاولات.
• هدف مستوى الخدمة هو 10 ثوانٍ بعد استجابة المعاملة.
• تعامل مع 404 على أنه "لن تكون هناك نتيجة" وتوقف عن الاستعلام.
• auto_fraud_risk وsocial_eng_risk يستبعد كل منهما الآخر.