Перейти к основному содержимому
Получение процессаGET

Получение существующего процесса по его идентификатору. Согласно контракту API, результат уже возвращается синхронно при создании процесса — используйте этот эндпоинт для повторных запросов, аудита и поддержки.

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

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

Эндпоинт​

СредаURL
ProductionGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Запрос​

Заголовки
ЗаголовокЗначение
AuthorizationBearer <access_token>
Параметры пути
ПараметрТипОбязателенОписание
processIdstring (UUID)даИдентификатор процесса, возвращённый Создать процесс.

Пример​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

Ответы​

200 OK
{
"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
}
}
Поля процесса
ПолеЗначение
idUUID процесса; ключ, используемый для запроса и отслеживания потока.
flowТип выполненного сценария (например, id_r2, idlivetrust_r2, idtrust_r2 и т. д.).
callbackUriCallback 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.​authenticationIdID события аутентификации личности, сгенерированного потоком.
capacitiesИспользованные возможности/продукты. Значения PROCESS_CAPACITY_* (например, IDCLOUDONE).
expiresAtМетка времени истечения процесса/ссылки (UTC).
tokenТокен сессии/доступа, связанный с процессом (может быть пустым).
companyDataПодобъект с данными компании/тенанта, владеющего процессом.
simulatedЛогическое значение; является ли этот процесс симуляцией/песочницей (true) или настоящим (false).
Поля person
ПолеЗначение
duiTypeТип уникального документа, удостоверяющего личность. Значения DUI_TYPE_* (например, BR_CPF).
duiValueЗначение документа (например, номер CPF).
friendlyNameОтображаемое имя/псевдоним человека (произвольный текст, не проверяется).
emailEmail человека; может быть пустым.
phoneНомер телефона в формате E.164 (код страны + код региона + номер).
notificationsСписок каналов уведомлений. Каждый элемент содержит notificationChannel со значениями NOTIFICATION_CHANNEL_* (например, WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3Код страны ISO alpha-3 для номера телефона (например, BRA); может быть пустым.
Поля данных компании
ПолеЗначение
branchIdИдентификатор филиала тенанта; пуст, если сегментация по филиалам не используется.
countryCodeСтрана компании в формате ISO alpha-3 (например, BRA).
Типы документов и поля OCR

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.codeDictionary typeДокумент
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH (водительское удостоверение)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​PassaporteПаспорт
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​IneИзбирательное удостоверение INE
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir (водительское удостоверение)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​PasaporteПаспорт
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​UnknownТип не удалось определить, или это бразильский либо мексиканский тип без собственной схемы — doc.data пуст

Бразильские и мексиканские документы используют только специфичные схемы, приведённые выше. Бразильский или мексиканский документ любого другого типа — например, мексиканская карта резидента — сообщается как UNKNOWN, а не с унифицированной схемой.

PASSAPORTE и PASAPORTE — разные документы

Бразильский паспорт — это PASSAPORTE (двойная S), а мексиканский — PASAPORTE (одна S), каждый отражает написание в своём словаре. Это не опечатка — не считайте эти два значения эквивалентными.

Когда doc.code равен UNKNOWN, извлечение OCR не выполняется, и в doc.data не сообщается ни одно поле.

BrazilКлиенты в Бразилии могут получать полную полезную нагрузку процесса

Общая структура ответа остаётся такой же — единый результат используется по умолчанию.

Интеграции в Бразилии могут получать полный объект процесса, показанный ниже, с результатами по каждой возможности в 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.idstring (UUID)Идентификатор процесса.
process.flowstringИдентификатор потока, отправленный при создании.
process.callbackUristringCallback URL, настроенный для событий процесса.
process.​userRedirectUrlstringURL для перенаправления пользователя после завершения сценария.
process.stateenumТекущее состояние процесса. См. значения ниже.
process.resultenumРезультат верификации. Присутствует только когда state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)Метка времени ISO 8601, когда процесс был создан.
process.finishedAtstring (datetime)Метка времени ISO 8601, когда процесс завершился. Присутствует только когда state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)Метка времени ISO 8601, когда процесс истекает.
process.purposestringЦель процесса, настроенная в потоке.
process.​clientReferencestringОпциональная ссылка на стороне клиента для индексации в портале.
process.useCasestringИдентификатор сценария, связанного с потоком.
process.capacitiesarray of stringsСписок возможностей, активированных в этом процессе.
process.tokenstringПодписанный JWT для интеграции SDK.
process.personobjectИдентификационные данные, предоставленные при создании.
process.​person.​notificationsarrayКаналы уведомлений, настроенные для сценария (например, email).
process.​authenticationInfoobjectРезультаты по каждой возможности. См. ниже.
process.companyDataobjectКонтекст компании и филиала.
process.​companyData.​branchIdstringИдентификатор филиала.
process.​companyData.​countryCodestringКод страны ISO 3166-1 alpha-3 (например, BRA).
process.​bioTokenDataobjectИнформация о референсном процессе — присутствует только в потоках валидации 1:1 и умной ревалидации.
process.servicesarrayПодписанные конверты, захваченные документы и другие результаты сервисов. См. ниже.
Значения `process.state`
ЗначениеОписание
PROCESS_STATE_CREATEDПроцесс создан; пользователь ещё не завершил сценарий.
PROCESS_STATE_AWAITING_FOR_DOCUMENTПроцесс создан без документа, удостоверяющего личность. Присутствует только когда пользовательский поток (Custom Flow) допускает опциональный документ. Отправьте документ через Передача документа процесса.
PROCESS_STATE_FINISHEDСценарий завершён. Проверьте result и authenticationInfo.
PROCESS_STATE_FAILEDОшибка обработки.
Значения `process.result`
ЗначениеОписание
PROCESS_RESULT_OKВсе возможности вернули положительный результат.
PROCESS_RESULT_INVALID_IDENTITYКак минимум одна возможность вернула однозначно отрицательный результат (например, проверка живости не пройдена, личность не подтверждена).
PROCESS_RESULT_ERRORОшибка при обработке результата.
PROCESS_RESULT_EXPIREDПроцесс истёк до завершения сценария.
PROCESS_RESULT_UNSPECIFIEDПроцесс ещё не завершён.
Результаты возможностей в authenticationInfo

Все поля всегда возвращаются независимо от потока. Поля для возможностей, не используемых в потоке, возвращают *_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:1BIO_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Сходство Serpro0–100 (сходство); -1 (нет фото лица в базе для этого CPF); -2 (ошибка интеграции).
deviceMetadataМетаданные устройстваОбъект со status (found, not_found, unavailable) и данными устройства. Отсутствует, если возможность не включена в потоке.
Поля `process.services`
Один элемент на модуль

services содержит по одному элементу на каждый модуль, завершённый в процессе: последнее завершённое выполнение каждого модуля, и только пока процесс находится в состоянии PROCESS_STATE_FINISHED или PROCESS_STATE_AWAITING_FOR_DOCUMENT. Процессы, созданные только через API, содержат свой элемент документа в любом состоянии. Элемент захвата документов содержит documents и consent_granted. Элемент электронной подписи содержит envelope_id и document_ids. У элементов нет поля типа, и их порядок не постоянен: определяйте каждый элемент по его ключам, а не по позиции, и игнорируйте элементы, которые вы не распознаёте. Ключи записываются в snake_case, кроме ключей внутри doc.data, которые следуют схеме документа (например, nomeCivil).

ПолеТипОписание
consent_grantedbooleanЭлемент захвата документов. Дал ли пользователь согласие на передачу документов вашей компании.
documentsarrayЭлемент захвата документов. Захваченные документы с данными OCR и результатами валидации.
documents[].doc_idstringИдентификатор документа.
documents[].​share_idstringИдентификатор доступа, который пользователь предоставил вашей компании для этого процесса.
documents[].​typifiedbooleanБыл ли определён тип документа.
documents[].​cpf_matchbooleanТолько Бразилия. Совпадает ли CPF в документе с CPF, отправленным при создании. Всегда присутствует для компаний, у которых в качестве страны указана Бразилия; для других стран и для компаний без указанной страны не передаётся.
documents[].​validate_docbooleanТолько Бразилия. Прошёл ли документ валидацию документов Unico. Всегда присутствует для компаний, у которых в качестве страны указана Бразилия (false, если валидация не выполнялась); для других стран и для компаний без указанной страны не передаётся.
documents[].​face_matchboolean or nullСовпадает ли селфи с фотографией в документе. null означает, что проверка не выполнялась, — это не отрицательный результат.
documents[].​verifiedboolean or nulltrue, только если тип документа известен, документ не был удалён, face_match равен true и документ прошёл проверки качества. false в остальных случаях, в том числе когда face_match не выполнялся. null, если процесс не проходил через модуль документов.
documents[].​reused_docbooleanБыл ли этот документ повторно использован из предыдущего процесса.
documents[].​signed_urlstringКраткосрочный подписанный URL для скачивания изображения документа. Срок его действия истекает: не сохраняйте его и не рассчитывайте на фиксированный срок действия — чтобы получить новый, снова вызовите этот эндпоинт.
documents[].​doc.​versionintegerВерсия словаря типа документа (например, 2 для unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringТип документа — в виде короткого кода (например, CNH) или полного типа словаря (например, unico.moja.dictionary.br.cnh.v2.Cnh). Документы, обработанные модулем документов, содержат короткий код. Обрабатывайте оба варианта. Все значения и способ формирования кода см. в разделе Типы документов и поля OCR.
documents[].​doc.​dataobjectИзвлечённые поля OCR. Содержимое зависит от типа документа — полный каталог см. в полном справочнике полей. Названия полей соответствуют схеме документа: португальские для бразильских документов (например, nomeCivil, dataNascimento), испанские для мексиканских документов и английские для унифицированной схемы.
envelope_idstring (UUID)Элемент электронной подписи. Идентификатор подписанного конверта.
document_idsarray of stringsЭлемент электронной подписи. ID документов в конверте.
Процессы, созданные только через API

В процессе, созданном только через 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 не удалось прочитать.

Коды ошибок​

КодСообщениеОписание
3process id is invalidКогда ID процесса недействителен.

Опрос или вебхук​

Вы можете опрашивать этот эндпоинт для проверки прогресса, но рекомендуемый паттерн — подписаться на вебхук и вызывать этот эндпоинт только как резервный вариант. См. Вебхуки и события.

Что дальше​