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

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

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

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

Эндпоинт​

Окружение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
  }
}
Поля process
ПолеОписание
idUUID процесса; ключ для запроса и отслеживания потока.
flowТип выполняемого прохождения (например, id_r2, idlivetrust_r2, idtrust_r2 и т. д.).
callbackUriURI обратного вызова, на который перенаправляется клиентское приложение в конце потока.
userRedirectUrlПолный URL страницы CbU, которую открывает пользователь для прохождения (содержит id и флаги поведения).
stateСостояние жизненного цикла процесса. Значения PROCESS_STATE_* (например, CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, 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Логическое значение; является ли процесс симуляцией/sandbox (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); может быть пустым.
Поля companyData
ПолеОписание
branchIdИдентификатор филиала тенанта; пусто, если сегментация по филиалам не используется.
countryCodeСтрана компании в формате ISO alpha-3 (например, BRA).
Типы документов и поля OCR

process.services[].documents[].doc.code возвращает тип документа в виде короткого кода в верхнем регистре. unico.moja.dictionary.br.cnh.v2.Cnh превращается в CNH. Код не содержит ни страны, ни версии схемы; версия возвращается отдельно в doc.version.

Типы документов, использующие единую схему — unified_schema в справочнике полей, — возвращаются как определённый при захвате тип в верхнем регистре: IDCARD, DRIVERLICENSE, PASSPORT или VOTERID. Паспорта США сохраняют свой вариант вместо объединения в PASSPORT, поэтому также возвращаются значения POLYCARBONATEPASSPORT, PASSPORTCARD и PAPERPASSPORT. Например, unico.moja.dictionary.ar.generic.v1.IdCard и unico.moja.dictionary.us.generic.v1.PolycarbonatePassport возвращаются как IDCARD и POLYCARBONATEPASSPORT.

Отдельные схемы

Типы документов, использующие собственную схему полей — перечисленные в разделе specific_document_schemas в справочнике полей, — приведены в таблице ниже. Используйте тип словаря, чтобы найти каждую схему в этом файле.

Странаdoc.codeТип словаряДокумент
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 пусто
PASSAPORTE и PASAPORTE — разные документы

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

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

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

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

Интеграции в Бразилии могут получать приведённый ниже полный объект процесса с результатами по каждой возможности в authenticationInfo.

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "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": "smart_revalidation",
    "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_INCONCLUSIVE",
      "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": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "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.callbackUristringURL обратного вызова, настроенный для событий процесса.
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-2.
process.bioTokenDataobjectИнформация о референсном процессе — присутствует только в потоках Валидации 1:1 и Умной ревалидации.
process.servicesarrayПодписанные конверты, захваченные документы и другие результаты сервисов. См. ниже.
Значения process.state
ЗначениеОписание
PROCESS_STATE_CREATEDПроцесс создан; пользователь ещё не завершил прохождение.
AWAITING_FOR_DOCUMENTПроцесс создан без документа, удостоверяющего личность; ожидание его установки через установку документа процесса. Присутствует только когда Custom Flow допускает опциональный документ.
PROCESS_STATE_FINISHEDПрохождение завершено. Проверьте result и authenticationInfo.
PROCESS_STATE_FAILEDОшибка обработки.
Несоответствие в именовании состояний

AWAITING_FOR_DOCUMENT не соответствует соглашению о префиксе PROCESS_STATE_*, используемому для остальных состояний. Это известное несоответствие в именовании в текущей версии API.

Значения 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 (ошибка интеграции).
Поля process.services
Смешанные соглашения об именовании в services

Массив services использует camelCase для полей уровня конверта (envelopeId, documentIds) и snake_case для полей уровня документа (doc_id, consent_granted, face_match и т. д.). Это отражает реальный ответ API — обе конвенции намеренны и не являются ошибкой документации.

ПолеТипОписание
envelopeIdstring (UUID)Идентификатор подписанного конверта.
documentIdsarray of stringsID захваченных документов в данном сервисе.
consent_grantedbooleanДал ли пользователь согласие на обмен данными.
documentsarrayЗахваченные документы с данными OCR и результатами валидации.
documents[].doc_idstringИдентификатор документа.
documents[].typifiedbooleanБыл ли тип документа успешно определён.
documents[].cpf_matchbooleanСовпадает ли CPF на документе с предоставленным CPF (только Бразилия).
documents[].face_matchbooleanСовпадает ли селфи с фотографией на документе.
documents[].validate_docbooleanПрошёл ли документ проверку подлинности.
documents[].reused_docbooleanБыл ли этот документ повторно использован из предыдущего процесса.
documents[].signed_urlstringЗаранее подписанный URL для скачивания PDF документа (действителен 5 минут — запросите заново для обновления).
documents[].doc.versionintegerВерсия схемы OCR.
documents[].doc.codestringКраткий код типа документа (например, CNH). Все значения и способ формирования кода см. в разделе Типы документов и поля OCR.
documents[].doc.dataobjectИзвлечённые поля OCR. Содержимое зависит от типа документа — полный каталог см. в полном справочнике полей. Названия полей внутри doc.data (например, nomeCivil, dataNascimento) возвращаются на португальском языке — это фактические значения, генерируемые движком OCR.

Коды ошибок​

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

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

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

Что дальше​

Последнее обновление