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

Markdown

Это руководство описывает, как выполнить повторную обработку или импорт биометрической базы на платформе 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

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

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

Ответы​

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