Получение процесса

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

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

Endpoint

Эндпоинт

Окружение	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();

Ответы

200 OK

{
  "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.id`	string (UUID)	Идентификатор процесса.
`process.flow`	string	Идентификатор потока, отправленный при создании.
`process.callbackUri`	string	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-2.
`process.bioTokenData`	object	Информация о ссылочном процессе -- присутствует только в потоках Валидации 1:1 и Умной ревалидации.
`process.services`	array	Подписанные конверты, захваченные документы и другие результаты сервисов. См. ниже.

Значения 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: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` (ошибка интеграции).

Поля process.services

Смешанные соглашения об именовании в services

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

Поле	Тип	Описание
`envelopeId`	string (UUID)	Идентификатор подписанного конверта.
`documentIds`	array of strings	ID захваченных документов в данном сервисе.
`consent_granted`	boolean	Дал ли пользователь согласие на обмен данными.
`documents`	array	Захваченные документы с данными OCR и результатами валидации.
`documents[].doc_id`	string	Идентификатор документа.
`documents[].typified`	boolean	Был ли тип документа успешно определён.
`documents[].cpf_match`	boolean	Совпадает ли CPF на документе с предоставленным CPF.
`documents[].face_match`	boolean	Совпадает ли селфи с фотографией на документе.
`documents[].validate_doc`	boolean	Прошёл ли документ проверку подлинности.
`documents[].reused_doc`	boolean	Был ли этот документ повторно использован из предыдущего процесса.
`documents[].signed_url`	string	Предподписанный URL для скачивания PDF документа (действителен 5 минут -- повторно запросите для обновления).
`documents[].doc.version`	integer	Версия схемы OCR.
`documents[].doc.code`	string	Код типа документа (например, `CNH`, `RG`).
`documents[].doc.data`	object	Извлечённые поля OCR. Содержимое зависит от типа документа и доступных данных. Названия полей внутри `doc.data` (например, `nomeCivil`, `dataNascimento`) возвращаются на португальском языке — это фактические значения, генерируемые движком OCR.

400 Bad Request

Параметр пути processId отсутствует или имеет неверный формат.

401 Unauthorized

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

404 Not Found

processId не существует или не принадлежит аутентифицированному тенанту.

429 Too Many Requests

Достигнут лимит запросов. Когда ваша система получает ошибку HTTP 429, необходимо реализовать механизмы для предотвращения каскадных сбоев и ухудшения ограничения.

Лучшие практики:

Период ожидания (backoff): Немедленно остановите или ограничьте последующие запросы из вашей системы. Не повторяйте неудачные запросы непрерывно в плотном цикле.
Очередь и ограничение: Буферизуйте или ставьте в очередь исходящие запросы на вашей стороне для управления потоком трафика перед повторной отправкой.
Экспоненциальный backoff с jitter: При повторных попытках увеличивайте время ожидания экспоненциально между попытками (например, 1 с, 2 с, 4 с, 8 с) и добавляйте небольшую случайную задержку ("jitter"), чтобы предотвратить эффект стада, когда все поставленные в очередь запросы повторяются в один и тот же момент.

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

Непрерывные запросы к эндпоинту с ограничением без отступления могут продлить период ограничения и серьёзно повлиять на операционную пропускную способность вашей системы. Правильное ограничение запросов на вашей стороне обеспечивает более плавную и устойчивую интеграцию.

Для получения информации о лимитах по умолчанию, увеличении запросов и дополнительных деталях см. Лимиты запросов.

Коды ошибок

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	Когда используемый access-token содержит некорректные символы.
—	Jwt is expired	Когда используемый access-token истёк.

Код	Сообщение	Описание
`5`	error getting process: rpc error: code = NotFound desc = process not found	Когда ID процесса не найден.

Код	Сообщение	Описание
`99999`	Internal failure! Try again later	Внутренняя ошибка.

Опрос vs вебхук

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

Что дальше

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

Endpoint​

Эндпоинт​

Запрос​

Пример​

Ответы​

Коды ошибок​

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

Что дальше​