メインコンテンツへスキップ

プロセスの取得

警告

プロセスを取得する前に、Webhook の設定とフォールバック戦略を確認してください — こちらをクリック。

エンドポイント​

環境URL
本番GET https://api.idcloud.unico.app/client/v1/process/{processId}
サンドボックスGET 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.callbackUristringプロセスイベント用に設定されたコールバック URL。
process.userRedirectUrlstringジャーニー完了後にユーザーをリダイレクトする URL。
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.tokenstringSDK 統合用の署名付き JWT。
process.personobject作成時に提供された識別情報。
process.person.notificationsarrayジャーニー用に設定された通知チャネル（例: email）。
process.authenticationInfoobjectケイパビリティごとの結果。下記を参照。
process.companyDataobject企業とブランチのコンテキスト。
process.companyData.branchIdstringブランチ識別子。
process.companyData.countryCodestringISO 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少なくとも 1 つのケイパビリティが確定的な否定結果を返した（例: liveness 失敗、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
bioTokenEngineResult1: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.scoreSerpro類似度返却0–100（類似度）; -1（この CPF に顔データなし）; -2（統合エラー）。
process.services フィールド
フィールド型説明
envelopeIdstring (UUID)署名済みエンベロープ識別子。
documentIdsarray of stringsこのサービスでキャプチャされたドキュメントの ID。
consent_grantedbooleanユーザーがデータ共有の同意を付与したかどうか。
documentsarrayOCR データおよびバリデーション結果を含むキャプチャされたドキュメント。
documents[].doc_idstringドキュメント識別子。
documents[].typifiedbooleanドキュメントタイプが正常に識別されたかどうか。
documents[].cpf_matchbooleanドキュメントの CPF が提供された CPF と一致するかどうか。
documents[].face_matchbooleanセルフィーがドキュメントの写真と一致するかどうか。
documents[].validate_docbooleanドキュメントが真正性バリデーションに合格したかどうか。
documents[].reused_docbooleanこのドキュメントが以前のプロセスから再利用されたかどうか。
documents[].signed_urlstringドキュメント PDF をダウンロードするための事前署名付き URL（5 分間有効 — 更新するには再取得してください）。
documents[].doc.versionintegerOCR スキーマのバージョン。
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プロセス ID が無効な場合。

ポーリングと Webhook​

このエンドポイントをポーリングして進捗を確認することもできますが、推奨パターンは Webhook を購読し、このエンドポイントはフォールバックとしてのみ呼び出すことです。Webhook とイベントを参照してください。

次のステップ​

最終更新 に