プロセスの作成

これはすべての 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。
person.duiValue	string	はい	フォーマットなしのドキュメント番号。
person.friendlyName	string	いいえ	ジャーニー UI に表示されるユーザーの表示名。最大 50 文字。
person.phone	string	いいえ	国際電話番号 + 市外局番 + 番号の形式の電話番号（区切り文字なし）。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）および Smart Revalidation（idsmart）に必須。
references	array	条件付き	1:1 検証および Smart Revalidation フローの参照入力。bioTokenId を置き換えます。各アイテムには referenceType（REFERENCE_TYPE_IMAGE_BASE64 または REFERENCE_TYPE_PROCESS_ID）と referenceContent（base64 エンコードされた画像またはプロセス UUID）が含まれます。
useCase	string	条件付き	Smart Revalidation のユースケース。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.currency	string	いいえ	ユーザーに表示される通貨コード。指定可能な値: BRL、MXN、USD。
contextualization.price	number	いいえ	ユーザーに表示されるトランザクション金額。
contextualization.locale	object	いいえ	ローカライズされた理由テキスト。キー: ptBr、enUs、esMx — それぞれジャーニー中に表示される reason 文字列を持ちます。

例

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

レート制限に達しました。レスポンスヘッダーに示された間隔の後に再試行してください。

エラーコード

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 の値が無効な場合。
9	XX ID Apikeys are not set	API キーが適切に設定されていない場合。

401 Unauthorized

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

429 Too Many Requests

このステータスに対する詳細なエラーコードは提供されていません — HTTP ステータスのみ。

500 Internal Server Error

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

次のステップ

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