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

プロセスの取得

警告

プロセスを取得する前に、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": "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.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身分証明書なしでプロセスが作成されました。プロセスドキュメントの設定で設定されるのを待っています。カスタムフローがオプションのドキュメントを許可する場合のみ存在します。
PROCESS_STATE_FINISHEDジャーニーが完了しました。result と authenticationInfo を確認してください。
PROCESS_STATE_FAILED処理エラー。
状態の命名の不整合

AWAITING_FOR_DOCUMENT は他の状態で使用されている PROCESS_STATE_* プレフィックス規則に従っていません。これは現在のAPIの既知の命名の不整合です。

process.resultの値
値意味
PROCESS_RESULT_OKすべての機能が正の結果を返しました。
PROCESS_RESULT_INVALID_IDENTITY少なくとも1つの機能が決定的な否定結果を返しました（例: ライブネスの失敗、本人認証の不一致）。
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
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フィールド
services における命名規則の混在

services 配列は、エンベロープレベルのフィールド（envelopeId、documentIds）に camelCase を使用し、ドキュメントレベルのフィールド（doc_id、consent_granted、face_match など）に snake_case を使用しています。これは実際の API レスポンスを反映したものであり、両方の規則は意図的なものでドキュメントの誤りではありません。

フィールド型説明
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フィールド。内容はドキュメントタイプと利用可能なデータによって異なります。doc.data 内のフィールド名（例: nomeCivil、dataNascimento）はポルトガル語で返されます — これらは OCR エンジンが実際に出力する値です。
400 Bad Request

processId パスパラメータが欠落しているか不正な形式です。

401 Unauthorized

Bearerトークンが欠落、期限切れ、または無効です。

404 Not Found

processId が存在しないか、認証されたテナントに属していません。

429 Too Many Requests

レート制限に達しました。システムがHTTP 429エラーを受信した場合、カスケード障害を防ぎ、制限の悪化を避けるためのメカニズムを実装する必要があります。

ベストプラクティス:

  • クールダウン期間（バックオフ）: システムからの後続リクエストを直ちに停止またはスロットルしてください。失敗したリクエストをタイトループで継続的にリトライしないでください。
  • キューイングとスロットリング: 再送信前にトラフィックフローを制御するために、送信リクエストをバッファまたはキューに入れてください。
  • ジッターを含む指数バックオフ: リトライ時に、試行間の待機時間を指数的に増加させ（例: 1秒、2秒、4秒、8秒）、すべてのキューされたリクエストがまったく同じミリ秒にリトライするハード効果を防ぐために小さなランダム遅延（「ジッター」）を追加してください。
警告

バックオフせずにレート制限されたエンドポイントに継続的にアクセスすると、制限期間が延長され、システムの運用スループットに深刻な影響を与える可能性があります。リクエストを適切にスロットリングすることで、よりスムーズで回復力のあるインテグレーションが確保されます。

デフォルトの制限、リクエストの増加、その他の詳細については、レート制限を参照してください。

エラーコード​

コードメッセージ説明
3process id is invalidプロセスIDが無効な場合。

ポーリング vs Webhook​

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

次のステップ​

最終更新 に