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

Создание процесса с документом

Этот endpoint обрабатывает два документных потока, использующих один и тот же путь, но различающихся параметрами тела запроса:

  • Новый захват — отправляет изображения документа в формате base64 для обработки (требуется document.files).
  • Повторное использование — пропускает захват, ссылаясь на ранее захваченный документ (требуется document.documentId).

Активный поток определяется наличием document.documentId в теле запроса.

Перед созданием процесса с документом используйте Get Reusable Documents, чтобы проверить, есть ли у пользователя уже доступный документ.

Полный процесс интеграции описан в разделе Обзор API.

Endpoint​

СредаURL
ProductionPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Запрос​

Заголовки
ЗаголовокЗначение
AuthorizationBearer <access_token> (см. Аутентификация)
APIKEYВыданный API-ключ с включёнными функциями захвата и повторного использования документов.
Content-Typeapplication/json
Параметры тела запроса
ПолеТипОбязательноеОписание
subject.duiTypeintegerдаИдентификатор типа документа. См. значения duiType ниже.
subject.codestringдаЗначение идентификатора пользователя согласно subject.duiType. Без точек и дефисов.
subject.namestringнетПолное имя.
subject.genderstringнетM или F.
subject.birthDatestring (ISO 8601)нетДата рождения (YYYY-MM-DD).
subject.emailstringнетАдрес электронной почты.
subject.phonestringнетНомер телефона в формате E.164.
document.purposestringдаБизнес-цель. Значения: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessIdstringдаИдентификатор биометрического процесса, связанного с захватом этого документа.
document.filesarrayдаИзображения документа в формате base64 (лицевая и/или обратная сторона).
document.files[].datastringдаИзображение документа в формате base64 (PNG, JPEG или WebP, не более 800 КБ).
subsidiaryIdstringнетИдентификатор филиала — требуется только при наличии нескольких филиалов.
Значения duiType
СтранаКодОписание
BR1Бразильский CPF
MX2Мексиканский CURP
US4SSN США
BR5Бразильский паспорт
AR6Аргентинский паспорт
AR7Аргентинский DNI
NG8Нигерийский NIN
CL9Чилийский RUN
EC10Эквадорский NI
US11Паспорт США
GT12Гватемальский CUI
UY13Уругвайский CI
BR14Бразильский CNPJ
ZZ15Адрес электронной почты
ID16Индонезийский NIK
ZZ17Номер телефона
US18Водительское удостоверение США
NG20Нигерийский номер верификации банковского счёта (BVN)
US21Паспортная карта США
US22Поликарбонатный паспорт США
US23Идентификационная карта США
TR24Турецкий идентификационный номер (TCKN)
MX25Мексиканский RFC (физическое лицо)
CO26Колумбийский NIT
PE27Перуанский RUC
CA28Канадский SIN
DK29Датский CPR
GB30Британский номер национального страхования (NINO)
PL31Польский PESEL
SE32Шведский личный номер (PNR)
CH33Швейцарский номер AHV/AVS
AT34Австрийский налоговый номер (STNR)
FI35Финский код личной идентификации (HETU)
BE36Бельгийский национальный номер (NN)
IT37Итальянский налоговый код (Codice Fiscale, CF)
SE38Шведский координационный номер (Samordningsnummer)
NO39Норвежский национальный идентификационный номер (Fødselsnummer)
PE40Перуанский DNI
DE41Немецкий налоговый идентификационный номер (IdNr)
NL42Голландский идентификационный номер гражданина (BSN)
NG43Токен BVN Нигерии (хешированный)
NG44Токен NIN Нигерии (хешированный)
PT45Португальский налоговый идентификационный номер (NIF)
FR46Французский налоговый справочный номер (SPI)
IE47Ирландский номер социального страхования (PPSN)
LU48Люксембургский национальный идентификационный номер (Matricule)
AR49Аргентинское водительское удостоверение (Licencia Nacional de Conducir)
ES50Испанский номер иностранца (NIE)
ES51Испанский национальный документ, удостоверяющий личность (DNI)
CL52Чилийский паспорт
CO53Колумбийский паспорт
PE54Перуанский паспорт
CO55Колумбийское водительское удостоверение (Licencia de Conducción)
CO56Колумбийское удостоверение личности гражданина (Cédula de Ciudadanía)
CL57Чилийское водительское удостоверение (Licencia de Conducir)
MX58Мексиканское водительское удостоверение (Licencia de Conducir)
—0Не указано
—3Внутренний идентификатор Unico

Пример​

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

Ответы​

200 OK
{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}
ПолеТипОписание
idstring (UUID)Идентификатор процесса.
statusinteger3 (завершён успешно), 5 (завершён с ошибкой).
document.idstringИдентификатор захваченного документа. Используйте это значение в будущих запросах document.documentId для повторного использования.
document.typestringИдентифицированный тип документа в виде полного имени словаря. См. значения document.type ниже.
document.cpfMatchbooleantrue, если идентификатор, извлечённый из документа, совпадает с subject.code.
document.faceMatchbooleantrue, если лицо на документе совпадает с биометрическим селфи из document.authProcessId.
document.contentobjectПоля, извлечённые с помощью OCR. Структура зависит от типа документа — нажмите здесь, чтобы посмотреть описание полей.
document.fileUrlsarrayВременные URL (действительны 10 минут) для скачивания изображений документа.

В document.content присутствуют только успешно извлечённые поля; всё, что OCR не смог распознать, опускается, а не возвращается пустым.

Значения document.type
Единая схема

Все типы документов, использующие единую схему — unified_schema в справочнике полей — возвращаются в document.type в виде unico.moja.dictionary.<country>.generic.v1.<DocumentType>, где <country> — код страны ISO 3166-1 alpha-2 в нижнем регистре, а <DocumentType> — идентифицированный тип. Например:

  • unico.moja.dictionary.ar.generic.v1.IdCard: Удостоверение личности Аргентины
  • unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: Поликарбонатный паспорт США
Отдельные схемы

Типы документов, использующие собственную схему полей — перечисленные в specific_document_schemas в справочнике полей — приведены в таблице ниже:

СтранаЗначениеДокумент
BRunico.moja.dictionary.br.rg.v2.RgRG
BRunico.moja.dictionary.br.cnh.v2.CnhCNH (водительское удостоверение)
BRunico.moja.dictionary.br.cin.v1.CinCIN
BRunico.moja.dictionary.br.passaporte.v1.PassaporteПаспорт
MXunico.moja.dictionary.mx.ine.v1.IneИзбирательное удостоверение INE
MXunico.moja.dictionary.mx.lpc.v1.LpcLicencia para conducir (водительское удостоверение)
MXunico.moja.dictionary.mx.pasaporte.v1.PasaporteПаспорт
—unico.moja.dictionary.other.unknown.v1.UnknownТип не удалось определить — document.content пуст

Извлечение OCR не выполняется и ни одно поле не возвращается, когда document.type равен unico.moja.dictionary.other.unknown.v1.Unknown.

Коды ошибок​

КодСообщениеОписание
99989The document is invalid.Объект document имеет неверную структуру.
99988The document is empty.Объект document отсутствует в теле запроса.
20900O base64 informado não é válido.Параметр base64 недействителен. Возможные причины: это не изображение или попытка инъекции.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.Разрешение загруженного изображения слишком низкое.
20509The subject.name field is invalid.subject.name содержит недопустимые символы.
20508The subject.gender field is invalid.subject.gender должен быть M или F.
20507O parâmetro subject.code é inválido.Нестандартное или несуществующее значение идентификатора.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.Размер изображения превышает 800 КБ; выполните сжатие до JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.Формат base64 недействителен или не поддерживается.
20068The document.documentId or document.files parameter must be present.Не указаны ни document.documentId, ни document.files.
20067The document.purpose parameter is invalid.Нераспознанное значение в document.purpose.
20066The document.authProcessId parameter is invalid.Недопустимое значение в document.authProcessId.
20062The useCase field is invalid.Нераспознанное значение в поле useCase.
20021The subject.phone field is invalid.Формат subject.phone недействителен (международный код + код региона + номер, 13 символов).
20019The subject.birthDate field is invalid.subject.birthDate не соответствует формату ISO 8601 (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.Отсутствует параметр с изображением документа.
20008The subject.email field is invalid.Недействительный формат email в subject.email.
20005O parâmetro subject.code não foi informado.Отсутствует параметр subject.code.
20004O parâmetro subject não foi informado.Отсутствует параметр subject.
20003The request body is missing or invalid.Тело запроса отсутствует или имеет неверный формат.
20002O parâmetro APIKey não foi informado.Параметр APIKEY отсутствует в заголовке запроса.
20001O parâmetro authtoken não foi informado.Параметр токена интеграции отсутствует в заголовке запроса.
10508The JWT with the captured face has already been used.JWT может быть использован только один раз.
10507The JWT with the captured face is expired.JWT истёк; должен быть отправлен в течение 10 минут.
10506The imageBase64 field is not a valid JWT from SDK.imageBase64 не является действительным JWT, сгенерированным SDK.

Дальнейшие шаги​

  • Чтобы проверить наличие документа перед этим вызовом, см. Get Reusable Documents.
  • Для создания биометрического процесса (требуется для document.authProcessId), см. Create Process.
Последнее обновление