Получение существующего процесса по его идентификатору. Согласно контракту API, результат уже возвращается синхронно при создании процесса — используйте этот эндпоинт для повторных запросов, аудита и поддержки.
Перед получением процесса ознакомьтесь с настройкой вебхуков и стратегиями резервного варианта — нажмите здесь.
Эндпоинт
| Среда | URL |
|---|---|
| Production | GET https://api.idcloud.unico.app/client/v1/process/{processId} |
| Sandbox | GET https://api.idcloud.uat.unico.app/client/v1/process/{processId} |
Запрос
| Заголовок | Значение |
|---|---|
Authorization | Bearer <access_token> |
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
processId | string (UUID) | да | Идентификатор процесса, возвращённый Создать процесс. |
Пример
- cURL
- Node.js
curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"
import fetch from 'node-fetch';
const res = await fetch(
`https://api.idcloud.unico.app/client/v1/process/${processId}`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();
Ответы
{
"process": {
"id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
"flow": "id_r2",
"callbackUri": "/",
"userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"createdAt": "2026-08-06T01:42:21.693615Z",
"finishedAt": "2026-08-06T01:43:03.080508Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "40*******50",
"friendlyName": "teste",
"email": "",
"phone": "5511999999999",
"notifications": [
{ "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
],
"phoneCountryCodeAlpha3": ""
},
"purpose": "personAuthentication",
"services": [],
"authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
"capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
"expiresAt": "2026-08-13T01:42:21.536500Z",
"token": "",
"companyData": { "branchId": "", "countryCode": "BRA" },
"simulated": false
}
}
| Поле | Значение |
|---|---|
id | UUID процесса; ключ, используемый для запроса и отслеживания потока. |
flow | Тип выполненного сценария (например, id_r2, idlivetrust_r2, idtrust_r2 и т. д.). |
callbackUri | Callback URI, на который перенаправляется клиентское приложение в конце потока. |
userRedirectUrl | Полный URL страницы CbU, которую пользователь открывает для выполнения сценария (содержит id и флаги поведения). |
state | Состояние жизненного цикла процесса (например, PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED). |
result | Итоговый вердикт оценки. Значения PROCESS_RESULT_* (например, APPROVED, AUTHENTICATED, NOT_APPROVED и т. д.). Является окончательным только когда state = PROCESS_STATE_FINISHED. |
createdAt | Метка времени создания процесса (UTC). |
finishedAt | Метка времени завершения процесса (UTC). |
person | Подобъект с данными проверяемого лица. |
purpose | Цель процесса (например, personAuthentication, регистрация лица). |
services | Список дополнительных сервисов, прикреплённых к процессу; пуст, если их нет. |
authenticationInfo.authenticationId | ID события аутентификации личности, сгенерированного потоком. |
capacities | Использованные возможности/продукты. Значения PROCESS_CAPACITY_* (например, IDCLOUDONE). |
expiresAt | Метка времени истечения процесса/ссылки (UTC). |
token | Токен сессии/доступа, связанный с процессом (может быть пустым). |
companyData | Подобъект с данными компании/тенанта, владеющего процессом. |
simulated | Логическое значение; является ли этот процесс симуляцией/песочницей (true) или настоящим (false). |
| Поле | Значение |
|---|---|
duiType | Тип уникального документа, удостоверяющего личность. Значения DUI_TYPE_* (например, BR_CPF). |
duiValue | Значение документа (например, номер CPF). |
friendlyName | Отображаемое имя/псевдоним человека (произвольный текст, не проверяется). |
email | Email человека; может быть пустым. |
phone | Номер телефона в формате E.164 (код страны + код региона + номер). |
notifications | Список каналов уведомлений. Каждый элемент содержит notificationChannel со значениями NOTIFICATION_CHANNEL_* (например, WHATSAPP, SMS, EMAIL). |
phoneCountryCodeAlpha3 | Код страны ISO alpha-3 для номера телефона (например, BRA); может быть пустым. |
| Поле | Значение |
|---|---|
branchId | Идентификатор филиала тенанта; пуст, если сегментация по филиалам не используется. |
countryCode | Страна компании в формате ISO alpha-3 (например, BRA). |
process.services[].documents[].doc.code сообщает тип документа в одной из двух форм. Документы, обработанные модулем документов Unico, включая повторно использованные документы, содержат короткий код в верхнем регистре (CNH). Процессы, созданные только через API, обычно содержат полный тип словаря (unico.moja.dictionary.br.cnh.v2.Cnh), но могут содержать и короткий код. Обрабатывайте обе формы при любом способе интеграции.
Короткий код не содержит ни страну, ни версию схемы; версия возвращается отдельно в doc.version.
В короткой форме типы документов, использующие унифицированную схему — unified_schema в справочнике полей — сообщаются как тип, определённый во время захвата, в верхнем регистре. Наиболее распространённые значения — IDCARD, DRIVERLICENSE, PASSPORT и VOTERID, но список открыт: другие типы, определённые во время захвата, возвращаются как есть, в верхнем регистре. Обрабатывайте значения за пределами этого списка.
Паспорта США сохраняют свой вариант вместо объединения в PASSPORT: также возвращаются POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT и REFUGEEPASSPORT.
Например, unico.moja.dictionary.ar.generic.v1.IdCard и unico.moja.dictionary.us.generic.v1.PolycarbonatePassport сообщаются как IDCARD и POLYCARBONATEPASSPORT.
Типы документов, использующие собственную схему полей — перечисленные в specific_document_schemas в справочнике полей — показаны в таблице ниже. Используйте dictionary type, чтобы найти каждую схему в этом файле.
| Страна | doc.code | Dictionary type | Документ |
|---|---|---|---|
| BR | RG | unico.moja.dictionary.br.rg.v2.Rg | RG |
| BR | CNH | unico.moja.dictionary.br.cnh.v2.Cnh | CNH (водительское удостоверение) |
| BR | CIN | unico.moja.dictionary.br.cin.v1.Cin | CIN |
| BR | PASSAPORTE | unico.moja.dictionary.br.passaporte.v1.Passaporte | Паспорт |
| MX | INE | unico.moja.dictionary.mx.ine.v1.Ine | Избирательное удостоверение INE |
| MX | LPC | unico.moja.dictionary.mx.lpc.v1.Lpc | Licencia para conducir (водительское удостоверение) |
| MX | PASAPORTE | unico.moja.dictionary.mx.pasaporte.v1.Pasaporte | Паспорт |
| — | UNKNOWN | unico.moja.dictionary.other.unknown.v1.Unknown | Тип не удалось определить, или это бразильский либо мексиканский тип без собственной схемы — doc.data пуст |
Бразильские и мексиканские документы используют только специфичные схемы, приведённые выше. Бразильский или мексиканский документ любого другого типа — например, мексиканская карта резид ента — сообщается как UNKNOWN, а не с унифицированной схемой.
PASSAPORTE и PASAPORTE — разные документыБразильский паспорт — это PASSAPORTE (двойная S), а мексиканский — PASAPORTE (одна S), каждый отражает написание в своём словаре. Это не опечатка — не считайте эти два значения эквивалентными.
Когда doc.code равен UNKNOWN, извлечение OCR не выполняется, и в doc.data не сообщается ни одно поле.
Клиенты в Бразилии могут получать полную полезную нагрузку процессаОбщая структура ответа остаётся такой же — единый результат используется по умолчанию.

Общая структура ответа остаётся такой же — единый результат используется по умолчанию.
Интеграции в Бразилии могут получать полный объект процесса, показанный ниже, с результатами по каждой возможности в authenticationInfo.
{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"callbackUri": "https://example.com/callback",
"userRedirectUrl": "https://example.com/redirect",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_OK",
"createdAt": "2024-01-01T10:00:00Z",
"finishedAt": "2024-01-01T10:15:00Z",
"expiresAt": "2024-01-08T10:00:00Z",
"purpose": "VERIFICATION",
"clientReference": "client-ref-abc",
"useCase": "USE_CASE_LOGIN",
"capacities": ["liveness", "face_match"],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909",
"friendlyName": "Luke Skywalker",
"notifications": [
{
"notificationChannel": "email"
}
]
},
"authenticationInfo": {
"authenticationId": "auth-123",
"livenessResult": "LIVENESS_RESULT_LIVE",
"authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
"identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
"bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
"smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
"idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
"scoreEngineResult": {
"scoreEnabled": "SCORE_ENABLED_TRUE",
"score": 85.5
}
},
"companyData": {
"branchId": "branch-123",
"countryCode": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
| Поле | Тип | Описание |
|---|---|---|
process.id | string (UUID) | Идентификатор процесса. |
process.flow | string | Идентификатор потока, отправленный при создании. |
process.callbackUri | string | Callback URL, настроенный для событий процесса. |
process.userRedirectUrl | string | URL для перенаправления пользователя после завершения сценария. |
process.state | enum | Текущее состояние процесса. См. значения ниже. |
process.result | enum | Результат верификации. Присутствует только когда state = PROCESS_STATE_FINISHED. |
process.createdAt | string (datetime) | Метка времени ISO 8601, когда процесс был создан. |
process.finishedAt | string (datetime) | Метка времени ISO 8601, когда процесс завершился. Присутствует только когда state = PROCESS_STATE_FINISHED. |
process.expiresAt | string (datetime) | Метка времени ISO 8601, когда процесс истекает. |
process.purpose | string | Цель процесса, настроенная в потоке. |
process.clientReference | string | Опциональная ссылка на стороне клиента для индексации в портале. |
process.useCase | string | Идентификатор сценария, связанного с потоком. |
process.capacities | array of strings | Список возможностей, активированных в этом процессе. |
process.token | string | Подписанный JWT для интеграции SDK. |
process.person | object | Идентификационные данные, предоставленные при создании. |
process.person.notifications | array | Каналы уведомлений, настроенные для сценария (например, email). |
process.authenticationInfo | object | Результаты по каждой возможности. См. ниже. |
process.companyData | object | Контекст компании и филиала. |
process.companyData.branchId | string | Идентификатор филиала. |
process.companyData.countryCode | string | Код страны ISO 3166-1 alpha-3 (например, BRA). |
process.bioTokenData | object | Информация о референсном процессе — присутствует только в потоках валидации 1:1 и умной ревалидации. |
process.services | array | Подписанные конверты, захваченные документы и другие результаты сервисов. См. ниже. |
| Значение | Описание |
|---|---|
PROCESS_STATE_CREATED | Процесс создан; пользователь ещё не завершил сценарий. |
PROCESS_STATE_AWAITING_FOR_DOCUMENT | Процесс создан без документа, удостоверяющ его личность. Присутствует только когда пользовательский поток (Custom Flow) допускает опциональный документ. Отправьте документ через Передача документа процесса. |
PROCESS_STATE_FINISHED | Сценарий завершён. Проверьте result и authenticationInfo. |
PROCESS_STATE_FAILED | Ошибка обработки. |
| Значение | Описание |
|---|---|
PROCESS_RESULT_OK | Все возможности вернули положительный результат. |
PROCESS_RESULT_INVALID_IDENTITY | Как минимум одна возможность вернула однозначно отрицательный результат (например, проверка живости не пройдена, личность не подтверждена). |
PROCESS_RESULT_ERROR | Ошибка при обработке результата. |
PROCESS_RESULT_EXPIRED | Процесс истёк до завершения сценария. |
PROCESS_RESULT_UNSPECIFIED | Процесс ещё не завершён. |
Все поля всегда возвращаются независимо от потока. Поля для во зможностей, не используемых в потоке, возвращают *_UNSPECIFIED.
Сокращённые значения (например, livenessResult = LIVE, authenticationResult = INCONCLUSIVE) напрямую соответствуют полным значениям перечислений, документированным здесь (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE и т. д.) — префикс опущен для краткости.
| Поле | Возможность | Возможные значения |
|---|---|---|
authenticationId | — | Уникальный идентификатор этой попытки аутентификации. |
livenessResult | Проверка живости | LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED |
authenticationResult | Проверка личности | AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED |
identityFraudstersResult | Классификация рисков мошенничества | TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED |
bioTokenEngineResult | Валидация 1:1 | BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED |
smartRevalidationResult | Умная ревалидация | SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED |
idAgeResult | Проверка возраста | ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED |
scoreEngineResult.scoreEnabled | Риск-скор | SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED |
scoreEngineResult.score | Риск-скор | Число от -100 до +100. Присутствует, когда authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE и включён «Риск-скор». |
serproResult.score | Сходство Serpro | 0–100 (сходство); -1 (нет фото лица в базе для этого CPF); -2 (ошибка интеграции). |
deviceMetadata | Метаданные устройства | Объект со status (found, not_found, unavailable) и данными устройства. Отсутствует, если возможность не включена в потоке. |
services содержит по одному элементу на каждый модуль, завершённый в процессе: последнее завершённое выполнение каждого модуля, и только пока процесс находится в состоянии PROCESS_STATE_FINISHED или PROCESS_STATE_AWAITING_FOR_DOCUMENT. Процессы, созданные только через API, содержат свой элемент документа в любом состоянии. Элемент захвата документов содержит documents и consent_granted. Элемент электронной подписи содержит envelope_id и document_ids. У элементов нет поля типа, и их порядок не постоянен: определяйте каждый элемент по его ключам, а не по позиции, и игнорируйте элементы, которые вы не распознаёте. Ключи записываются в snake_case, кроме ключей внутри doc.data, котор ые следуют схеме документа (например, nomeCivil).
| Поле | Тип | Описание |
|---|---|---|
consent_granted | boolean | Элемент захвата документов. Дал ли пользователь согласие на передачу документов вашей компании. |
documents | array | Элемент захвата документов. Захваченные документы с данными OCR и результатами валидации. |
documents[].doc_id | string | Идентификатор документа. |
documents[].share_id | string | Идентификатор доступа, который пользователь предоставил вашей компании для этого процесса. |
documents[].typified | boolean | Был ли определён тип документа. |
documents[].cpf_match | boolean | Только Бразилия. Совпадает ли CPF в документе с CPF, отправленным при создании. Всегда присутствует для компаний, у которых в качестве страны указана Бразилия; для других стран и для компаний без указанной страны не передаётся. |
documents[].validate_doc | boolean | Только Бразилия. Прошёл ли документ валидацию документов Unico. Всегда присутствует для компаний, у которых в качестве страны указана Бразилия (false, если валидация не выполнялась); для других стран и для компаний без указанной страны не передаётся. |
documents[].face_match | boolean or null | Совпадает ли селфи с фотографией в документе. null означает, что проверка не выполнялась, — это не отрицательный результат. |
documents[].verified | boolean or null | true, только если тип документа известен, документ не был удалён, face_match равен true и документ прошёл проверки качества. false в остальных случаях, в том числе когда face_match не выполнялся. null, если процесс не проходил через модуль документов. |
documents[].reused_doc | boolean | Был ли этот документ повторно использован из предыдущего процесса. |
documents[].signed_url | string | Краткосрочный подписанный URL для скачивания изображения документа. Срок его действия истекает: не сохраняйте его и не рассчитывайте на фиксированный срок действия — чтобы получить новый, снова вызовите этот эндпоинт. |
documents[].doc.version | integer | Версия словаря типа документа (например, 2 для unico.moja.dictionary.br.cnh.v2.Cnh). |
documents[].doc.code | string | Тип документа — в виде короткого кода (например, CNH) или полного типа словаря (например, unico.moja.dictionary.br.cnh.v2.Cnh). Документы, обработанные модулем документов, содержат короткий код. Обрабатывайте оба варианта. Все значения и способ формирования кода см. в разделе Типы документов и поля OCR. |
documents[].doc.data | object | Извлечённые поля OCR. Содержимое зависит от типа документа — полный каталог см. в полном справочнике полей. Названия полей соответствуют схеме документа: португальские для бразильских документов (например, nomeCivil, dataNascimento), испанские для мексиканских документов и английские для унифицированной схемы. |
envelope_id | string (UUID) | Элемент электронной подписи. Идентификатор подписанного конверта. |
document_ids | array of strings | Элемент электронной подписи. ID документов в конверте. |
В процессе, созданном только через API, элемент документа поступает из вызова API, а не из модуля документов Unico, и некоторые значения отличаются от приведённых в таблице выше:
consent_grantedвсегда равенfalse: согласие собирает ваша компания, и Unico его не отслеживает.share_idиsigned_urlпусты.face_matchвсегда равенtrueилиfalse, но никогда неnull.verifiedвсегда равенnull.doc.versionравен0.doc.codeобычно содержит полный тип словаря (например,unico.moja.dictionary.br.cnh.v2.Cnh), но может содержать короткий код.doc.dataравенnull, если данные OCR не удалось прочитать.
Коды ошибок
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
| Код | Сообщение | Описание |
|---|---|---|
3 | process id is invalid | Когда ID процесса недействителен. |
| Код | Сообщение | Описание |
|---|---|---|
| — | Jwt header is an invalid JSON | Когда использованный токен доступа содержит некорректные символы. |
| — | Jwt is expired | Когда использованный токен доступа истёк. |
| Код | Сообщение | Описание |
|---|---|---|
5 | error getting process: rpc error: code = NotFound desc = process not found | Когда ID процесса не был найден. |
Достигнут лимит запросов. Когда ваша система получает ошибку HTTP 429, необходимо реализовать механизмы для предотвращения каскадных сбоев и избежания усугубления ограничения.
Лучшие практики:
- Период ожидания (backoff): Немедленно остановите или снизьте частоту последующих запросов из вашей системы. Не повторяйте неудачные запросы непрерывно в тесном цикле.
- Очередь и ограничение (Queueing & throttling): Буферизируйте или ставьте в очередь исходящие запросы на вашей стороне для контроля потока трафика перед их повторной отправкой.
- Экспоненциальный backoff с джиттером: При повторных попытках увеличивайте время ожидания экспоненциально между попытками (например, 1 с, 2 с, 4 с, 8 с) и добавляйте небольшую случайную задержку ("джиттер"), чтобы предотвратить эффект стада, когда все запросы из очереди повторяются в одну и ту же миллисекунду.
Непрерывная отправка запросов к эндпоинту с ограничением частоты без применения backoff может продлить период ограничения и серьезно снизить операционную пропускную способность вашей системы. Правильное ограничение запросов на вашей стороне обеспечивает более плавную и устойчивую интеграцию.
Информацию о лимитах по умолчанию, увеличении запросов и дополнительные сведения см. в разделе Лимиты запросов.
| Код | Сообщение | Описание |
|---|---|---|
99999 | Internal failure! Try again later | Когда произошла внутренняя ошибка. |
Опрос или вебхук
Вы можете опрашивать этот эндпоинт для проверки прогресса, но рекомендуемый паттерн — подписаться на вебхук и вызывать этот эндпоинт только как резервный вариант. См. Вебхуки и события.
Что дальше
- Для захваченного селфи см. Получение селфи.
- Для набора доказательств для аудита см. Получение набора доказательств.