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

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

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

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

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

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

Endpoint

Среда	URL
Production	`POST https://api.id.unico.app/processes/v1`
Sandbox	`POST https://api.id.uat.unico.app/processes/v1`

Запрос

Заголовки

Заголовок	Значение
`Authorization`	`Bearer <access_token>` (см. Аутентификация)
`APIKEY`	Выданный API-ключ с включёнными функциями захвата и повторного использования документов.
`Content-Type`	`application/json`

Параметры тела запроса

Новый захват
Повторное использование

Поле	Тип	Обязательное	Описание
`subject.duiType`	string	да	Тип идентификатора. Возможные значения: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	да	Значение идентификатора пользователя согласно `subject.duiType`. Без точек и дефисов.
`subject.name`	string	нет	Полное имя.
`subject.gender`	string	нет	`M` или `F`.
`subject.birthDate`	string (ISO 8601)	нет	Дата рождения (`YYYY-MM-DD`).
`subject.email`	string	нет	Адрес электронной почты.
`subject.phone`	string	нет	Номер телефона в формате E.164.
`document.purpose`	string	да	Бизнес-цель. Значения: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	да	Идентификатор биометрического процесса, связанного с захватом этого документа.
`document.files`	array	да	Изображения документа в формате base64 (лицевая и/или обратная сторона).
`document.files[].data`	string	да	Изображение документа в формате base64 (PNG, JPEG или WebP, не более 800 КБ).
`subsidiaryId`	string	нет	Идентификатор филиала — требуется только при наличии нескольких филиалов.

Поле	Тип	Обязательное	Описание
`subject.duiType`	string	да	Тип идентификатора. Возможные значения: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	да	Значение идентификатора пользователя согласно `subject.duiType`. Без точек и дефисов.
`subject.name`	string	нет	Полное имя.
`subject.gender`	string	нет	`M` или `F`.
`subject.birthDate`	string (ISO 8601)	нет	Дата рождения (`YYYY-MM-DD`).
`subject.email`	string	нет	Адрес электронной почты.
`subject.phone`	string	нет	Номер телефона в формате E.164.
`document.purpose`	string	да	Бизнес-цель. Значения: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	да	Идентификатор биометрического процесса, связанного с данным документом.
`document.documentId`	string	да	Идентификатор ранее захваченного документа (полученный из Get Reusable Documents). При наличии `document.files` можно не указывать.
`subsidiaryId`	string	нет	Идентификатор филиала — требуется только при наличии нескольких филиалов.

Пример

Новый захват — cURL
Новый захват — Node.js
Повторное использование — cURL
Повторное использование — Node.js

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": "DUI_TYPE_BR_CPF",
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

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": "DUI_TYPE_BR_CPF",
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

Ответы

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"
    ]
  }
}

Поле	Тип	Описание
`id`	string (UUID)	Идентификатор процесса.
`status`	integer	`3` (завершён успешно), `5` (завершён с ошибкой).
`document.id`	string	Идентификатор захваченного документа. Используйте это значение в будущих запросах `document.documentId` для повторного использования.
`document.type`	string	Идентифицированный тип документа. Возможные значения: `unico.moja.dictionary.br.rg.v2.Rg`, `unico.moja.dictionary.br.cnh.v2.Cnh`, `unico.moja.dictionary.br.cin.v1.Cin`, `unico.moja.dictionary.br.passaporte.v1.Passaporte`.
`document.cpfMatch`	boolean	`true`, если идентификатор, извлечённый из документа, совпадает с `subject.code`.
`document.faceMatch`	boolean	`true`, если лицо на документе совпадает с биометрическим селфи из `document.authProcessId`.
`document.content`	object	Поля, извлечённые с помощью OCR. Структура зависит от типа документа — см. ниже.
`document.fileUrls`	array	Временные URL (действительны 10 минут) для скачивания изображений документа.

400 Bad Request

Тело запроса некорректно, изображение недействительно или отсутствуют обязательные поля. См. Коды ошибок ниже.

403 Forbidden

Bearer-токен или APIKEY отсутствует, истёк или недействителен. См. Аутентификация.

409 Conflict

Указанный processId уже существует для данного тенанта. См. Коды ошибок ниже.

Коды ошибок

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

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

Код	Сообщение	Описание
`30017`	User does not have permission to perform this action.	Некорректный JWT или пользователь без разрешения на выполнение данной операции.
`10502`	O token informado está expirado.	Срок действия токена доступа истёк.
`10501`	O token informado é inválido.	Токен аутентификации недействителен.
`10201`	O AppKey informado é inválido.	APIKEY недействителен или не существует.

Код	Сообщение	Описание
`20073`	The processID already exists.	Указанный `processId` уже существует для данного тенанта.

Код	Сообщение	Описание
`99999`	Internal failure! Try again later	Внутренняя ошибка сервера.

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

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

Endpoint​

Запрос​

Пример​

Ответы​

Коды ошибок​

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