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

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

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

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

Эндпоинт​

Среда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, 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Логическое значение; является ли этот процесс симуляцией/песочницей (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

Типы документов, использующие унифицированную схему — 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.

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

Специфичные схемы

Типы документов, использующие собственную схему полей — перечисленные в 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 пуст
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": "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.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-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 процесса недействителен.

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

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

Что дальше​

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