Создание процесса

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

Полный поток интеграции см. в Обзор Web & 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`

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

Поле	Тип	Обязательный	Описание
`callbackUri`	string	да	URL, на который пользователь перенаправляется после завершения пути. Используйте `/` для потоков нативного SDK, где обратный вызов обрабатывается внутри приложения.
`flow`	string	да	Идентификатор потока -- определяет, какие возможности выполняются. Примеры: `idunicodocs`, `idunicosign`, `idchecktrust`, `idtoken`, `idsmart`. См. Доступные потоки.
`purpose`	string	да	Бизнес-назначение. Допустимые значения: `creditprocess`, `biometryonboarding`, `carpurchase`, `ageverification`.
`person.duiType`	enum	да	Тип документа. Допустимые значения: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_BR_PASSPORT`, `DUI_TYPE_AR_PASSPORT`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_CL_RUN`, `DUI_TYPE_EC_NI`, `DUI_TYPE_US_PASSPORT`, `DUI_TYPE_GT_CUI`, `DUI_TYPE_UY_CI`, `DUI_TYPE_ZZ_EMAIL`, `DUI_TYPE_ID_NIK`, `DUI_TYPE_ZZ_PHONE_NUMBER`, `DUI_TYPE_US_DRIVER_LICENSE`, `DUI_TYPE_NG_BVN`, `DUI_TYPE_MX_RFC_PERSONA_FISICA`, `DUI_TYPE_CO_NIT`, `DUI_TYPE_PE_RUC`, `DUI_TYPE_CA_SIN`, `DUI_TYPE_DK_CPR`, `DUI_TYPE_GB_NINO`, `DUI_TYPE_PL_PESEL`, `DUI_TYPE_SE_PNR`, `DUI_TYPE_AT_STNR`, `DUI_TYPE_FI_HETU`.
`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`.
`bioTokenId`	string (UUID)	условно	Устарело. Используйте `references` вместо этого. ID ссылочного биометрического процесса. Обязателен для потоков Валидации 1:1 (`idtoken`, `idtokentrust`, `idtokensign`) и Умной ревалидации (`idsmart`).
`references`	array	условно	Входные данные для потоков Валидации 1:1 и Умной ревалидации, заменяющие `bioTokenId`. Каждый элемент содержит `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` или `REFERENCE_TYPE_PROCESS_ID`) и `referenceContent` (base64-изображение или UUID процесса).
`useCase`	string	условно	Вариант использования Умной ревалидации. Обязателен для `idsmart`. Примеры: `USE_CASE_LOGIN`, `USE_CASE_IDENTITY_REVALIDATION_7_DAYS`, `USE_CASE_FIN_TRANSACTIONS`.
`clientReference`	string	нет	Ваш внутренний идентификатор для этого процесса (внешний ключ для перекрёстных ссылок в портале).
`companyBranchId`	string (UUID)	нет	ID филиала. Обязателен только если у сервисного аккаунта более одного связанного филиала.
`expiresIn`	string	нет	Окно действия процесса с момента создания. Формат: `"3600s"`. По умолчанию 7 дней, если не указано.
`flow_config`	object	нет	Переопределения конфигурации для каждого потока.
`flow_config.biometry_capture.enabled_back_camera`	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-теги удаляются.

Пример

cURL
Node.js

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

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({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

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

Ответы

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

Поле	Тип	Описание
`process.id`	string (UUID)	Идентификатор процесса. Используйте его для получения результата через Получение процесса.
`process.state`	enum	`PROCESS_STATE_CREATED` -- процесс создан, путь ещё не начат. `PROCESS_STATE_FAILED` -- создание процесса не удалось.
`process.flow`	string	Идентификатор потока, отправленный при создании.
`process.purpose`	string	Бизнес-назначение, отправленное при создании.
`process.callbackUri`	string	URI обратного вызова, отправленный при создании.
`process.clientReference`	string	Ваш внутренний идентификатор, отправленный при создании. Присутствует только если указан в запросе.
`process.companyBranchId`	string (UUID)	ID филиала. Присутствует только если указан в запросе.
`process.userRedirectUrl`	string	URL для перенаправления пользователя (интеграции Web Redirect и iFrame). Не изменяйте этот URL.
`process.token`	string	JWT для инициализации Web SDK iFrame.
`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

Возвращается, когда тело запроса содержит ошибки, обязательные поля отсутствуют или значение flow неизвестно.

401 Unauthorized

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

429 Too Many Requests

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

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

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

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

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

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

Коды ошибок

400 Bad Request
401 Unauthorized
429 Too Many Requests
500 Internal Server Error

Код	Сообщение	Описание
`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 символов.
`9`	XX ID Apikeys are not set	Когда API-ключ не настроен должным образом.

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

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

Что дальше

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

Эндпоинт​

Запрос​

Пример​

Ответы​

Коды ошибок​

Что дальше​