Передача документа процесса

Передача документа процессаPOST

Создайте процесс без документа, дайте пользователю завершить захват, а затем отправьте документ с вашего бэкенда. После этого процесс завершается.

Markdown ChatGPT Claude

Жизненный цикл

Ваш бэкенд создаёт процесс через Создать процесс без person.duiType и person.duiValue. Поток должен допускать опциональный документ. Процесс начинается в состоянии PROCESS_STATE_CREATED.
Пользователь проходит сценарий и выполняет захват.
Unico API переводит процесс в состояние AWAITING_FOR_DOCUMENT — его возвращает Получение процесса, пока процесс ожидает документ. Вы уже можете прочитать частичные результаты возможностей, которые не зависят от duiValue.
Ваш бэкенд вызывает этот эндпоинт с ID процесса в URL и документом в теле запроса. Затем Unico API завершает процесс, и он переходит в состояние PROCESS_STATE_FINISHED.

Ответ не содержит итогового результата

Получите итоговое состояние и результат через Получение процесса или дождитесь вебхука.

Эндпоинт

Среда	URL
Production	`POST https://api.idcloud.unico.app/client/v1/process/{processId}/document`
Sandbox	`POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document`

Запрос

Заголовки

Заголовок	Значение
`Authorization`	`Bearer <access_token>` (см. Аутентификация)
`Content-Type`	`application/json`

Учётным данным требуется то же разрешение, что и для вызова Создать процесс.

Параметры пути

Параметр	Тип	Обязателен	Описание
`processId`	string (UUID)	да	Идентификатор процесса, возвращённый Создать процесс.

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

Поле	Тип	Обязателен	Описание
`duiType`	enum	да	Тип документа. `DUI_TYPE_UNSPECIFIED` отклоняется. См. значения `duiType` ниже.
`duiValue`	string	да	Номер документа без форматирования. До 320 символов.

Значения duiType

Страна	Значение	Описание
AR	`DUI_TYPE_AR_PASSPORT`	Аргентинский паспорт
AR	`DUI_TYPE_AR_DNI`	Аргентинский DNI
AR	`DUI_TYPE_AR_LNC`	Аргентинское водительское удостоверение (Licencia Nacional de Conducir)
AT	`DUI_TYPE_AT_STNR`	Австрийский налоговый номер (STNR)
BE	`DUI_TYPE_BE_NN`	Бельгийский национальный номер (NN)
BR	`DUI_TYPE_BR_CPF`	Бразильский CPF
BR	`DUI_TYPE_BR_PASSPORT`	Бразильский паспорт
BR	`DUI_TYPE_BR_CNPJ`	Бразильский CNPJ
CA	`DUI_TYPE_CA_SIN`	Канадский SIN
CH	`DUI_TYPE_CH_AHV`	Швейцарский номер AHV/AVS
CL	`DUI_TYPE_CL_RUN`	Чилийский RUN
CL	`DUI_TYPE_CL_PASSPORT`	Чилийский паспорт
CL	`DUI_TYPE_CL_LICENCIA_CONDUCIR`	Чилийское водительское удостоверение (Licencia de Conducir)
CO	`DUI_TYPE_CO_NIT`	Колумбийский NIT
CO	`DUI_TYPE_CO_PASSPORT`	Колумбийский паспорт
CO	`DUI_TYPE_CO_LICENCIA_CONDUCCION`	Колумбийское водительское удостоверение (Licencia de Conducción)
CO	`DUI_TYPE_CO_CC`	Колумбийское удостоверение личности гражданина (Cédula de Ciudadanía)
DE	`DUI_TYPE_DE_IDNR`	Немецкий налоговый идентификационный номер (IdNr)
DK	`DUI_TYPE_DK_CPR`	Датский CPR
EC	`DUI_TYPE_EC_NI`	Эквадорский NI
ES	`DUI_TYPE_ES_NIE`	Испанский номер иностранца (NIE)
ES	`DUI_TYPE_ES_DNI`	Испанский национальный документ, удостоверяющий личность (DNI)
FI	`DUI_TYPE_FI_HETU`	Финский код личной идентификации (HETU)
FR	`DUI_TYPE_FR_SPI`	Французский налоговый справочный номер (SPI)
GB	`DUI_TYPE_GB_NINO`	Британский номер национального страхования (NINO)
GT	`DUI_TYPE_GT_CUI`	Гватемальский CUI
ID	`DUI_TYPE_ID_NIK`	Индонезийский NIK
IE	`DUI_TYPE_IE_PPSN`	Ирландский номер социального страхования (PPSN)
IT	`DUI_TYPE_IT_CF`	Итальянский налоговый код (Codice Fiscale, CF)
LK	`DUI_TYPE_LK_NIC`	Шри-ланкийский NIC
LU	`DUI_TYPE_LU_MATRICULE`	Люксембургский национальный идентификационный номер (Matricule)
MX	`DUI_TYPE_MX_CURP`	Мексиканский CURP
MX	`DUI_TYPE_MX_RFC_PERSONA_FISICA`	Мексиканский RFC (физическое лицо)
MX	`DUI_TYPE_MX_LICENCIA_CONDUCIR`	Мексиканское водительское удостоверение (Licencia de Conducir)
NG	`DUI_TYPE_NG_NIN`	Нигерийский NIN
NG	`DUI_TYPE_NG_BVN`	Нигерийский номер верификации банковского счёта (BVN)
NG	`DUI_TYPE_NG_BVN_TOKEN`	Токен BVN Нигерии (хешированный)
NG	`DUI_TYPE_NG_NIN_TOKEN`	Токен NIN Нигерии (хешированный)
NL	`DUI_TYPE_NL_BSN`	Голландский идентификационный номер гражданина (BSN)
NO	`DUI_TYPE_NO_FNR`	Норвежский национальный идентификационный номер (Fødselsnummer)
PE	`DUI_TYPE_PE_RUC`	Перуанский RUC
PE	`DUI_TYPE_PE_DNI`	Перуанский DNI
PE	`DUI_TYPE_PE_PASSPORT`	Перуанский паспорт
PL	`DUI_TYPE_PL_PESEL`	Польский PESEL
PT	`DUI_TYPE_PT_NIF`	Португальский налоговый идентификационный номер (NIF)
SE	`DUI_TYPE_SE_PNR`	Шведский личный номер (PNR)
SE	`DUI_TYPE_SE_SAMORDNINGSNUMMER`	Шведский координационный номер (Samordningsnummer)
TR	`DUI_TYPE_TR_TCKN`	Турецкий идентификационный номер (TCKN)
US	`DUI_TYPE_US_SSN`	SSN США
US	`DUI_TYPE_US_PASSPORT`	Паспорт США
US	`DUI_TYPE_US_DRIVER_LICENSE`	Водительское удостоверение США
US	`DUI_TYPE_US_PASSPORT_CARD`	Паспортная карта США
US	`DUI_TYPE_US_POLYCARBONATE_PASSPORT`	Поликарбонатный паспорт США
US	`DUI_TYPE_US_ID_CARD`	Идентификационная карта США
UY	`DUI_TYPE_UY_CI`	Уругвайский CI
ZZ	`DUI_TYPE_ZZ_EMAIL`	Адрес электронной почты
ZZ	`DUI_TYPE_ZZ_PHONE_NUMBER`	Номер телефона

Когда вызов принимается

Процесс находится в состоянии AWAITING_FOR_DOCUMENT: пользователь уже завершил захват.
Срок действия процесса не истёк.
Поток допускает опциональный документ.

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

Пример

cURL
Node.js

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678909"
  }'

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

Ответы

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

Поле	Тип	Описание
`processId`	string (UUID)	Идентификатор процесса.
`duiType`	enum	Тип документа, зарегистрированный для процесса.
`duiValue`	string	Номер документа, зарегистрированный для процесса.

Значения в примере являются заглушками.

Коды ошибок

Код	Описание
`3`	`processId` отсутствует или недействителен, `duiType` не указан, либо `duiValue` пуст или длиннее 320 символов.
`9`	Процесс не ожидает документ (в том числе если документ уже передан), истёк или завершён, либо поток не допускает опциональный документ.

Код	Сообщение	Описание
—	Jwt header is an invalid JSON	Когда использованный токен доступа содержит некорректные символы.
—	Jwt is expired	Когда использованный токен доступа истёк.

Код	Описание
`7`	У учётных данных нет разрешения, необходимого для Создать процесс.

Код	Описание
`5`	Процесс не существует или не принадлежит вашей компании.

Достигнут лимит запросов. Когда ваша система получает ошибку HTTP 429, необходимо реализовать механизмы для предотвращения каскадных сбоев и избежания усугубления ограничения.

Лучшие практики:

Период ожидания (backoff): Немедленно остановите или снизьте частоту последующих запросов из вашей системы. Не повторяйте неудачные запросы непрерывно в тесном цикле.
Очередь и ограничение (Queueing & throttling): Буферизируйте или ставьте в очередь исходящие запросы на вашей стороне для контроля потока трафика перед их повторной отправкой.
Экспоненциальный backoff с джиттером: При повторных попытках увеличивайте время ожидания экспоненциально между попытками (например, 1 с, 2 с, 4 с, 8 с) и добавляйте небольшую случайную задержку ("джиттер"), чтобы предотвратить эффект стада, когда все запросы из очереди повторяются в одну и ту же миллисекунду.

предупреждение

Непрерывная отправка запросов к эндпоинту с ограничением частоты без применения backoff может продлить период ограничения и серьезно снизить операционную пропускную способность вашей системы. Правильное ограничение запросов на вашей стороне обеспечивает более плавную и устойчивую интеграцию.

Информацию о лимитах по умолчанию, увеличении запросов и дополнительные сведения см. в разделе Лимиты запросов.

Код	Описание
`13`	Не удалось сохранить документ.

примечание

Перед сохранением документ регистрируется в сервисе идентификации. Если эта регистрация не удалась, вызов возвращает статус этой ошибки.

Что дальше

Чтобы получить итоговое состояние и результат, см. Получение процесса.
Чтобы получать уведомление о завершении процесса, см. Вебхуки и события.

Жизненный цикл​

Эндпоинт​

Запрос​

Пример​

Ответы​

Коды ошибок​

Что дальше​