Перейти к основному содержимому

Получить процесс

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

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

Endpoint​

Среда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": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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Процесс создан без идентификационного документа; ожидается его передача через Set Process 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.

Сокращённые формы в сценариях ответов

На странице Сценарии ответов используются сокращённые значения enum (например, livenessResult = LIVE, authenticationResult = INCONCLUSIVE) для удобства чтения. Они напрямую соответствуют полным значениям enum, задокументированным здесь (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
ПолеТипОписание
envelopeIdstring (UUID)Идентификатор подписанного конверта.
documentIdsarray of stringsИдентификаторы захваченных документов в данном сервисе.
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, RG).
documents[].doc.dataobjectИзвлечённые поля OCR. Содержимое зависит от типа документа и доступных данных.
400 Bad Request

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

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

Достигнут лимит запросов.

Коды ошибок​

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

Polling и webhook​

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

Что дальше​

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