プロセスの作成POST

バックエンドから Human Token プロセスを作成し、data.humanToken で humanToken を取得します。

Markdown

Human Token は Human API の POST /client/v1/process エンドポイントで実行されます。API Only フロー（api+humantoken、api+liveness+humantoken、api+liveness+humantoken+revalidation）では、プロセスの作成と完了が1回の呼び出しで行われます。レスポンスには、すでに data.humanToken に結果が含まれています。Human Token Journey フロー（humantoken および humantoken+revalidation）では、レスポンスにプロセスの id、token、ジャーニーの link が含まれ、ユーザーがジャーニーを完了した後に結果が利用可能になります。+revalidation フローでは、再検証のために以前に取得した humanToken を含む references 配列が必要です。

フロー

Human Token は2つの統合モデルで実行されます。

• API Only — バックエンドがセルフィーを imageBase64 で送信します。
• Human Token Journey — ユーザーが Web 上で Unico のジャーニーを進め、完了後にあなたの callbackUri に戻ります。

Flow	Capabilities	Possible result	Integration components required	Example
api+humantoken	Human Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken	LivenessHuman Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	LivenessHuman Token	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb
humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb

エンドポイント

環境	URL
本番	POST https://humantoken.unico.app/client/v1/process

リクエスト

ヘッダー

ヘッダー	値
x-unico-accesskey	<your_access_key>（認証を参照）
Content-Type	application/json

ボディパラメータ

フィールド	型	必須	説明
flow	string	はい	Human Token フロー: api+humantoken、api+liveness+humantoken、api+liveness+humantoken+revalidation（API Only）または humantoken、humantoken+revalidation（Human Token Journey）。フローを参照してください。
imageBase64	string	API Only	フロントエンドでキャプチャし、直接送信するセルフィー（base64）。PNG、JPEG または WebP、最大 800 KB。キャプチャスタンダードに従ってください。
callbackUri	string	Human Token Journey	ジャーニー終了後にユーザーがリダイレクトされる URL。
companyBranchId	string	いいえ	ブランチ識別子。指定された場合、プロセスは指定されたブランチの構成を使用します。
references	array	再検証フロー	参照オブジェクトの配列。+revalidation フローで必須です。各オブジェクトには referenceType（REFERENCE_TYPE_HUMAN_TOKEN）と referenceContent（以前に取得した humanToken の値）が含まれます。

レスポンス

200 OK

フィールド	型	説明
id	string (UUID)	プロセス識別子。プロセスの取得でプロセスを再取得する際に使用します。
state	string	プロセスの状態。結果の解釈を参照してください。API Only フローのみ。
token	string	作成されたプロセスのトークン。Journey SDKエクスペリエンスを開くために使用できます。Human Token Journeyフロー（humantoken、humantoken+revalidation）のみ。
link	string	Human Token Journey の URL です。ユーザーをこの URL に送ります。Human Token Journey フロー（humantoken、humantoken+revalidation）のみ。
data.​humanToken.​value	string	顔の安定した不透明な識別子（最大100文字）。同じ人物は常に同じ値に解決されます。API Only フローのみ（再検証以外）。
data.​humanTokenMatch	string	セルフィーが参照された humanToken と一致する場合は "true"、一致しない場合は "false"。+revalidation API Only フローのみ。

結果の解釈

state	意味	対応
PROCESS_STATE_FINISHED	data.humanToken.value あり：Human Token を持つ実在の人物。	自社の記録で value を検索してください。存在する場合は再訪ユーザーまたは重複の可能性があり、存在しない場合は新しい人物です。
PROCESS_STATE_FINISHED	data.humanToken なし、または value が空：判定不能。	判定不能として扱ってください。空の value は絶対に保存・照合しないでください。ビジネスルールに従って、プロセスを再試行するか拒否してください。
PROCESS_STATE_FAILED	本人確認プロセスが失敗しました。	ビジネスルールに従い、プロセスを再試行するか拒否してください。
PROCESS_STATE_CREATED	プロセスが作成されました。	待機してください。後でプロセスの取得で結果を取得してください。
PROCESS_STATE_CANCELED	プロセスがキャンセルされました。	ユーザーの確認がまだ必要な場合は、新しいプロセスを作成してください。

警告

data.humanToken.value を使用する前に、必ず空でないことを確認してください。

エラーコード

メモ

x-unico-accesskey ヘッダーのアクセスキーが存在しない、または無効な場合に返される HTTP ステータスは現在確認中です。認証を参照してください。

400 Bad Request

コード	メッセージ	説明
3	invalid flow	指定されたフローが存在しない場合。
3	INVALID_IMAGE	画像が有効な base64 でない、またはインジェクション攻撃の疑いがある場合。
3	IMAGE_TOO_LARGE	画像が最大サイズ 800 KB を超えている場合。
3	UNSUPPORTED_IMAGE_FORMAT	画像フォーマットが PNG、JPEG、または WebP でない場合。
3	MISSING_IMAGE	このフローに画像が必須であるにもかかわらず、送信されなかった場合。
3	INVALID_REQUEST	リクエストボディが null、または解釈できない場合。
9	monthly process limit of <monthly_limit> reached for this tenant	月間利用上限に達した場合。
9	PROCESS_FAILED	プロセスの作成中に終了状態の失敗に達した場合。

403 Forbidden

コード	メッセージ	説明
7	PERMISSION_DENIED	認証情報は有効だが、この操作の権限がない場合。

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

500 Internal Server Error

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

このエンドポイントのコードの完全な一覧については、Human API のプロセスの作成リファレンスを参照してください。

次のステップ

• 後続の Human Token 呼び出しで同一人物を認識するために、humanToken の値をユーザーレコードと一緒に保存してください。
• 監査やサポートのためにプロセスを再取得するには、プロセスの取得を使用してください。