プロセスの取得GET

既存のプロセスを識別子で取得します。APIコントラクトの仕様上、結果はプロセス作成時にすでに同期的に返されているため、このエンドポイントは再照会・監査・サポート対応に使用します。

警告

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

エンドポイント

環境	URL
本番	GET https://api.id.unico.app/processes/v1/{processId}
サンドボックス	GET https://api.id.uat.unico.app/processes/v1/{processId}

リクエスト

ヘッダー

ヘッダー	値
Authorization	Bearer <access_token>
APIKEY	発行済みのAPIキー。

パスパラメータ

パラメータ	型	必須	説明
processId	string (UUID)	はい	プロセスの作成で返されるプロセス識別子。

例

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

レスポンス

200 OK

このコントラクトは単一で、idCloud.result フィールドが使用されたケイパビリティの統合された判定結果を保持します。

Unicoは、実行されたケイパビリティの結果を単一の idCloud.result に統合します。個々の結果をオーケストレーションする必要はなく、フローの次のステップをすぐに判断できます。

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

可能な結果の値

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

返される値は、APIKeyに設定されたレシピによって異なります。各レシピが返す結果値については、フローを参照してください。

このエンドポイントの使用タイミング

APIコントラクトは結果を同期的に返すため、ほとんどの統合ではこのエンドポイントは不要です。次の場合に使用します。

• processId のみを保存しており、後で完全な結果を取得する必要がある場合（監査、サポート対応）。
• 元のレスポンスが通信中に失われた可能性がある場合（プラットフォームが処理を完了した後のネットワークエラー）。
• 過去のプロセスを確認するバックオフィスツールを構築している場合。

エラーコード

400 Bad Request

コード	メッセージ	説明
20023	O parâmetro processId não foi informado.	processId パラメータが指定されていません。
20002	O parâmetro APIKey não foi informado.	リクエストヘッダーにAPIKEYパラメータがありません。
20001	O parâmetro authtoken não foi informado.	リクエストヘッダーに統合トークンパラメータがありません。

404 Not Found

コード	メッセージ	説明
50001	O processo informado não foi encontrado.	指定されたプロセスがデータベースに存在しません。

403 Forbidden

コード	メッセージ	説明
30017	User does not have permission to perform this action.	JWTが不正であるか、この操作を実行する権限がないユーザーです。
10502	O token informado está expirado.	使用されたアクセストークンの有効期限が切れている場合。
10501	O token informado é inválido.	認証トークンが無効です。
10201	O AppKey informado é inválido.	APIKEYパラメータが入力されていないか、存在しません。

410 Gone

プロセスは存在しますが、エラーで終了しています。id と status: 5 のみを返します。

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

警告

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

コード	メッセージ	説明
99999	Internal failure! Try again later	内部エラーが発生した場合。

フロー

レシピとは、プロジェクトのAPIKeyに設定されたケイパビリティ（ライブネス、本人確認、リスクシグナル、ドキュメントなど）の組み合わせです。各プロセスでUnicoが何を実行し、結果がどのように単一の result に統合されるかを定義します — お客様側でオーケストレーションを行う必要はありません。

Unicoは、名前とバージョンが付けられた事前定義済みレシピのカタログを管理しています（例: byunico-idlive-idunico-oneresponse-std）。Score、Serpro、年齢確認を含むものなど、一部はブラジル専用です。

プロセスはどのケイパビリティを実行しますか?

ケイパビリティの組み合わせ（プロジェクトのフロー）は、APIKeyの設定で定義されます。事前定義済みのレシピを確認するか、Unicoのプロジェクト担当者にカスタマイズを相談してください。