---
title: KYC Magic Link
description: تنفيذ عملية التعرف على الهوية في المكسيك، مع جمع وثائق الهوية الوطنية (INE) والبيانات البيومترية للوجه عبر رحلة مُستضافة تُوزَّع بواسطة رابط فريد.
canonical: https://developer.unico.io/ar/dual-api/products/sign-up/kyc-magic-link/index
locale: ar
generated_by: markdown-export
---

- [/ar/](/ar/)
- [بناء](/ar/dual-api/products/)
- الدليل الإقليمي
- KYC Magic Link

**في هذه الصفحة# KYC Magic Link

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

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

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

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

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

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

خط أنابيب يُنفَّذ ضمن عملية واحدة:
[التقاط الوثيقة (INE)](/ar/capabilities/document-reuse-and-capture)[الحيوية](/ar/capabilities/liveness)[تصنيف المخاطر](/ar/capabilities/fraud-risk-classification)[التحقق من الهوية](/ar/capabilities/identity-verification)
القدرةمطلوبةالدور في التدفق**التقاط الوثيقة**مطلوبةيلتقط صورة وثيقة INE. إعادة استخدام الوثائق **غير متاحة** في حالة الاستخدام هذه — كل جلسة تتطلب التقاطاً جديداً.**الحيوية**مطلوبةفحص الحضور الحي — صورة سيلفي إلزامية تُرسّخ العملية.**تصنيف المخاطر**مطلوبةيقارن إشارات سلوكية للإشارة إلى مخاطر الاحتيال المرتبطة بالرقم الوطني.**التحقق من الهوية**اختيارية (إذا كانت مُتعاقداً عليها)يتحقق مما إذا كان وجه المعاملة يخص حامل المعرّف الحكومي المُقدَّم، باستخدام قاعدة هوية Unico وإشارات إضافية.**[التحقق من RENAPO](/ar/capabilities/renapo-verification)**اختيارية (إذا كانت مُتعاقداً عليها)يستعلم من RENAPO، السجل الوطني للسكان في المكسيك، باستخدام CURP الخاص بالمستخدم ويُعيد سجل السجل إلى جانب نتيجة التحقق من الهوية.
### المتطلبات الأساسية​

**مفتاح 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 — انظر [جدول الخطوات المدعومة](#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](https://github.com/unico-labs/TrullyAi-AndroidMagicLink)
**React Native:** [TrullyAI-ReactNativeMagicLink](https://github.com/unico-labs/TrullyAI-ReactNativeMagicLink)

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

لديك مرونة كاملة لتقرير كيفية استقبال النتيجة النهائية لعملية KYC — اختر الاستراتيجية الأنسب لبنية نظامك. يمكنك الاستطلاع الفعّال عن النتيجة (GET) أو استقبالها بشكل سلبي عبر الإشعارات (Webhook).
**الخيار أ — الاستطلاع الفعّال عبر GET**
استرجع النتيجة عبر استدعاء `GET /v2/history/request?magic_link_token={token}` (انظر [الاستطلاع عبر GET](#polling-via-get) أدناه). يُملأ القرار النهائي في `data.response.unico.result`.
أفضل ممارسة لـ GETبدلاً من الاستطلاع الدوري منذ لحظة إنشاء الرابط، استخدم webhooks التتبع (انظر [Webhook V2](#webhook-v2) أدناه) لمعرفة اللحظة الدقيقة للاستعلام. بمجرد استقبال خطوة `form_decision_maker`، تكون تلك هي اللحظة الدقيقة والآمنة لتنفيذ استدعاء GET هذا.
**الخيار ب — الاستقبال التلقائي عبر Webhook**
اجعل نظامك يتلقى إشعاراً تلقائياً بمجرد جاهزية النتيجة النهائية (انظر [Webhook V2](#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)آخر تحديث في 8 أكتوبر 2026**