プロセスの作成

これはすべてのWeb & SDKインテグレーションのエントリーポイントです。バックエンドがこれを呼び出してプロセスを作成し、フロントエンドが返されたトークンを使用してiFrameをレンダリングするか、ユーザーをリダイレクトするか、ネイティブSDKを初期化します。

完全なインテグレーションフローについては、Web & SDK概要を参照してください。

エンドポイント

環境	URL
本番	POST https://api.idcloud.unico.app/client/v1/process
サンドボックス	POST https://api.idcloud.uat.unico.app/client/v1/process

リクエスト

ヘッダー

ヘッダー	値
Authorization	Bearer <access_token>（認証を参照）
Content-Type	application/json

ボディパラメータ

フィールド	型	必須	説明
callbackUri	string	はい	ジャーニー終了後にユーザーがリダイレクトされるURL。コールバックがアプリ内で処理されるネイティブSDKフローでは / を使用してください。
flow	string	はい	フロー識別子 - 実行する機能を決定します。例: idunicodocs、idunicosign、idchecktrust、idtoken、idsmart。利用可能なフローを参照してください。
purpose	string	はい	ビジネス目的。受け入れ可能な値: creditprocess、biometryonboarding、carpurchase、ageverification。
person.duiType	enum	はい	ドキュメントタイプ。受け入れ可能な値: DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN、DUI_TYPE_BR_PASSPORT、DUI_TYPE_AR_PASSPORT、DUI_TYPE_AR_DNI、DUI_TYPE_NG_NIN、DUI_TYPE_CL_RUN、DUI_TYPE_EC_NI、DUI_TYPE_US_PASSPORT、DUI_TYPE_GT_CUI、DUI_TYPE_UY_CI、DUI_TYPE_ZZ_EMAIL、DUI_TYPE_ID_NIK、DUI_TYPE_ZZ_PHONE_NUMBER、DUI_TYPE_US_DRIVER_LICENSE、DUI_TYPE_NG_BVN、DUI_TYPE_MX_RFC_PERSONA_FISICA、DUI_TYPE_CO_NIT、DUI_TYPE_PE_RUC、DUI_TYPE_CA_SIN、DUI_TYPE_DK_CPR、DUI_TYPE_GB_NINO、DUI_TYPE_PL_PESEL、DUI_TYPE_SE_PNR、DUI_TYPE_AT_STNR、DUI_TYPE_FI_HETU。
person.duiValue	string	はい	フォーマットなしのドキュメント番号。
person.friendlyName	string	いいえ	ジャーニーUIに表示されるユーザーの表示名。最大50文字。
person.phone	string	いいえ	DDI + DDD + 番号形式の電話番号（区切りなし）。SMSまたはWhatsAppで通知を送信する場合に必須。
person.email	string	いいえ	メールアドレス。電子署名を含むフローに必須。
person.notifications	array	いいえ	ジャーニーリンクを送信するための通知チャネル。各アイテムには notificationChannel があります: NOTIFICATION_CHANNEL_WHATSAPP、NOTIFICATION_CHANNEL_SMS、または NOTIFICATION_CHANNEL_EMAIL。
bioTokenId	string (UUID)	条件付き	非推奨。 代わりに references を使用してください。リファレンス生体認証プロセスのID。1:1 バリデーションフロー（idtoken、idtokentrust、idtokensign）およびスマート再検証（idsmart）に必須。
references	array	条件付き	bioTokenId を置き換える1:1 バリデーションおよびスマート再検証フローのリファレンス入力。各アイテムには referenceType（REFERENCE_TYPE_IMAGE_BASE64 または REFERENCE_TYPE_PROCESS_ID）と referenceContent（base64エンコード画像またはプロセスUUID）が含まれます。
useCase	string	条件付き	スマート再検証のユースケース。idsmart に必須。例: USE_CASE_LOGIN、USE_CASE_IDENTITY_REVALIDATION_7_DAYS、USE_CASE_FIN_TRANSACTIONS。
clientReference	string	いいえ	このプロセスの内部識別子（ポータルでのクロスリファレンス用の外部キー）。
companyBranchId	string (UUID)	いいえ	支店ID。サービスアカウントに複数の支店が関連付けられている場合のみ必須。
expiresIn	string	いいえ	作成からのプロセス有効期間。フォーマット: "3600s"。省略した場合、デフォルトは7日間です。
flow_config	object	いいえ	フローごとの設定オーバーライド。
flow_config.biometry_capture.enabled_back_camera	boolean	いいえ	デバイスの背面カメラを使用します。ドキュメントキャプチャまたは電子署名フローとは互換性がありません。
contextualization	object	いいえ	キャプチャの理由を説明するためにジャーニー中にユーザーに表示されるトランザクションコンテキスト。
contextualization.company_name	string	いいえ	ジャーニー中に表示される会社名。最大20文字。
contextualization.currency	string	いいえ	ユーザーに表示される通貨コード。受け入れ可能な値: BRL、MXN、USD。
contextualization.price	number	いいえ	ユーザーに表示されるトランザクション金額。
contextualization.locale	object	いいえ	ジャーニー中に表示されるローカライズされたテキスト。キー: ptBr、enUs、esMx。
contextualization.locale.{ptBr|enUs|esMx}.reason	string	いいえ	ジャーニー中に表示されるキャプチャの簡単な理由。最大50文字。
contextualization.locale.{ptBr|enUs|esMx}.title	string	いいえ	ジャーニー中に表示される顧客通知のタイトル。最大100文字。text と一緒に指定する必要があります。HTMLタグは除去されます。
contextualization.locale.{ptBr|enUs|esMx}.text	string	いいえ	ジャーニー中に表示される顧客通知の本文。最大210文字。title と一緒に指定する必要があります。HTMLタグは除去されます。

例

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

レスポンス

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

フィールド	型	説明
process.id	string (UUID)	プロセス識別子。プロセスの取得で結果を取得するために使用します。
process.state	enum	PROCESS_STATE_CREATED - プロセスが作成され、ジャーニーはまだ開始されていません。PROCESS_STATE_FAILED - プロセスの作成に失敗しました。
process.flow	string	作成時に送信されたフロー識別子。
process.purpose	string	作成時に送信されたビジネス目的。
process.callbackUri	string	作成時に送信されたコールバックURI。
process.clientReference	string	作成時に送信された内部識別子。リクエストで提供された場合のみ存在します。
process.companyBranchId	string (UUID)	支店ID。リクエストで提供された場合のみ存在します。
process.userRedirectUrl	string	ユーザーをリダイレクトするURL（WebリダイレクトおよびiFrameインテグレーション）。このURLを変更しないでください。
process.token	string	Web SDK iFrameを初期化するためのJWT。
process.webAppToken	string	ネイティブSDK（Android、iOS、Flutter）を初期化するためのJWT。
process.createdAt	string (date-time)	プロセスが作成されたタイムスタンプ。
process.expiresAt	string (date-time)	プロセスが期限切れとなり、完了できなくなるタイムスタンプ。
process.capacities	array	このプロセスに設定された機能。
process.authenticationInfo	object	プロセスの認証情報（作成時は空）。
process.person	object	作成時に送信された person オブジェクトのエコー。
process.companyData.branchId	string (UUID)	プロセスに関連付けられた支店ID。
process.companyData.countryCode	string	支店に関連付けられた国コード（例: BR、MX）。

400 Bad Request

リクエストペイロードの形式が不正、必須フィールドが欠落、または flow の値が不明な場合に返されます。

401 Unauthorized

Bearerトークンが欠落、期限切れ、または無効です。認証を参照してください。

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

エラーコード

400 Bad Request

コード	メッセージ	説明
3	invalid flow	指定されたフローが存在しない場合。
3	invalid person: friendly name exceeds 50 characters.	フレンドリー名が50文字を超えている場合。
3	invalid purpose	提供された目的が無効な場合。
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	提供されたcallbackUriが無効な場合。
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	提供されたメールが無効でメール通知が設定されている場合。
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	提供された電話番号が無効でSMSまたはWhatsApp通知が設定されている場合。
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	提供された識別子（duiValue）が無効な場合。
3	invalid expiresIn argument	expiresIn の値が無効な場合。
3	invalid company_name argument in process contextualization, max length is 20	contextualization.company_name が20文字を超えている場合。
3	title and text must be provided together in process contexts	ロケール内で title または text のいずれか一方のみが指定されている場合。
3	invalid title argument in process contexts, max length is 100	ロケールの title が100文字を超えている場合。
3	invalid text argument in process contexts, max length is 210	ロケールの text が210文字を超えている場合。
3	invalid reason argument in process contexts, max length is 50	ロケールの reason が50文字を超えている場合。
9	XX ID Apikeys are not set	APIキーが正しく設定されていない場合。

401 Unauthorized

メッセージ	説明
Jwt header is an invalid JSON	使用されたアクセストークンに不正な文字が含まれている場合。
Jwt is expired	使用されたアクセストークンが期限切れの場合。

429 Too Many Requests

このステータスに対する詳細なエラーコードは提供されません — HTTPステータスのみです。ベストプラクティスについては上記の 429 Too Many Requests セクションを参照してください。

500 Internal Server Error

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

次のステップ

• ユーザーがジャーニーを完了した後、結果を取得するにはプロセスの取得を呼び出すか、Webhookを待ちます。