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)

Liveness

Классификация рисков

Верификация личности

Возможность	Обязательность	Роль в процессе
Захват документа	Обязательно	Захватывает изображение документа INE. Повторное использование документа недоступно в этом сценарии — каждая сессия требует нового захвата.
Liveness	Обязательно	Проверка живости — обязательное селфи, которое привязывает процесс.
Классификация рисков	Обязательно	Перекрёстно сопоставляет поведенческие сигналы для выявления риска мошенничества, связанного с CPF.
Верификация личности	Опционально (при наличии контракта)	Проверяет, принадлежит ли лицо в транзакции владельцу предоставленного государственного идентификатора, используя базу идентификаторов Unico и дополнительные сигналы.
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 — см. таблицу поддерживаемых шагов ниже.

Пример запроса:

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`	integer	HTTP-код статуса ответа, обеспечивающий стандартизированный индикатор результата запроса.
`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
React Native: TrullyAI-ReactNativeMagicLink

4. Получите результат

У вас есть полная свобода в выборе способа получения итогового результата процесса KYC — выберите стратегию, которая лучше всего подходит архитектуре вашей системы. Вы можете активно опрашивать результат (GET) или получать его пассивно через уведомления (Вебхук).

Вариант A — активный опрос через GET

Получите результат, вызвав GET /v2/history/request?magic_link_token={token} (см. Опрос через GET ниже). Итоговое решение заполняется в поле data.response.unico.result.

Лучшая практика для GET

Вместо периодического опроса с момента создания ссылки используйте вебхуки отслеживания (см. Вебхук V2 ниже), чтобы точно знать, когда делать запрос. Как только вы получите шаг form_decision_maker, это будет точный и безопасный момент для вызова этого запроса GET.

Вариант B — автоматическое получение через вебхук

Настройте автоматическое уведомление вашей системы сразу после готовности итогового результата (см. Вебхук 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`	integer	HTTP-код статуса.
`request_date`	string (date-time)	Дата и время запроса.
`version`	string	Версия API, обработавшего запрос.
`data.user_id`	string	ID пользователя, установленный в исходном запросе.

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)

Что решает этот сценарий использования​

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

Предварительные требования​

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

1. Создайте Magic Link​

2. Получите токен и URL ссылки​

3. Распространите magic_link_url пользователю​

4. Получите результат​

Опрос через GET​

Вебхук V2​

Кастомизации​