Создать процесс

MarkdownChatGPTClaude

Это точка входа любой интеграции с Unico API. Ваш бэкенд вызывает её для создания процесса; фронтенд использует полученные токены, чтобы отрендерить iFrame, перенаправить пользователя или инициализировать нативный SDK.

Полный сценарий интеграции см. в разделе Потоки.

Эндпоинт

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

Запрос

Заголовки

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

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

Требования к полю зависят от потока

Является ли поле обязательным, опциональным или неприменимым, зависит от того, с каким flow вы интегрируетесь — прежде чем делать выводы об обязательности поля только по этой таблице, проверьте Потоки для конкретного используемого рецепта.

Поле	Тип	Описание
callbackUri	string	URL, на который перенаправляется пользователь после завершения сценария. Используйте / для потоков нативного SDK, где callback обрабатывается внутри приложения.
flow	string	Идентификатор потока — определяет, какие возможности выполняются. Примеры: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. См. Доступные потоки.
purpose	string	Бизнес-цель. Допустимые значения: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	Тип документа. См. значения duiType ниже.
person.duiValue	string	Номер документа, без форматирования.
person.friendlyName	string	Отображаемое имя пользователя, показываемое в интерфейсе сценария. Максимум 50 символов.
person.phone	string	Номер телефона в формате DDI + DDD + номер, без разделителей. Обязателен при отправке уведомлений по SMS или WhatsApp.
person.email	string	Адрес электронной почты. Обязателен для потоков с электронной подписью.
person.​notifications	array	Каналы уведомлений для отправки ссылки на сценарий. Каждый элемент содержит notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS или NOTIFICATION_CHANNEL_EMAIL.
references	array	Референсные данные для потоков валидации 1:1 и умной ревалидации. Каждый элемент содержит referenceType (REFERENCE_TYPE_IMAGE_BASE64 или REFERENCE_TYPE_PROCESS_ID) и referenceContent (изображение в base64 или UUID процесса). Отправляйте не более одного элемента — более длинный массив отклоняется с кодом 400, а referenceContent не должен быть пустым.
useCase	string	Сценарий умной ревалидации. Обязателен для 🇧🇷 idsmart, idsmart_r2, idsmart_tp1. Примеры: USE_CASE_LOGIN, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	Уникальный идентификатор пользователя в вашей системе. Обязателен для возможности Мультиаккаунт. Уникален в вашей базе, максимум 256 символов, без пробелов.
companyBranchId	string (UUID)	ID филиала. Обязателен только если с сервисным аккаунтом связано более одного филиала.
expiresIn	string	Окно действительности процесса с момента создания. Формат: "3600s". По умолчанию — 7 дней, если не указано.
flowConfig	object	Переопределения конфигурации для конкретного потока.
flowConfig.​biometryCapture.​enabledBackCamera	boolean	Использовать заднюю камеру устройства. Несовместимо с потоками захвата документов или электронной подписи.
contextualization	object	Контекст транзакции, показываемый пользователю во время сценария, чтобы объяснить захват. Доступно клиентам в любом регионе — не ограничено конкретной страной.
contextualization.​company_name	string	Название компании, отображаемое во время сценария. Максимум 20 символов.
contextualization.​currency	string	Код валюты, показываемый пользователю. Допустимые значения: BRL, MXN, USD.
contextualization.​price	number	Сумма транзакции, показываемая пользователю.
contextualization.​locale	object	Локализованный текст, показываемый во время сценария. Ключи: ptBr, enUs, esMx — это единственные поддерживаемые языки для текста, независимо от региона клиента.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	Краткая причина захвата, показываемая во время сценария. Максимум 50 символов.
contextualization.locale.{ptBr|enUs|esMx}.title	string	Заголовок уведомления для клиента, показываемого во время сценария. Максимум 100 символов. Должен передаваться совместно с text. HTML-теги удаляются.
contextualization.locale.{ptBr|enUs|esMx}.text	string	Текст уведомления для клиента, показываемого во время сценария. Максимум 210 символов. Должен передаваться совместно с title. HTML-теги удаляются.
imageBase64	string	Селфи, отправленное напрямую. Принимает JWT захвата от SDK.
document.purpose	enum	Назначение документа. Фиксированный словарь: DOCUMENT_PURPOSE_ONBOARDING, DOCUMENT_PURPOSE_CREDIT_PROCESS, DOCUMENT_PURPOSE_CAR_PURCHASE, DOCUMENT_PURPOSE_PAY_BY_PAYCHECK, DOCUMENT_PURPOSE_FGTS. Используется только в потоках сопоставления лица с документом.
document.​files[].​data	bytes	Новый захват документа, в кодировке base64. Доступно по всему миру, не ограничено Бразилией. Взаимоисключает с document.documentId.
document.documentId	string (UUID)	Повторно использует документ, уже захваченный тем же лицом, вместо нового захвата. Взаимоисключает с document.files[].
expectedResult	object	Имитирует результат возможности в тестовой среде/песочнице и помечает ответ как simulated: true. См. Симуляция результатов (тестовый режим).

Значения 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	Номер телефона

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

Если поток допускает опциональный документ, можно не передавать person.duiType и person.duiValue. После захвата процесс ожидает в состоянии AWAITING_FOR_DOCUMENT, пока ваш бэкенд не отправит документ через Передача документа процесса.

Пример

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "idunicodocs_r2",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flow: 'idunicodocs_r2',
    purpose: 'biometryonboarding',
    clientReference: 'pedido-88216',
    callbackUri: 'https://your-app.example.com/onboarding/callback',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    },
  }),
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

Ответы

200 OK

{
  "process": {
    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "flow": "idunicodocs_r2",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDLIVE",
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDDOCS"
    ],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "companyData": {
      "branchId": "",
      "countryCode": "BRA"
    },
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
    "simulated": false
  }
}

Поле	Тип	Описание
process.id	string (UUID)	Идентификатор процесса. Используйте его, чтобы получить результат через Получение процесса.
process.state	enum	PROCESS_STATE_CREATED — процесс создан, сценарий ещё не начат. PROCESS_STATE_FAILED — создание процесса завершилось ошибкой.
process.result	enum	Результат верификации. Присутствует только когда state = PROCESS_STATE_FINISHED — значения результата, которые может возвращать конкретный поток, см. в Потоках.
process.flow	string	Идентификатор потока, отправленный при создании.
process.purpose	string	Бизнес-цель, отправленная при создании.
process.callbackUri	string	Callback URI, отправленный при создании.
process.​clientReference	string	Ваш внутренний идентификатор, отправленный при создании. Присутствует только если был указан в запросе.
process.​companyBranchId	string (UUID)	ID филиала. Присутствует только если был указан в запросе.
process.​userRedirectUrl	string	URL для перенаправления пользователя (интеграции Web Redirect и iFrame). Не изменяйте этот URL.
process.token	string	JWT для инициализации iFrame Web SDK.
process.webAppToken	string	JWT для инициализации нативных SDK (Android, iOS, Flutter).
process.createdAt	string (date-time)	Метка времени создания процесса.
process.expiresAt	string (date-time)	Метка времени, после которой процесс истекает и не может быть завершён.
process.capacities	array	Возможности, настроенные для этого процесса.
process.​authenticationInfo	object	Информация об аутентификации процесса (пуста в момент создания).
process.person	object	Копия объекта person, отправленного при создании.
process.​companyData.​branchId	string (UUID)	ID филиала, связанного с процессом.
process.​companyData.​countryCode	string	Код страны, связанной с филиалом (например, BR, MX).

Коды ошибок

400 Bad Request

Код	Сообщение	Описание
3	invalid flow	Когда указанный поток не существует.
3	invalid person: friendly name exceeds 50 characters.	Когда отображаемое имя превышает 50 символов.
3	invalid purpose	Когда указанная цель недействительна.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Когда указанный callbackUri недействителен.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Когда указанный email недействителен, а настроено уведомление по email.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	Когда указанный номер телефона недействителен, а настроено уведомление по SMS или WhatsApp.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Когда указанный идентификатор (duiValue) недействителен.
3	invalid expiresIn argument	Когда значение expiresIn недействительно.
3	invalid company_name argument in process contextualization, max length is 20	Когда contextualization.​company_name превышает 20 символов.
3	title and text must be provided together in process contexts	Когда в локали указано только одно из значений title или text.
3	invalid title argument in process contexts, max length is 100	Когда title локали превышает 100 символов.
3	invalid text argument in process contexts, max length is 210	Когда text локали превышает 210 символов.
3	invalid reason argument in process contexts, max length is 50	Когда reason локали превышает 50 символов.
3	The references array must contain at most one element.	Когда в references отправлено более одного элемента.
3	The references[].referenceContent field is missing.	Когда referenceContent пуст.
3	The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.	Когда referenceType не входит в число поддерживаемых значений.
3	A reference is required for this flow.	Когда поток требует референс, а он не был отправлен. Отправьте references[0] с referenceType PROCESS_ID или IMAGE_BASE64.
9	The referenceProcessId field is invalid.	Когда референсный процесс не существует или не может быть повторно использован. Указывает поле, которое вы отправили — bioTokenId, если вы отправили его.
3	INVALID_IMAGE	Когда изображение не является корректным base64 или похоже на попытку инъекции.
3	INVALID_DUI	Когда номер документа нестандартный или не существует.
3	IMAGE_TOO_LARGE	Когда изображение превышает максимальный размер 800 КБ.
3	UNSUPPORTED_IMAGE_FORMAT	Когда формат изображения не PNG, JPEG или WebP.
3	MISSING_IMAGE	Когда изображение обязательно для этого потока, но не было отправлено.
3	MISSING_NAME	Когда имя обязательно для этого потока, но не было отправлено.
3	MISSING_DUI	Когда номер документа обязателен для этого потока, но не был отправлен.
3	MISSING_PERSON	Когда объект person обязателен для этого потока, но не был отправлен.
3	INVALID_REQUEST	Когда тело запроса пустое (null) или не может быть интерпретировано.
3	TOKEN_ALREADY_USED	Когда токен захвата уже был использован. Он одноразовый.
3	TOKEN_EXPIRED	Когда токен захвата истёк. Он должен быть использован в течение 10 минут.
3	INVALID_BUNDLE	Когда запрос не соответствует требованиям безопасности.
3	INVALID_NAME	Когда имя длиннее максимально допустимого.
3	INVALID_EMAIL	Когда адрес электронной почты некорректен или слишком длинный.
3	INVALID_PHONE	Когда номер телефона длиннее 20 символов.
3	INVALID_DUI_TYPE	Когда тип документа не входит в число поддерживаемых значений.
3	INVALID_CLIENT_REFERENCE	Когда clientReference слишком длинный или содержит пробел либо #.
3	INVALID_CONSENT_TYPE	Когда consentType не является NONE, DIRECT или INDIRECT.
3	INVALID_USE_CASE	Когда useCase не распознан или слишком длинный.
3	INVALID_DEVICE_TRUST_TOKEN	Когда токен доверия устройства недействителен или уже был использован.
3	TOO_MANY_REFERENCES	Когда в references отправлено более одного элемента.
3	INVALID_REFERENCE_TYPE	Когда referenceType не равен IMAGE_BASE64 или PROCESS_ID.
3	INVALID_REFERENCE_PROCESS	Когда ID референсного процесса не является допустимым идентификатором.
3	REFERENCE_PROCESS_NOT_FOUND	Когда референсный процесс не существует.
3	REFERENCE_PROCESS_NOT_READY	Когда у референсного процесса нет результата, доступного для повторного использования, либо он уже был использован.
3	REFERENCE_SELFIE_NOT_FOUND	Когда референсный процесс не содержит селфи для повторного использования.
3	INVALID_CAPTURE_TOKEN	Когда захваченное изображение не является допустимым токеном, созданным SDK захвата.
3	INVALID_CAPTURE_SIGNATURE	Когда подпись токена захвата не проходит проверку.
3	PRIOR_CAPTURE_NOT_FOUND	Когда предыдущий захват, на котором строится этот запрос, не может быть найден. Начните процесс заново.
3	PRIOR_CAPTURE_IN_PROGRESS	Когда предыдущий захват ещё не завершён. Повторите попытку позже.
3	PRIOR_CAPTURE_FAILED	Когда предыдущий захват не удалось завершить. Начните процесс заново.
3	INVALID_DOCUMENT	Когда файл документа не читается, защищён паролем или имеет неподдерживаемый формат.
3	INVALID_AUTH_PROCESS	Когда document.authProcessId недействителен, истёк или принадлежит другому лицу.
3	INVALID_DOCUMENT_PURPOSE	Когда document.purpose не входит в число поддерживаемых значений.
3	PROCESS_REUSE_NOT_ENABLED	Когда поток не разрешает повторное использование предыдущего процесса без изображения. Отправьте изображение.
9	PROCESS_FAILED	Когда процесс достиг финального сбоя во время создания.
9	Tenant API key is not configured	Когда API-ключ не настроен должным образом.

401 Unauthorized

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

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

403 Forbidden

Код	Сообщение	Описание
7	INVALID_API_KEY	Когда API-ключ недействителен или отсутствует.
7	INVALID_AUTH_TOKEN	Когда токен аутентификации недействителен.
7	PERMISSION_DENIED	Когда учётные данные действительны, но не дают права на это действие.
7	TOKEN_TENANT_MISMATCH	Когда токен захвата был выпущен для другого тенанта.
7	MISSING_ACCESS_TOKEN	Когда заголовок авторизации отсутствует.

404 Not Found

Код	Сообщение	Описание
5	NO_RESULTS_FOUND	Когда документ, указанный в запросе, не может быть найден.

429 Too Many Requests

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

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

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

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

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

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

500 Internal Server Error

Код	Сообщение	Описание
13	Internal failure! Try again later	Когда произошла внутренняя ошибка.

Что дальше

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