---
title: KYC Magic Link
description: Выполняет процесс идентификации в Мексике, собирая национальные удостоверения личности (INE) и биометрические данные лица через размещённый процесс, распространяемый по уникальной ссылке.
canonical: https://developer.unico.io/ru/dual-api/products/sign-up/kyc-magic-link/index
locale: ru
generated_by: markdown-export
---

- [/ru/](/ru/)
- [Создать](/ru/dual-api/products/)
- Региональное руководство
- KYC Magic Link

**На этой странице# KYC Magic Link

Отдельный региональный контрактЭтот сценарий использования **не использует** эндпоинт Unico `POST /v1/process` и не использует контракт API. Интеграция осуществляется с **Trully.ai** (хост `api.trully.ai`), с **аутентификацией через `x-api-key`** вместо Bearer JWT, и **собственной схемой ответа**. Для других стран используйте Онбординг (Глобальный).
### Что решает этот сценарий использования​

KYC Magic Link решает задачу выполнения процесса идентификации в Мексике, сбора национальных удостоверений личности (INE) и биометрических данных лица. Благодаря процессу, размещённому Unico, вы устраняете трудности с разработкой front-end с помощью ссылки, отправляемой через ваши собственные каналы (WhatsApp, SMS, электронная почта).
**Используйте этот сценарий, когда:**

Вы работаете в **Мексике** и используемый документ удостоверения личности — **INE (обязательно)**.

**Не используйте этот сценарий, когда:**

Пользователь находится за пределами Мексики или использует другие документы → обратитесь к другим сценариям онбординга.

### Задействованные возможности​

Конвейер, выполняемый в рамках одного процесса:
[Захват документа (INE)](/ru/capabilities/document-reuse-and-capture)[Liveness](/ru/capabilities/liveness)[Классификация рисков](/ru/capabilities/fraud-risk-classification)[Верификация личности](/ru/capabilities/identity-verification)
ВозможностьОбязательностьРоль в процессе**Захват документа**ОбязательноЗахватывает изображение документа INE. Повторное использование документа **недоступно** в этом сценарии — каждая сессия требует нового захвата.**Liveness**ОбязательноПроверка живости — обязательное селфи, которое привязывает процесс.**Классификация рисков**ОбязательноПерекрёстно сопоставляет поведенческие сигналы для выявления риска мошенничества, связанного с CPF.**Верификация личности**Опционально (при наличии контракта)Проверяет, принадлежит ли лицо в транзакции владельцу предоставленного государственного идентификатора, используя базу идентификаторов Unico и дополнительные сигналы.**[RENAPO Verification](/ru/capabilities/renapo-verification)**Опционально (при наличии контракта)Запрашивает RENAPO — национальный реестр населения Мексики — по CURP пользователя и возвращает запись реестра наряду с результатом Проверки личности.
### Предварительные требования​

**API-ключ** — предоставляется вашим менеджером проекта по онбордингу в Unico. Отправляется в заголовке `x-api-key`.
**Публичный HTTPS-эндпоинт** для получения вебхуков (опционально, но рекомендуется).
**Настройка CORS** — разрешите источники `https://verification.unico.app` (продакшн) и `https://verification.uat.unico.app` (sandbox) на сервере, принимающем вебхук.

### Пошаговая реализация​

В отличие от других сценариев, 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НетURL для перенаправления пользователя после завершения процесса KYC.`metadata.webhook_url`stringНетURL для отправки данных процесса KYC после его завершения. Этот вебхук будет вызываться на стороне клиента. В целях безопасности эндпоинт должен использовать HTTPS. Компонент будет ждать одну минуту ответа от вашего вебхук-сервера — по истечении этого времени связь будет прервана. Процесс никак не пострадает от сбоя вебхук-коммуникации. Убедитесь, что `https://verification.unico.app` и `https://verification.uat.unico.app` разрешены в вашей конфигурации CORS для продакшна и sandbox соответственно.`metadata.track_webhook_url`stringНетURL для отправки данных каждого шага KYC, выполненного пользователем (см. события вебхуков ниже). Этот вебхук будет вызываться на стороне клиента. В целях безопасности эндпоинт должен использовать HTTPS. Компонент будет ждать одну минуту ответа от вашего вебхук-сервера — по истечении этого времени связь будет прервана. Процесс никак не пострадает от сбоя вебхук-коммуникации. Убедитесь, что `https://verification.unico.app` и `https://verification.uat.unico.app` разрешены в вашей конфигурации CORS для продакшна и sandbox соответственно.
`data.step` (отправляется на `track_webhook_url`) отражает те же шаги, что и Вебхук 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)URL для перенаправления пользователя после завершения процесса KYC.`data.metadata.webhook_url`string (nullable)URL для отправки данных процесса KYC после его завершения. Этот вебхук будет вызываться на стороне клиента.`data.metadata.track_webhook_url`string (nullable)URL для отправки данных каждого шага KYC, выполненного пользователем. Этот вебхук будет вызываться на стороне клиента.`data.version`stringВерсия magic link.`version`stringВерсия API, обработавшего запрос, полезна для отслеживания изменений и совместимости.`status`stringТекстовое представление статуса ответа, указывающее на успех или неудачу операции.`status_code`integerHTTP-код статуса ответа, обеспечивающий стандартизированный индикатор результата запроса.`request_date`string (date-time)Дата и время запроса в формате ISO 8601.`request.metadata.redirect_url`string (nullable)URL для перенаправления пользователя после завершения процесса KYC (эхо запроса).`request.metadata.webhook_url`string (nullable)URL для отправки данных процесса KYC после завершения (эхо запроса).`request.metadata.track_webhook_url`string (nullable)URL для отправки данных каждого шага 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 пользователю​

Отправьте через WhatsApp, 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) или получать его пассивно через уведомления (Вебхук).
**Вариант A — активный опрос через GET**
Получите результат, вызвав `GET /v2/history/request?magic_link_token={token}` (см. [Опрос через GET](#polling-via-get) ниже). Итоговое решение заполняется в поле `data.response.unico.result`.
Лучшая практика для GETВместо периодического опроса с момента создания ссылки используйте вебхуки отслеживания (см. [Вебхук V2](#webhook-v2) ниже), чтобы точно знать, когда делать запрос. Как только вы получите шаг `form_decision_maker`, это будет точный и безопасный момент для вызова этого запроса GET.
**Вариант B — автоматическое получение через вебхук**
Настройте автоматическое уведомление вашей системы сразу после готовности итогового результата (см. [Вебхук V2](#webhook-v2) ниже). Доступны две версии:

**Вебхук V1** — вы получаете результат по URL, отправленному в `metadata.webhook_url` при создании токена.
**Вебхук V2** — настраивается заранее с вашим менеджером проекта по онбордингу. Вы получаете итоговый вердикт, прослушивая событие `MAGIC_LINK_RESULTS`.

Отказоустойчивость — резервный вариантЕсли вебхук (вариант B) является вашим основным методом, также реализуйте запрос GET (вариант A) в качестве резервного варианта. Это позволяет восстановить результат с помощью процедур сверки в случае сетевых сбоев, временных отказов сервера или вебхука, который не смог корректно обработать данные.

### Опрос через 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`integerHTTP-код статуса.`request_date`string (date-time)Дата и время запроса.`version`stringВерсия API, обработавшего запрос.`data.user_id`stringID пользователя, установленный в исходном запросе.
**`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`).
**Liveness** — было ли живое лицо обнаружено в момент захвата (`PROCESS_RESULT_NOT_LIVE`).

РезультатРекомендацияЗначениеСигнал`PROCESS_RESULT_ERROR`**Отклонить**Процесс завершился с ошибкой.Система`PROCESS_RESULT_VERIFIED`**Принять**Пользователь был активен в момент захвата; это лицо владельца удостоверения личности, и свидетельств мошенничества не обнаружено.Личность: подтверждена`PROCESS_RESULT_LIVE`**Проверить / Принять**Пользователь был активен в момент захвата; недостаточно доказательств того, что он является владельцем удостоверения личности, и нет признаков мошенничества.Личность: неопределённо · Мошенничество: нет`PROCESS_RESULT_HIGH_RISK`**Рекомендуем отклонить**Обнаружено по крайней мере одно веское доказательство мошенничества. Окончательное решение за вами.Мошенническое поведение: 1 сильный сигнал`PROCESS_RESULT_CRITICAL_RISK`**Рекомендуем отклонить**Обнаружено не менее 2 веских доказательств мошенничества. Окончательное решение за вами.Мошенническое поведение: 2+ сильных сигнала`PROCESS_RESULT_NOT_APPROVED`**Отклонить**Рекомендуется отклонить, так как обнаружены множественные признаки мошенничества.Личность: отклонена · Мошенническое поведение: множественные сигналы`PROCESS_RESULT_NOT_LIVE`**До 2 повторных попыток**Пользователь не был живым в момент захвата, хотя других признаков мошенничества не обнаружено.Liveness: лицо не живое
примечание`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Предупреждение о том, что лицо пользователя связано с несколькими внешними ID.
**`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Предупреждение, если лицо пользователя связано с несколькими внешними ID.
**`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  }}
```

### Вебхук V2​

Доступны три события вебхука. Для активации запросите настройку у вашего менеджера проекта по онбордингу, предоставив: **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)Внешний ID, установленный в 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`Пользователь завершил процесс liveness.`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 по умолчанию. Для кастомизации процесса (логотип, цвета, тексты) используйте Онбординг (Глобальный) с SDK или Web.
**Доступность:** Мексика · **Эндпоинт:** `POST https://api.trully.ai/v2/magic-link` · **Документ:** INE · **Аутентификация:** `x-api-key` (Trully)Последнее обновление 8 окт. 2026 г.**