KYC Magic Link

عقد إقليمي منفصل

لا تستخدم حالة الاستخدام هذه نقطة نهاية Unico POST /v1/process ولا عقد API/TCA. التكامل مع Trully.ai (المضيف api.trully.ai)، مع المصادقة عبر x-api-key بدلاً من Bearer JWT، وبـ مخطط استجابة خاص. بالنسبة للدول الأخرى، استخدم Onboarding (العالمي).

ما الذي تحله حالة الاستخدام هذه

يعالج KYC Magic Link تحدي تنفيذ عملية التعرف على الهوية في المكسيك، من خلال جمع وثائق الهوية الوطنية (INE) والبيانات البيومترية للوجه. مع رحلة مُستضافة من Unico، تُزيل عقبات تطوير الواجهة الأمامية عبر رابط يُرسَل عبر قنواتك الخاصة (واتساب، رسائل SMS، بريد إلكتروني).

استخدم حالة الاستخدام هذه عندما:

تعمل في المكسيك ووثيقة الهوية المستخدمة هي INE (إلزامية).

لا تستخدم حالة الاستخدام هذه عندما:

يكون المستخدم خارج المكسيك أو يستخدم وثائق أخرى ← انظر حالات استخدام التسجيل الأخرى.

القدرات المعتمدة

خط أنابيب يُنفَّذ ضمن عملية واحدة:

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

المتطلبات الأساسية

مفتاح API — يُوفّره مدير مشروع التأهيل لديك في Unico. يُرسَل في ترويسة x-api-key.
نقطة نهاية HTTPS عامة لاستقبال webhooks (اختيارية، لكن موصى بها).
إعداد CORS — السماح بالأصول https://verification.unico.app (الإنتاج) وhttps://verification.uat.unico.app (البيئة التجريبية) على الخادم الذي يستقبل webhook.

التطبيق خطوة بخطوة

على عكس حالات الاستخدام الأخرى، لا يحتوي Magic Link على حقل flow — التكامل مباشر مع Trully API. تُنشئ نقطة النهاية رابط تحقق فريداً تُوزّعه على المستخدم عبر قناتك الخاصة.

1. إنشاء Magic Link

نقطة النهاية: POST https://sandbox.trully.ai/v2/magic-link

الترويسات:

الترويسة	مطلوبة	الوصف
`x-api-key`	نعم	مفتاح API الذي وفّره مدير مشروع التأهيل لديك في Unico.
`Content-Type`	نعم	`application/json`

الجسم (application/json):

الحقل	النوع	مطلوب	الوصف
`external_id`	string	لا	معرّف خارجي للطلب، يُستخدم لأغراض التتبع والمرجعية.
`metadata`	object	لا	حاوية لمعاملات الإعداد.
`metadata.phone`	string	لا	رقم هاتف المستخدم بالصيغة الدولية (مثلاً: `521234567890`).
`metadata.redirect_url`	string	لا	رابط لإعادة توجيه المستخدم بعد اكتمال عملية KYC.
`metadata.webhook_url`	string	لا	رابط لإرسال بيانات عملية KYC بعد اكتمالها. سيُستدعى هذا webhook من جانب العميل. لأسباب أمنية يجب أن تستخدم نقطة النهاية HTTPS. ستنتظر المكوّن دقيقة واحدة لاستجابة خادم webhook — بعدها سيُنهي الاتصال. لن تتأثر العملية بأي شكل من أشكال التواصل عبر webhook. تأكد من السماح بـ `https://verification.unico.app` و`https://verification.uat.unico.app` في إعداد CORS الخاص بك للإنتاج والبيئة التجريبية على التوالي.
`metadata.track_webhook_url`	string	لا	رابط لإرسال كل خطوة من خطوات KYC التي يُنجزها المستخدم (انظر أحداث webhook أدناه). سيُستدعى هذا webhook من جانب العميل. لأسباب أمنية يجب أن تستخدم نقطة النهاية HTTPS. ستنتظر المكوّن دقيقة واحدة لاستجابة خادم webhook — بعدها سيُنهي الاتصال. لن تتأثر العملية بأي شكل من أشكال التواصل عبر webhook. تأكد من السماح بـ `https://verification.unico.app` و`https://verification.uat.unico.app` في إعداد CORS الخاص بك للإنتاج والبيئة التجريبية على التوالي.

data.step (تُرسَل إلى track_webhook_url) تُبلِّغ عن نفس الخطوات المُتتبَّعة بواسطة Webhook V2 — انظر جدول الخطوات المدعومة أدناه.

مثال على الطلب:

curl -X POST https://sandbox.trully.ai/v2/magic-link \
  -H "x-api-key: $TRULLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-mx-12345",
    "metadata": {
      "phone": "521234567890",
      "redirect_url": "https://app.client.com.mx/kyc-done",
      "webhook_url": "https://app.client.com.mx/webhook/result",
      "track_webhook_url": "https://app.client.com.mx/webhook/track"
    }
  }'

2. استقبال الرمز ورابط URL

حقول الاستجابة:

الحقل	النوع	الوصف
`data.external_id`	string (nullable)	معرّف خارجي للطلب، يُستخدم لأغراض التتبع والمرجعية.
`data.created_on`	string (date-time)	تاريخ إنشاء magic link.
`data.is_active`	boolean	إذا كانت القيمة `true`، فإن magic link نشط.
`data.token`	string	رمز magic link الذي سيُستخدم لربط عمليات KYC بـ magic link.
`data.magic_link_url`	string (URI)	رابط URL السحري لبدء عملية KYC.
`data.metadata.redirect_url`	string (nullable)	رابط لإعادة توجيه المستخدم بعد اكتمال عملية KYC.
`data.metadata.webhook_url`	string (nullable)	رابط لإرسال بيانات عملية KYC بعد اكتمالها. سيُستدعى هذا webhook من جانب العميل.
`data.metadata.track_webhook_url`	string (nullable)	رابط لإرسال كل خطوة من خطوات KYC التي يُنجزها المستخدم. سيُستدعى هذا webhook من جانب العميل.
`data.version`	string	إصدار magic link.
`version`	string	إصدار API الذي عالج الطلب، مفيد لتتبع التغييرات والتوافق.
`status`	string	تمثيل نصي لحالة الاستجابة، يُشير إلى نجاح العملية أو فشلها.
`status_code`	integer	رمز حالة HTTP للاستجابة، يُوفر مؤشراً معيارياً لنتيجة الطلب.
`request_date`	string (date-time)	تاريخ ووقت تقديم الطلب بصيغة ISO 8601.
`request.metadata.redirect_url`	string (nullable)	رابط إعادة توجيه المستخدم بعد اكتمال عملية KYC (صدى الطلب).
`request.metadata.webhook_url`	string (nullable)	رابط إرسال بيانات عملية KYC بعد الاكتمال (صدى الطلب).
`request.metadata.track_webhook_url`	string (nullable)	رابط إرسال كل خطوة من خطوات KYC التي يُنجزها المستخدم (صدى الطلب).

مثال على الاستجابة:

{
  "data": {
    "external_id": null,
    "created_on": "2025-07-28T18:11:54.430048399Z",
    "is_active": true,
    "token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
    "magic_link_url": "https://verification.uat.unico.app/link/v2/3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
    "metadata": {
      "redirect_url": null,
      "webhook_url": null,
      "track_webhook_url": null
    },
    "version": "v2"
  },
  "version": "v1.4.2",
  "status": "ok",
  "status_code": 200,
  "request_date": "2025-07-28T18:11:54+0000",
  "request": {
    "metadata": {
      "redirect_url": null,
      "webhook_url": null,
      "track_webhook_url": null
    }
  }
}

استجابات الخطأ — POST /v2/magic-link

الرمز	الرسالة	الوصف
`400 Bad Request`	`data provided in the field is invalid`	هيكل بيانات غير صالح أو قيم حقول غير صحيحة في حمولة الطلب. تحقق من الحقول المطلوبة والصيغ.
`403 Forbidden`	`Forbidden`	مفتاح API مفقود أو منتهي الصلاحية أو بدون صلاحية. تحقق من ترويسة `x-api-key`.
`500 Internal Server Error`	`internal server error`	فشل في المعالجة على جانب الخادم. أعد المحاولة مع تراجع أسي. إذا استمر الأمر، أبلغ الدعم.

مثال على استجابة 400:

{
  "data": {
    "error": "data provided in the field is invalid"
  },
  "version": "v1.4.2",
  "status": "bad request",
  "status_code": 400,
  "request_date": "2025-07-28T20:22:29+0000",
  "request": {
    "metadata": null
  }
}

3. توزيع magic_link_url على المستخدم

أرسل عبر واتساب أو رسائل SMS أو بريد إلكتروني أو ادمجه. يصل المستخدم إلى الرابط على جهازه الخاص ويُكمل الرحلة المُستضافة.

إذا كنت تفضّل تضمين الرحلة داخل تطبيقك الخاص بدلاً من فتح الرابط في المتصفح، يمكنك القيام بذلك عبر WebView أو CustomTab. أمثلة مرجعية (PoC):

Android/Kotlin: TrullyAi-AndroidMagicLink
React Native: TrullyAI-ReactNativeMagicLink

4. استقبال النتيجة

لديك مرونة كاملة لتقرير كيفية استقبال النتيجة النهائية لعملية KYC — اختر الاستراتيجية الأنسب لبنية نظامك. يمكنك الاستطلاع الفعّال عن النتيجة (GET) أو استقبالها بشكل سلبي عبر الإشعارات (Webhook).

الخيار أ — الاستطلاع الفعّال عبر GET

استرجع النتيجة عبر استدعاء GET /v2/history/request?magic_link_token={token} (انظر الاستطلاع عبر GET أدناه). يُملأ القرار النهائي في data.response.unico.result.

أفضل ممارسة لـ GET

بدلاً من الاستطلاع الدوري منذ لحظة إنشاء الرابط، استخدم webhooks التتبع (انظر Webhook V2 أدناه) لمعرفة اللحظة الدقيقة للاستعلام. بمجرد استقبال خطوة form_decision_maker، تكون تلك هي اللحظة الدقيقة والآمنة لتنفيذ استدعاء GET هذا.

الخيار ب — الاستقبال التلقائي عبر Webhook

اجعل نظامك يتلقى إشعاراً تلقائياً بمجرد جاهزية النتيجة النهائية (انظر Webhook V2 أدناه). إصداران متاحان:

Webhook V1 — تستقبل النتيجة على الرابط المُرسَل في metadata.webhook_url عند إنشاء الرمز.
Webhook V2 — يُضبط مسبقاً مع مدير مشروع التأهيل لديك. تستقبل الحكم النهائي عبر الاستماع إلى حدث MAGIC_LINK_RESULTS.

المرونة — الحل الاحتياطي

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

الاستطلاع عبر GET

نقطة النهاية: GET https://sandbox.trully.ai/v2/history/request

معاملات الاستعلام:

المعامل	النوع	مطلوب	الوصف
`magic_link_token`	string	نعم	الرمز الذي أُعيد عند إنشاء Magic Link.

الترويسات:

الترويسة	مطلوبة	الوصف
`x-api-key`	نعم	مفتاح API الذي وفّره مدير مشروع التأهيل لديك في Unico.

مثال على الطلب:

curl "https://sandbox.trully.ai/v2/history/request?magic_link_token=$TOKEN" \
  -H "x-api-key: $TRULLY_API_KEY"

مثال على الاستجابة:

{
  "data": {
    "images": {
      "document_image": "/9j/4ASu7bmV[...]fyPjOKfgif//Z",
      "document_image_back": "/9j/4ASu7bmV[...]fyPjOKfgif//Z",
      "selfie": "/9j/4ASu7bmV[...]fyPjOKfgif//Z"
    },
    "response": {
      "curp": {
        "age": 58,
        "curp": "GOCJ850627HDFRRL09",
        "date_of_birth": "14/11/1956",
        "deceased": false,
        "gender": "M",
        "government_name": "LUKE SKYWALKER",
        "government_valid": true,
        "is_mexican": true,
        "name_to_CURP_valid": true,
        "state_iso": "MX-NLE",
        "state_of_birth": "Nuevo León"
      },
      "document": {
        "back": {
          "cic": "237457894",
          "citizen_id": "237457894",
          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE"
        },
        "details": {
          "detected": true,
          "document_id": 229928,
          "forensics": { "is_valid": "no" }
        },
        "front": {
          "face_analysis": {
            "face_id": 237437,
            "face_id_v2": 199068,
            "first_seen": "12/22/2022, 18:54:09",
            "inquiry_date": "07/28/2025, 20:53:12",
            "last_seen": "07/28/2025, 18:47:46",
            "last_seen_by_your_company": "07/24/2025, 21:38:21",
            "match": true,
            "match_fraud_flag": true,
            "seen_by_your_company": true,
            "seen_different_companies": 46,
            "times_seen_by_your_company": 3,
            "times_seen_last_month": 111,
            "unique_face_id_v2": 126880,
            "warnings": {
              "external_id": "User found in the company with other external_ids: ['abc-123']"
            }
          },
          "information": {
            "address": { "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552", "valid": false },
            "birthdate": { "text": "14/11/1956", "valid": true },
            "complete_name": { "text": "LUKE SKYWALKER", "valid": true },
            "curp": { "text": "GOCJ850627HDFRRL09", "valid": true },
            "electoral_key": { "text": "GRCRSN82031007M500", "valid": true },
            "last_name": { "text": "SKYWALKER", "valid": true },
            "mother_last_name": { "text": "ORGANA", "valid": true },
            "name": { "text": "LUKE", "valid": true },
            "registration_year": { "text": "1998", "valid": true },
            "sex": { "text": "H", "valid": true },
            "valid_thru": { "text": "2027", "valid": true }
          }
        }
      },
      "face_match": false,
      "label": null,
      "reason": null,
      "request_id": "d1kxp9ah8f0s71uv9zx0",
      "selfie": {
        "face_id": 237436,
        "face_id_v2": 4378,
        "first_seen": "02/05/2025, 02:36:19",
        "first_seen_image": true,
        "inquiry_date": "07/28/2025, 20:52:49",
        "last_seen": "07/28/2025, 20:52:51",
        "last_seen_by_your_company": "07/23/2025, 18:14:27",
        "match": true,
        "match_fraud_flag": true,
        "seen_by_your_company": true,
        "seen_different_companies": 2,
        "times_seen_by_your_company": 2,
        "times_seen_last_month": 7,
        "unique_face_id_v2": 494,
        "warnings": {}
      },
      "unico": {
        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",
        "result": "PROCESS_RESULT_LIVE"
      }
    },
    "user_id": ""
  },
  "request_date": "2025-07-28T20:53:38",
  "status": "Request fulfilled, document follows",
  "status_code": 200,
  "version": "v3.6.0"
}

حقول الاستجابة:

المستوى الجذري:

الحقل	النوع	الوصف
`status`	string	تمثيل نصي لحالة الاستجابة.
`status_code`	integer	رمز حالة HTTP.
`request_date`	string (date-time)	تاريخ ووقت تقديم الطلب.
`version`	string	إصدار API الذي عالج الطلب.
`data.user_id`	string	معرّف المستخدم المحدد في الطلب الأصلي.

data.images — صور ملتقطة مُرمَّزة بـ Base64:

الحقل	النوع	الوصف
`data.images.document_image`	string	صورة الوجه الأمامي للوثيقة مُرمَّزة بـ Base64.
`data.images.document_image_back`	string	صورة الوجه الخلفي للوثيقة مُرمَّزة بـ Base64.
`data.images.selfie`	string	صورة السيلفي الملتقطة أثناء التحقق مُرمَّزة بـ Base64.

data.response.unico — الحكم الموحَّد:

الحقل	النوع	الوصف
`data.response.unico.process_id`	string (UUID)	معرّف داخلي مرتبط بعملية التحقق.
`data.response.unico.result`	string	نتيجة العملية. القيم المحتملة موضحة أدناه.

القيم المحتملة لـ data.response.unico.result:

يُرمّز قيمة النتيجة أحد ثلاثة أبعاد للتقييم:

تقييم الهوية — ما إذا كان الوجه الملتقَط ينتمي إلى حامل الوثيقة (PROCESS_RESULT_VERIFIED، PROCESS_RESULT_NOT_APPROVED).
السلوك الاحتيالي — ما إذا كانت الإشارات السلوكية أو الشبكية تشير إلى مخاطر الاحتيال (PROCESS_RESULT_LIVE، PROCESS_RESULT_HIGH_RISK، PROCESS_RESULT_CRITICAL_RISK، PROCESS_RESULT_NOT_APPROVED).
الحيوية — ما إذا تم اكتشاف وجه حي وقت الالتقاط (PROCESS_RESULT_NOT_LIVE).

النتيجة	التوصية	المعنى	الإشارة
`PROCESS_RESULT_ERROR`	رفض	انتهت العملية بخطأ.	النظام
`PROCESS_RESULT_VERIFIED`	قبول	كان المستخدم نشطاً لحظة الالتقاط؛ وجهه يطابق صاحب الوثيقة ولم يُعثر على أدلة احتيال.	الهوية: مؤكدة
`PROCESS_RESULT_LIVE`	مراجعة / قبول	كان المستخدم نشطاً لحظة الالتقاط؛ لم نجد أدلة كافية لضمان أنه صاحب الوثيقة ولا أدلة احتيال.	الهوية: غير حاسمة · الاحتيال: لا شيء
`PROCESS_RESULT_HIGH_RISK`	يُوصى بالرفض	وجدنا دليلاً قوياً واحداً على الأقل على الاحتيال. القرار النهائي لك.	السلوك الاحتيالي: إشارة قوية واحدة
`PROCESS_RESULT_CRITICAL_RISK`	يُوصى بالرفض	وجدنا دليلَين قويَّين على الأقل على الاحتيال. القرار النهائي لك.	السلوك الاحتيالي: إشارتان قويتان أو أكثر
`PROCESS_RESULT_NOT_APPROVED`	رفض	يُوصى بالرفض نظراً لرصد مؤشرات متعددة على الاحتيال.	الهوية: مرفوضة · السلوك الاحتيالي: إشارات متعددة
`PROCESS_RESULT_NOT_LIVE`	السماح بحتى محاولتين	لم يكن المستخدم حياً لحظة الالتقاط، رغم عدم وجود مؤشرات احتيال أخرى.	الحيوية: الوجه غير حي

ملاحظة

PROCESS_RESULT_VERIFIED يتطلب تفعيلاً. بشكل افتراضي، هذه النتيجة غير مُفعَّلة — تواصل مع مدير مشروعك في Unico إذا أردت تفعيلها.

إشارات مساعدة لاتخاذ قرارك:

في حالات LIVE أو HIGH_RISK أو CRITICAL_RISK، استكمل قرارك بهذه الحقول:

الحقل	النوع	المعنى
`face_match`	boolean	حالة مطابقة الوجه بين الوثيقة والسيلفي.
`document.front.face_analysis.match_fraud_flag`	boolean	ما إذا كان وجه الوثيقة مرتبطاً بنشاط احتيالي.
`selfie.match_fraud_flag`	boolean	ما إذا كان وجه السيلفي مرتبطاً بنشاط احتيالي.
`warnings.external_id`	string	تحذير يشير إلى ارتباط وجه المستخدم بمعرّفات خارجية متعددة.

data.response — إشارات النتيجة الرئيسية:

الحقل	النوع	الوصف
`data.response.face_match`	boolean	ما إذا كان وجه السيلفي يطابق وجه الوثيقة.
`data.response.label`	string (nullable)	محجوز لنتائج عمليات فرعية محددة؛ `null` إذا لم ينطبق.
`data.response.reason`	string (nullable)	أسباب التسمية المُعيَّنة.
`data.response.request_id`	string	معرّف فريد لطلب API.

data.response.curp — التحقق من CURP مع RENAPO:

الحقل	النوع	الوصف
`curp`	string	سلسلة CURP قيد التحليل.
`government_valid`	boolean	ما إذا كان CURP صالحاً وفقاً لـ RENAPO.
`government_name`	string	الاسم الكامل المرتبط بـ CURP في قاعدة البيانات الرسمية.
`name_to_CURP_valid`	boolean	ما إذا كان الاسم المُقدَّم متوافقاً مع CURP.
`is_mexican`	boolean	ما إذا كان CURP يخص مواطناً مكسيكياً.
`deceased`	boolean	ما إذا كان CURP مُصنَّفاً كمتوفى في قاعدة البيانات الرسمية.
`date_of_birth`	string	تاريخ الميلاد كما هو مُستخرج من CURP (يوم/شهر/سنة).
`age`	integer	العمر المحسوب للمستخدم.
`gender`	string	الجنس كما هو مُستخرج من CURP (`M` أو `F`).
`state_of_birth`	string	ولاية الميلاد كما هي مُستخرجة من CURP.
`state_iso`	string	رمز ISO 3166-2 لولاية الميلاد.

data.response.document.details — اكتشاف الوثيقة والتحليل الجنائي:

الحقل	النوع	الوصف
`detected`	boolean	ما إذا تم اكتشاف وثيقة بنجاح في الصورة.
`document_id`	integer	معرّف فريد للوثيقة المعالجة.
`forensics.is_valid`	string	نتيجة التحليل الجنائي: `yes` أو `no` أو `inconclusive`.

data.response.document.front.information — الحقول المُستخرجة بـ OCR من الوجه الأمامي لـ INE. كل حقل يحتوي على text (القيمة المُستخرجة) وvalid (ما إذا أمكن التحقق منها هيكلياً):

الحقل	الوصف
`name`	الاسم الأول.
`last_name`	اسم الأب.
`mother_last_name`	اسم الأم.
`complete_name`	الاسم الكامل.
`birthdate`	تاريخ الميلاد (يوم/شهر/سنة).
`sex`	الجنس (`H` أو `M`).
`curp`	CURP المُستخرج من الوثيقة.
`electoral_key`	المفتاح الانتخابي.
`address`	العنوان.
`registration_year`	سنة تسجيل الوثيقة.
`valid_thru`	سنة انتهاء صلاحية الوثيقة.

data.response.document.front.face_analysis — تحليل الوجه الموجود على INE:

الحقل	النوع	الوصف
`face_id`	integer	معرّف فريد لهذه النسخة من الوجه.
`face_id_v2`	integer	معرّف فريد (الإصدار 2).
`unique_face_id_v2`	integer	معرّف ثابت لهذا الوجه الفيزيائي عبر جميع الاستفسارات.
`first_seen`	string	الطابع الزمني لأول مرة شُوهد فيها هذا الوجه في النظام.
`last_seen`	string	الطابع الزمني لآخر مرة شُوهد فيها هذا الوجه في الشبكة.
`last_seen_by_your_company`	string	آخر مرة شُوهد فيها هذا الوجه في استفسار بواسطة شركتك.
`inquiry_date`	string	الطابع الزمني لاستفسار التحقق الحالي.
`match`	boolean	ما إذا كان هذا الوجه مطابقاً محتملاً لوجوه أخرى في قاعدة البيانات.
`match_fraud_flag`	boolean	ما إذا كان هذا الوجه مرتبطاً بنشاط احتيالي.
`seen_by_your_company`	boolean	ما إذا سبق لشركتك رؤية هذا الوجه.
`seen_different_companies`	integer	عدد الشركات الأخرى في الشبكة التي رأت هذا الوجه.
`times_seen_by_your_company`	integer	إجمالي مرات رؤية هذا الوجه في استفسارات شركتك.
`times_seen_last_month`	integer	عدد مرات رؤيته خلال الشهر الماضي عبر الشبكة.
`warnings.external_id`	string	تحذير إذا كان وجه المستخدم مرتبطاً بمعرّفات خارجية متعددة.

data.response.document.back — بيانات MRZ من الوجه الخلفي لـ INE:

الحقل	النوع	الوصف
`mrz`	string	سلسلة المنطقة القابلة للقراءة الآلية الكاملة.
`cic`	string	رقم CIC المُستخرج من MRZ.
`citizen_id`	string	رقم تعريف المواطن من MRZ.

data.response.selfie — تحليل السيلفي الملتقط:

الحقل	النوع	الوصف
`face_id`	integer	معرّف فريد لنسخة وجه السيلفي.
`face_id_v2`	integer	معرّف فريد (الإصدار 2).
`unique_face_id_v2`	integer	معرّف ثابت لهذا الوجه الفيزيائي عبر جميع الاستفسارات.
`first_seen`	string	أول مرة شُوهد فيها وجه هذا السيلفي في النظام.
`first_seen_image`	boolean	ما إذا كانت هذه أول مرة تُرى فيها هذه الصورة بالذات.
`last_seen`	string	آخر مرة شُوهد فيها هذا الوجه في الشبكة.
`last_seen_by_your_company`	string	آخر مرة شُوهد فيها هذا الوجه بواسطة شركتك.
`inquiry_date`	string	الطابع الزمني لاستفسار التحقق الحالي.
`match`	boolean	ما إذا كان وجه السيلفي يطابق وجوهاً أخرى في قاعدة البيانات.
`match_fraud_flag`	boolean	ما إذا كان وجه السيلفي مرتبطاً بنشاط احتيالي.
`seen_by_your_company`	boolean	ما إذا سبق لشركتك رؤية هذا الوجه.
`seen_different_companies`	integer	عدد الشركات الأخرى في الشبكة التي رأت هذا الوجه.
`times_seen_by_your_company`	integer	إجمالي مرات رؤية هذا الوجه في استفسارات شركتك.
`times_seen_last_month`	integer	عدد مرات رؤيته خلال الشهر الماضي عبر الشبكة.
`warnings`	object	تحذيرات محددة تتعلق بتحليل السيلفي (نفس هيكل face_analysis للوثيقة).

استخدم الاستطلاع مع التراجع الأسي — لا تستدعِ في حلقة متواصلة.

استجابات الخطأ — GET /v2/history/request

الرمز	الرسالة	الوصف
`400 Bad Request`	`Input should be a valid UUID, invalid group length...`	المعامل `magic_link_token` مُشوَّه أو ليس بصيغة UUID صالحة.
`404 Not Found`	`This magic link have no requests associated`	الرمز المُقدَّم موجود لكن لا توجد عمليات KYC مكتملة مرتبطة به. ربما لم يُنهِ المستخدم الرحلة بعد.
`500 Internal Server Error`	`internal server error`	فشل في المعالجة على جانب الخادم. أعد المحاولة مع تراجع أسي. إذا استمر الأمر، أبلغ الدعم.

مثال على استجابة 400:

{
  "data": {
    "error": [
      {
        "attribute": ["magic_link_token"],
        "message": "Input should be a valid UUID, invalid group length in group 4: expected 12, found 11",
        "type": "uuid_parsing"
      }
    ]
  },
  "request_date": "2025-07-28T20:43:34",
  "status": "There are some errors in the request",
  "status_code": 400,
  "version": "v3.6.0"
}

مثال على استجابة 404:

{
  "data": {
    "error": "This magic link have no requests associated"
  },
  "request_date": "2025-07-28T20:40:50",
  "status": "Nothing matches the given URI",
  "status_code": 404,
  "version": "v3.6.0"
}

مثال على استجابة 500:

{
  "data": {
    "error": "internal server error"
  },
  "version": "v1.4.2",
  "status": "bad request",
  "status_code": 400,
  "request_date": "2025-07-28T20:22:29+0000",
  "request": {
    "metadata": null
  }
}

Webhook V2

ثلاثة أحداث webhook متاحة. للتفعيل، اطلب الإعداد من مدير مشروع التأهيل لديك مُقدِّماً: رابط URL لنقطة النهاية (HTTPS مطلوب)، نوع المصادقة (basic_auth أو api_key أو oauth2 أو NoAuth)، إعداد المصادقة، الحد الأقصى لمحاولات إعادة المحاولة، فترة إعادة المحاولة (بالثواني) والمهلة (بالثواني).

MAGIC_LINK_RESULTS

يُرسَل هذا الحدث في نهاية التدفق، عندما يُنهي Decision Maker معالجة المعلومات المُرسَلة.

{
  "data": {
    "images": {
      "document_image": "base64str",
      "document_image_back": "base64str",
      "selfie": "base64str"
    },
    "response": {
      "document": {
        "details": {
          "detected": true,
          "forensics": {
            "is_valid": "yes"
          },
          "document_id": 123
        },
        "front": {
          "information": {
            "birthdate": { "text": "14/11/1956", "valid": true },
            "sex": { "text": "H", "valid": true },
            "registration_year": { "text": "1998", "valid": true },
            "name": { "text": "LUKE", "valid": true },
            "mother_last_name": { "text": "ORGANA", "valid": true },
            "last_name": { "text": "SKYWALKER", "valid": true },
            "electoral_key": { "text": "GRCRSN82031007M500", "valid": true },
            "curp": { "text": "GOCJ850627HDFRRL09", "valid": true },
            "address": { "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552", "valid": false },
            "complete_name": { "text": "LUKE SKYWALKER", "valid": true },
            "valid_thru": { "text": "2027", "valid": true }
          },
          "face_analysis": {
            "face_id": 237437,
            "first_seen": "12/22/2022, 18:54:09",
            "unique_face_id_v2": 126880,
            "face_id_v2": 199068,
            "inquiry_date": "07/28/2025, 20:53:12",
            "last_seen": "07/28/2025, 18:47:46",
            "last_seen_by_your_company": "07/24/2025, 21:38:21",
            "match": true,
            "match_fraud_flag": true,
            "seen_by_your_company": true,
            "seen_different_companies": 46,
            "times_seen_by_your_company": 3,
            "times_seen_last_month": 111,
            "warnings": {
              "external_id": "User found in the company with other external_ids: ['abc-123']"
            }
          }
        },
        "back": {
          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE",
          "cic": "237457894"
        }
      },
      "selfie": {
        "face_id": 237436,
        "first_seen": "02/05/2025, 02:36:19",
        "unique_face_id_v2": 494,
        "face_id_v2": 4378,
        "inquiry_date": "07/28/2025, 20:52:49",
        "last_seen": "07/28/2025, 20:52:51",
        "last_seen_by_your_company": "07/23/2025, 18:14:27",
        "match": true,
        "match_fraud_flag": true,
        "seen_by_your_company": true,
        "seen_different_companies": 2,
        "times_seen_by_your_company": 2,
        "times_seen_last_month": 7,
        "warnings": {
          "external_id": "User found in the company with other external_ids: ['abc-123']"
        },
        "first_seen_image": true
      },
      "face_match": false,
      "curp": {
        "curp": "GOCJ850627HDFRRL09",
        "state_of_birth": "Nuevo León",
        "state_iso": "MX-NLE",
        "date_of_birth": "14/11/1956",
        "age": 58,
        "gender": "M",
        "is_mexican": true,
        "name_to_CURP_valid": true,
        "government_valid": true,
        "government_name": "LUKE SKYWALKER",
        "deceased": false
      },
      "unico": {
        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",
        "result": "PROCESS_RESULT_LIVE"
      },
      "label": null,
      "reason": null,
      "request_id": "d1kxp9ah8f0s71uv9zx0"
    },
    "user_id": null
  },
  "event": "MAGIC_LINK_RESULTS",
  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
  "user_id": null,
  "date": "2025-10-03T21:15:41.299815"
}

MAGIC_LINK_TRACK

تُستقبل هذه الأحداث عندما يُكمل المستخدم إجراءً ما. على سبيل المثال، سيُستقبل form_start عندما يلتقط المستخدم الوجه الأمامي للوثيقة، مما يعني أن المستخدم نقر وأكمل الشاشة الأولى.

{
  "data": {
    "completed_on": "Fri, 03 Oct 2025 21:15:35 GMT",
    "started_on": "Fri, 03 Oct 2025 21:15:30 GMT",
    "step": "form_start",
    "user_id": null
  },
  "event": "MAGIC_LINK_TRACK",
  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
  "user_id": null,
  "date": "2025-10-03T21:15:41.299815"
}

الحقل	النوع	الوصف
`data.step`	string	اسم الخطوة المكتملة.
`data.user_id`	string (nullable)	المعرّف الخارجي المحدد في magic link.
`data.started_on`	datetime	وقت بدء الخطوة بتوقيت UTC.
`data.completed_on`	datetime	وقت اكتمال الخطوة بتوقيت UTC.
`event`	string	معرّف نوع الحدث.
`magic_link_token`	uuid	رمز magic link الفريد.
`user_id`	string (nullable)	المعرّف الخارجي.
`date`	datetime	الطابع الزمني للحدث.

الخطوات المدعومة:

الخطوة	الوصف
`form_start`	نقر المستخدم على زر magic link الأولي.
`form_document_front`	أكمل المستخدم التقاط الوجه الأمامي لـ INE.
`form_document_back`	أكمل المستخدم التقاط الوجه الخلفي لـ INE.
`form_document`	أكمل المستخدم عمليتَي الوجه الأمامي والخلفي.
`form_selfie`	أكمل المستخدم عملية الحيوية.
`form_decision_maker`	أكمل المستخدم التدفق بالكامل.

MAGIC_LINK_DOCUMENT_RETAKE_REASONS

يُرسَل هذا الحدث عند الحاجة إلى إعادة التقاط الوثيقة، سواء أثناء عملية الوجه الأمامي أو الخلفي. يُشير إلى تعذُّر قراءة بيانات مهمة من INE.

{
  "data": {
    "document_type": "ine_front",
    "invalid_back_ocr": false,
    "invalid_curp": false,
    "invalid_document": true
  },
  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",
  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
  "user_id": null,
  "date": "2025-10-03T21:12:00.000Z"
}

الحقل	النوع	الوصف
`data.document_type`	string	جانب الوثيقة: `ine_front` أو `ine_back`.
`data.invalid_document`	boolean	`true` إذا لم تكن الصورة الملتقطة INE صالحة (أي جانب).
`data.invalid_curp`	boolean	`true` إذا تعذّرت قراءة CURP (خاص بـ `ine_front` فقط).
`data.invalid_back_ocr`	boolean	`true` إذا تعذّرت قراءة رمز MRZ (خاص بـ `ine_back` فقط).
`event`	string	معرّف نوع الحدث.
`magic_link_token`	uuid	رمز magic link الفريد.
`user_id`	string (nullable)	المعرّف الخارجي.
`date`	datetime	الطابع الزمني للحدث.

الحمولة مُصمَّمة بحيث يُستقبل خطأ واحد فقط (true) لكل جانب من جوانب الوثيقة.

سيناريوهات الفشل — الوجه الأمامي لـ INE:

وثيقة غير صالحة ← invalid_document: true فقط
فشل قراءة CURP ← invalid_curp: true فقط

سيناريوهات الفشل — الوجه الخلفي لـ INE:

وثيقة غير صالحة ← invalid_document: true فقط
فشل قراءة MRZ ← invalid_back_ocr: true فقط

التوافق بين V1 / V2

إذا كنت لا تزال ترسل webhook_url في metadata الخاص بالطلب (Webhook V1)، فإن هذا الإعداد يأخذ الأولوية على V2 العالمي. للترحيل، أزل webhook_url من metadata واضبط V2 مع مدير التأهيل لديك.

التخصيصات

صفحة Magic Link المُستضافة لا تدعم التخصيص البصري من قِبل العميل — فهي تتبع الهوية البصرية الافتراضية لـ Unico/Trully. لتخصيص الرحلة (الشعار، الألوان، النصوص)، استخدم Onboarding (العالمي) مع SDK أو Web.

التوفر: المكسيك · نقطة النهاية: POST https://api.trully.ai/v2/magic-link · الوثيقة: INE · المصادقة: x-api-key (Trully)

ما الذي تحله حالة الاستخدام هذه​

القدرات المعتمدة​

المتطلبات الأساسية​

التطبيق خطوة بخطوة​

1. إنشاء Magic Link​

2. استقبال الرمز ورابط URL​

3. توزيع magic_link_url على المستخدم​

4. استقبال النتيجة​

الاستطلاع عبر GET​

Webhook V2​

التخصيصات​