Повторная обработка и импорт биометрической базы

Это руководство описывает, как выполнить повторную обработку или импорт биометрической базы на платформе Unico. В нём подробно описаны технические и операционные требования для эффективной и безопасной интеграции в соответствии с лучшими практиками платформы.

Область применения

Данный материал охватывает два типа процессов:

Повторная обработка: повторная обработка биометрических записей пользователей, которые уже прошли через базу клиента и Unico, для переоценки или миграции между системами.
Импорт биометрической базы: первичная загрузка или обновление базы, содержащей селфи для верификации личности и/или классификации рисков.
Импорт базы документов: загрузка базы документов вместе с селфи для верификации по Facematch или CPF Match (только для Бразилии).

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

У клиента должен быть действующий контракт или NDA, подписанный с Unico, и он должен находиться на этапе интеграции (исключение при одобрении командой governance).
Проект будет следовать формальным соглашениям TPS (транзакций в секунду). См. раздел Соглашение TPS ниже.
Перед получением продуктивных учётных данных обязательна полная гомологация интеграции для обеспечения качества данных, соответствия payload и стабильной производительности.
Для повторной обработки или импорта необходимо создать выделенную сервисную учётную запись (например, "Reprocessing" или "Legacy_Import").
Для повторной обработки/импорта будет создан выделенный API Key.
(Необязательно) Для повторной обработки/импорта может быть создан выделенный филиал. Этот параметр указывается в payload как subsidiaryId. См. раздел Параметры payload ниже.
API Key и сервисная учётная запись будут деактивированы после согласованного периода или завершения обработки.

Доступные capabilities

Capability	Описание
Identity Verification	Проверяет, принадлежит ли отправленное селфи реальному владельцу идентификатора.
Risk Fraud Classification	Проверяет наличие истории мошеннического поведения, связанного с данным лицом.
Facematch	Проверяет, соответствует ли фотография в документе отправленному селфи.
CPF Match Brazil only	Проверяет, соответствует ли предоставленный CPF номеру CPF, напечатанному на документе. Примечание: не все RG содержат напечатанный CPF.

Требования к селфи

Должно быть отправлено в формате base64.
Изображение должно соответствовать стандарту ICAO (светлый фон, центрированное лицо, отсутствие аксессуаров, затрудняющих идентификацию, надлежащее освещение).
Рекомендуемые размеры: 1080x1920 (книжная ориентация) или 1920x1080 (альбомная ориентация).
Максимальный размер: 800 КБ (при необходимости сжимайте с помощью JPEG 92).
Ориентация: портретная.

Требования к документам

Поддерживаемые типы документов: см. Распознавание документов и повторное использование — Поддерживаемые документы.
Изображения должны включать как лицевую, так и оборотную сторону документа, полностью видимые без обрезки.
Документ должен быть читаемым — чётким, хорошо освещённым и без помех.

Соглашение TPS

Максимальный согласованный TPS для данного проекта составляет 10 TPS.
Распределяйте запросы равномерно по времени, а не отправляйте их большими пакетами.
Этот лимит не должен быть превышен без формального одобрения команды Unico.
Запросы, превышающие лимит, могут быть автоматически отклонены или заблокированы.
Если необходимо временное увеличение, требуется формальное предварительное согласование.

Интеграция

Endpoints

Среда	Базовый URL	Доступ	Примечания
Staging	`https://api.id.uat.unico.app`	Открытый	Обязательно для тестирования
Production	`https://api.id.unico.app`	Только после утверждённой гомологации	Требуется строгий контроль TPS

Обязательные заголовки

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Параметры payload

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}

Поле	Тип	Обязательное	Описание
`subject`	object	Да	Идентификационные данные пользователя.
`subject.duiType`	integer	Да	Идентификатор типа документа. См. значения `duiType` ниже.
`subject.code`	string	Да	CPF или другой идентификатор пользователя.
`subject.name`	string	Да	Полное имя пользователя.
`subject.email`	string	Нет	Электронная почта пользователя.
`subject.phone`	string	Нет	Номер телефона пользователя.
`subject.birthDate`	string	Нет	Дата рождения пользователя (`DD/MM/YYYY`).
`subject.gender`	string	Нет	Пол пользователя (`M` или `F`).
`useCase`	string	Да	Название сценария использования ("Reprocessamento" или "Importação de base").
`subsidiaryId`	string	Нет	UUID филиала (предоставляется Unico).
`imageBase64`	base64	Да	Селфи пользователя, конвертированное в base64.
`document`	object	Нет	Данные документа, связанного с процессом.
`document.purpose`	string	Нет	Назначение документа (например, `"Reprocessamento"`).
`document.documentId`	string	Нет	Идентификатор документа.
`document.files`	array	Нет	Список файлов изображений документа.
`document.files[].data`	base64	Нет	Изображение документа, конвертированное в base64.
`document.files[].faceDocumentMatch`	boolean	Нет	Указывает, совпадает ли лицо в документе с отправленным селфи.

Значения duiType

Страна	Код	Описание
BR	1	Бразильский CPF
MX	2	Мексиканский CURP
US	4	SSN США
BR	5	Бразильский паспорт
AR	6	Аргентинский паспорт
AR	7	Аргентинский DNI
NG	8	Нигерийский NIN
CL	9	Чилийский RUN
EC	10	Эквадорский NI
US	11	Паспорт США
GT	12	Гватемальский CUI
UY	13	Уругвайский CI
BR	14	Бразильский CNPJ
ZZ	15	Адрес электронной почты
ID	16	Индонезийский NIK
ZZ	17	Номер телефона
US	18	Водительское удостоверение США
NG	20	Нигерийский номер верификации банковского счёта (BVN)
US	21	Паспортная карта США
US	22	Поликарбонатный паспорт США
US	23	Идентификационная карта США
TR	24	Турецкий идентификационный номер (TCKN)
MX	25	Мексиканский RFC (физическое лицо)
CO	26	Колумбийский NIT
PE	27	Перуанский RUC
CA	28	Канадский SIN
DK	29	Датский CPR
GB	30	Британский номер национального страхования (NINO)
PL	31	Польский PESEL
SE	32	Шведский личный номер (PNR)
CH	33	Швейцарский номер AHV/AVS
AT	34	Австрийский налоговый номер (STNR)
FI	35	Финский код личной идентификации (HETU)
BE	36	Бельгийский национальный номер (NN)
IT	37	Итальянский налоговый код (Codice Fiscale, CF)
SE	38	Шведский координационный номер (Samordningsnummer)
NO	39	Норвежский национальный идентификационный номер (Fødselsnummer)
PE	40	Перуанский DNI
DE	41	Немецкий налоговый идентификационный номер (IdNr)
NL	42	Голландский идентификационный номер гражданина (BSN)
NG	43	Токен BVN Нигерии (хешированный)
NG	44	Токен NIN Нигерии (хешированный)
PT	45	Португальский налоговый идентификационный номер (NIF)
FR	46	Французский налоговый справочный номер (SPI)
IE	47	Ирландский номер социального страхования (PPSN)
LU	48	Люксембургский национальный идентификационный номер (Matricule)
AR	49	Аргентинское водительское удостоверение (Licencia Nacional de Conducir)
ES	50	Испанский номер иностранца (NIE)
ES	51	Испанский национальный документ, удостоверяющий личность (DNI)
CL	52	Чилийский паспорт
CO	53	Колумбийский паспорт
PE	54	Перуанский паспорт
CO	55	Колумбийское водительское удостоверение (Licencia de Conducción)
CO	56	Колумбийское удостоверение личности гражданина (Cédula de Ciudadanía)
CL	57	Чилийское водительское удостоверение (Licencia de Conducir)
MX	58	Мексиканское водительское удостоверение (Licencia de Conducir)
—	0	Не указано
—	3	Внутренний идентификатор Unico

Важные замечания

Селфи должно соответствовать стандарту ICAO с надлежащим качеством и освещением.
Селфи должно быть в формате base64.
Избегайте массовых отправок без контроля TPS — это может вызвать ограничение скорости (см. раздел Обработка ошибок ниже).
Всегда сначала тестируйте данные и интеграцию в среде staging.

Ответы

Успех — 200 OK

Без документа
С документом (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}

Поле	Тип	Описание
`id`	string	Идентификатор процесса. Сохраните его для будущих запросов или если вы планируете реализовать Валидацию 1:1 позже.
`status`	integer	Статус транзакции.
`unicoId.result`	string	Ответ возможности «Верификация личности».
`riskLevel.result`	string	Результат классификации рисков мошенничества. Возможные значения: `reproved`, `risk-critical`, `risk-high`, `inconclusive`.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}

Поле	Тип	Описание
`id`	string	Идентификатор процесса. Сохраните его для будущих запросов или если вы планируете реализовать Валидацию 1:1 позже.
`status`	integer	Статус транзакции.
`score`	number	Оценка Facematch.
`unicoId.result`	string	Ответ возможности «Верификация личности».
`faceDocumentMatch.faceMatch`	boolean	Соответствует ли фотография в документе отправленному селфи.
`riskLevel.result`	string	Результат классификации рисков мошенничества. Возможные значения: `reproved`, `risk-critical`, `risk-high`, `inconclusive`.

Ошибка обработки изображения

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
}

Распространённые ошибки

Коды в диапазоне 4xx указывают на ошибки валидации предоставленных данных. Коды в диапазоне 5xx указывают на сбои на стороне сервера.

HTTP-код	Тип ошибки	Вероятная причина	Рекомендуемое действие
`400`	Bad Request	Некорректный payload	Проверьте структуру и содержимое.
`401`	Unauthorized	Истёкший или недействительный токен	Сгенерируйте токен заново.
`403`	Forbidden	Неверный API Key или недостаточные разрешения	Проверьте учётные данные.
`429`	Too Many Requests	Превышена частота запросов	Подождите и соблюдайте лимит TPS.
`500+`	Internal Server Error	Внутренний сбой	Повторите попытку через несколько секунд; откройте тикет при постоянных ошибках.

Обработка ошибок

Rate Limit (HTTP 429) необходимо тщательно отслеживать. Перегрузка запросами может заблокировать конвейер.
Всегда соблюдайте TPS, согласованный с Unico (см. раздел Соглашение TPS).
При постоянных сбоях (5xx) выполняйте повторную обработку с контролем retry/backoff.

Область применения​

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

Доступные capabilities​

Требования к селфи​

Требования к документам​

Соглашение TPS​

Интеграция​

Endpoints​

Обязательные заголовки​

Параметры payload​

Важные замечания​

Ответы​

Обработка ошибок​