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

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

Подробнее о полном потоке интеграции см. в разделе Web & SDK Overview.

Endpoint

Окружение	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> (см. Authentication)
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.
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. Идентификатор ссылочного биометрического процесса. Обязателен для потоков валидации 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)	нет	Идентификатор филиала. Обязателен только в случае, если с сервисным аккаунтом связан более чем один филиал.
expiresIn	string	нет	Срок действия процесса с момента создания. Формат: "3600s". По умолчанию — 7 дней, если не указано.
flow_config	object	нет	Переопределение конфигурации для конкретного потока.
flow_config.biometry_capture.enabled_back_camera	boolean	нет	Использовать заднюю камеру устройства. Несовместимо с потоками захвата документов или электронной подписи.
contextualization	object	нет	Контекст транзакции, отображаемый пользователю во время сессии для объяснения процесса захвата.
contextualization.currency	string	нет	Код валюты, отображаемый пользователю. Допустимые значения: BRL, MXN, USD.
contextualization.price	number	нет	Сумма транзакции, отображаемая пользователю.
contextualization.locale	object	нет	Локализованный текст причины. Ключи: ptBr, enUs, esMx — каждый со строкой reason, отображаемой во время сессии.

Пример

cURL

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

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({
    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)	Идентификатор процесса. Используйте его для получения результата через Get Process.
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)	Идентификатор филиала. Присутствует только если был указан в запросе.
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)	Идентификатор филиала, связанного с процессом.
process.companyData.countryCode	string	Код страны, связанный с филиалом (например, BR, MX).

400 Bad Request

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

401 Unauthorized

Bearer-токен отсутствует, истёк или недействителен. См. Authentication.

429 Too Many Requests

Достигнут лимит запросов. Повторите попытку через интервал, указанный в заголовках ответа.

Коды ошибок

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	Когда указанный адрес электронной почты недействителен и настроено уведомление по электронной почте.
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 недействительно.
9	XX ID Apikeys are not set	Когда API Key настроен неправильно.

401 Unauthorized

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

429 Too Many Requests

Для этого статуса подробный код ошибки не предусмотрен — только HTTP-статус.

500 Internal Server Error

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

Что дальше

• После того как пользователь завершит сессию, вызовите Get Process для получения результата или дождитесь webhook.