Перейти к основному содержимому

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

Это руководство описывает, как выполнить повторную обработку или импорт биометрической базы на платформе 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 BrazilBrazil onlyПроверяет, соответствует ли предоставленный CPF номеру CPF, напечатанному на документе. Примечание: не все RG содержат напечатанный CPF.

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

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

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

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

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

Интеграция​

Endpoints​

СредаБазовый URLДоступПримечания
Staginghttps://api.id.uat.unico.appОткрытыйОбязательно для тестирования
Productionhttps://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"
      }
    ]
  }
}
ПолеТипОбязательноеОписание
subjectobjectДаИдентификационные данные пользователя.
subject.duiTypeintegerДаИдентификатор типа документа. См. значения duiType ниже.
subject.codestringДаCPF или другой идентификатор пользователя.
subject.namestringДаПолное имя пользователя.
subject.emailstringНетЭлектронная почта пользователя.
subject.phonestringНетНомер телефона пользователя.
subject.birthDatestringНетДата рождения пользователя (DD/MM/YYYY).
subject.genderstringНетПол пользователя (M или F).
useCasestringДаНазвание сценария использования ("Reprocessamento" или "Importação de base").
subsidiaryIdstringНетUUID филиала (предоставляется Unico).
imageBase64base64ДаСелфи пользователя, конвертированное в base64.
documentobjectНетДанные документа, связанного с процессом.
document.purposestringНетНазначение документа (например, "Reprocessamento").
document.documentIdstringНетИдентификатор документа.
document.filesarrayНетСписок файлов изображений документа.
document.files[].database64НетИзображение документа, конвертированное в base64.
document.files[].faceDocumentMatchbooleanНетУказывает, совпадает ли лицо в документе с отправленным селфи.
Значения duiType
ЗначениеОписание
0Не указано
1Бразилия — CPF
2Мексика — CURP
3Внутренний идентификатор Unico
4США — SSN
5Бразилия — Паспорт
6Аргентина — Паспорт
7Аргентина — DNI
8Нигерия — NIN
9Чили — RUN
10Эквадор — NI
11США — Паспорт
12Гватемала — CUI
13Уругвай — CI
15Адрес электронной почты
16Индонезия — NIK
17Номер телефона
18США — Водительское удостоверение

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

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

Ответы​

Успех — 200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}
ПолеТипОписание
idstringИдентификатор процесса. Сохраните его для будущих запросов или если вы планируете реализовать Валидацию 1:1 позже.
statusintegerСтатус транзакции.
unicoId.resultstringОтвет возможности «Верификация личности».
riskLevel.resultstringРезультат классификации рисков мошенничества. Возможные значения: reproved, risk-critical, risk-high, inconclusive.

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

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

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

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

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

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

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