プロセスの作成

MarkdownChatGPTClaude

これはすべての Unico API 統合のエントリーポイントです。バックエンドがこれを呼び出してプロセスを作成し、フロントエンドが返されたトークンを使用してiFrameをレンダリングするか、ユーザーをリダイレクトするか、ネイティブ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

ボディパラメータ

フィールドの要件はフローによって異なります

フィールドが必須、任意、または該当なしかは、統合している flow によって異なります — このテーブルだけでフィールドの要件を判断する前に、使用している特定のレシピについてフローを確認してください。

Field	Type	Description
callbackUri	string	ジャーニー終了後にユーザーがリダイレクトされるURL。コールバックがアプリ内で処理されるネイティブSDKフローでは / を使用してください。
flow	string	フロー識別子 — 実行するケイパビリティを決定します。例: idunicodocs、idunicosign、idchecktrust、idtoken、idsmart。利用可能なフローを参照してください。
purpose	string	ビジネス目的。受け入れ可能な値: creditprocess、biometryonboarding、carpurchase、ageverification。
person.duiType	enum	ドキュメントタイプ。下記のduiType の値を参照してください。
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。
references	array	1:1 バリデーションおよびスマート再検証フロー用のリファレンス入力。各アイテムには referenceType（REFERENCE_TYPE_IMAGE_BASE64 または REFERENCE_TYPE_PROCESS_ID）と referenceContent（base64エンコード画像またはプロセスUUID）が含まれます。最大1要素を送信してください — それより長い配列は 400 で拒否され、referenceContent は空であってはなりません。
useCase	string	スマート再検証のシナリオ。🇧🇷 idsmart、idsmart_r2、idsmart_tp1 に必須。例: USE_CASE_LOGIN、USE_CASE_FIN_TRANSACTIONS。
clientReference	string	あなたのシステムにおけるユーザーの一意の識別子。マルチアカウントケイパビリティに必須です。 自社ベース内で一意、最大256文字、スペース不可。
companyBranchId	string (UUID)	支店ID。サービスアカウントに複数の支店が関連付けられている場合のみ必須。
expiresIn	string	作成からのプロセス有効期間。フォーマット: "3600s"。省略した場合、デフォルトは7日間です。
flowConfig	object	フローごとの設定オーバーライド。
flowConfig.​biometryCapture.​enabledBackCamera	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タグは除去されます。
imageBase64	string	セルフィー。直接送信されます。SDKのキャプチャJWTを受け付けます。
document.purpose	enum	ドキュメントの用途。固定の語彙: DOCUMENT_PURPOSE_ONBOARDING、DOCUMENT_PURPOSE_CREDIT_PROCESS、DOCUMENT_PURPOSE_CAR_PURCHASE、DOCUMENT_PURPOSE_PAY_BY_PAYCHECK、DOCUMENT_PURPOSE_FGTS。顔写真とドキュメントの照合フローでのみ使用されます。
document.​files[].​data	bytes	新規ドキュメントキャプチャ、base64エンコード。ブラジルに限定されず、グローバルに利用可能です。document.documentId とは相互排他的です。
document.documentId	string (UUID)	新規キャプチャの代わりに、同じ人物によってすでにキャプチャされたドキュメントを再利用します。document.files[] とは相互排他的です。
expectedResult	object	テスト/サンドボックス環境でケイパビリティの結果をモックし、レスポンスに simulated: true を設定します。結果のシミュレーション（テストモック）を参照してください。

duiType の値

国	値	説明
AR	DUI_TYPE_AR_PASSPORT	アルゼンチン パスポート
AR	DUI_TYPE_AR_DNI	アルゼンチン DNI
AR	DUI_TYPE_AR_LNC	アルゼンチン 運転免許証（Licencia Nacional de Conducir）
AT	DUI_TYPE_AT_STNR	オーストリア 納税者番号（STNR）
BE	DUI_TYPE_BE_NN	ベルギー 国民番号（NN）
BR	DUI_TYPE_BR_CPF	ブラジル CPF
BR	DUI_TYPE_BR_PASSPORT	ブラジル パスポート
BR	DUI_TYPE_BR_CNPJ	ブラジル CNPJ
CA	DUI_TYPE_CA_SIN	カナダ SIN
CH	DUI_TYPE_CH_AHV	スイス AHV/AVS番号
CL	DUI_TYPE_CL_RUN	チリ RUN
CL	DUI_TYPE_CL_PASSPORT	チリ パスポート
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	チリ 運転免許証（Licencia de Conducir）
CO	DUI_TYPE_CO_NIT	コロンビア NIT
CO	DUI_TYPE_CO_PASSPORT	コロンビア パスポート
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	コロンビア 運転免許証（Licencia de Conducción）
CO	DUI_TYPE_CO_CC	コロンビア 市民証（Cédula de Ciudadanía）
DE	DUI_TYPE_DE_IDNR	ドイツ 税務識別番号（IdNr）
DK	DUI_TYPE_DK_CPR	デンマーク CPR
EC	DUI_TYPE_EC_NI	エクアドル NI
ES	DUI_TYPE_ES_NIE	スペイン 外国人識別番号（NIE）
ES	DUI_TYPE_ES_DNI	スペイン 国民身分証明書（DNI）
FI	DUI_TYPE_FI_HETU	フィンランド 個人識別番号（HETU）
FR	DUI_TYPE_FR_SPI	フランス 税務参照番号（SPI）
GB	DUI_TYPE_GB_NINO	英国 国民保険番号（NINO）
GT	DUI_TYPE_GT_CUI	グアテマラ CUI
ID	DUI_TYPE_ID_NIK	インドネシア NIK
IE	DUI_TYPE_IE_PPSN	アイルランド 個人公共サービス番号（PPSN）
IT	DUI_TYPE_IT_CF	イタリア 税務番号（CF）
LK	DUI_TYPE_LK_NIC	スリランカ NIC
LU	DUI_TYPE_LU_MATRICULE	ルクセンブルク 国民識別番号（Matricule）
MX	DUI_TYPE_MX_CURP	メキシコ CURP
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	メキシコ RFC（個人）
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	メキシコ 運転免許証（Licencia de Conducir）
NG	DUI_TYPE_NG_NIN	ナイジェリア NIN
NG	DUI_TYPE_NG_BVN	ナイジェリア 銀行認証番号（BVN）
NG	DUI_TYPE_NG_BVN_TOKEN	ナイジェリア BVNトークン（ハッシュ化）
NG	DUI_TYPE_NG_NIN_TOKEN	ナイジェリア NINトークン（ハッシュ化）
NL	DUI_TYPE_NL_BSN	オランダ 市民サービス番号（BSN）
NO	DUI_TYPE_NO_FNR	ノルウェー 国民識別番号（Fødselsnummer）
PE	DUI_TYPE_PE_RUC	ペルー RUC
PE	DUI_TYPE_PE_DNI	ペルー DNI
PE	DUI_TYPE_PE_PASSPORT	ペルー パスポート
PL	DUI_TYPE_PL_PESEL	ポーランド PESEL
PT	DUI_TYPE_PT_NIF	ポルトガル 納税者番号（NIF）
SE	DUI_TYPE_SE_PNR	スウェーデン 個人番号（PNR）
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	スウェーデン 調整番号（Samordningsnummer）
TR	DUI_TYPE_TR_TCKN	トルコ 国民識別番号（TCKN）
US	DUI_TYPE_US_SSN	アメリカ合衆国 SSN
US	DUI_TYPE_US_PASSPORT	アメリカ合衆国 パスポート
US	DUI_TYPE_US_DRIVER_LICENSE	アメリカ合衆国 運転免許証
US	DUI_TYPE_US_PASSPORT_CARD	アメリカ合衆国 パスポートカード
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	アメリカ合衆国 ポリカーボネートパスポート
US	DUI_TYPE_US_ID_CARD	アメリカ合衆国 IDカード
UY	DUI_TYPE_UY_CI	ウルグアイ CI
ZZ	DUI_TYPE_ZZ_EMAIL	メールアドレス
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	電話番号

ドキュメントなしでプロセスを作成する

フローが任意のドキュメントを許可している場合、person.duiType と person.duiValue を省略できます。キャプチャ後、バックエンドが プロセスドキュメントの設定 でドキュメントを送信するまで、プロセスは AWAITING_FOR_DOCUMENT で待機します。

例

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "idunicodocs_r2",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    }
  }'

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({
    flow: 'idunicodocs_r2',
    purpose: 'biometryonboarding',
    clientReference: 'pedido-88216',
    callbackUri: 'https://your-app.example.com/onboarding/callback',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    },
  }),
});

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

レスポンス

200 OK

{
  "process": {
    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "flow": "idunicodocs_r2",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDLIVE",
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDDOCS"
    ],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "companyData": {
      "branchId": "",
      "countryCode": "BRA"
    },
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
    "simulated": false
  }
}

Field	Type	Description
process.id	string (UUID)	プロセス識別子。プロセスの取得経由で結果を取得するために使用します。
process.state	enum	PROCESS_STATE_CREATED — プロセスが作成され、ジャーニーはまだ開始されていません。PROCESS_STATE_FAILED — プロセスの作成に失敗しました。
process.result	enum	検証結果。state = PROCESS_STATE_FINISHED の場合のみ存在します — 特定のフローが返す可能性のある結果値についてはフローを参照してください。
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

Code	Message	Description
3	invalid flow	指定されたフローが存在しない場合。
3	invalid person: friendly name exceeds 50 characters.	フレンドリー名が50文字を超えている場合。
3	invalid purpose	提供された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文字を超えている場合。
3	The references array must contain at most one element.	references に複数のアイテムが送信された場合。
3	The references[].referenceContent field is missing.	referenceContent が空の場合。
3	The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.	referenceType がサポートされている値のいずれでもない場合。
3	A reference is required for this flow.	フローがリファレンスを要求しているにもかかわらず、何も送信されなかった場合。referenceType に PROCESS_ID または IMAGE_BASE64 を指定した references[0] を送信してください。
9	The referenceProcessId field is invalid.	リファレンスプロセスが存在しない、または再利用できない場合。送信したフィールド名で表示されます — bioTokenId を送信した場合はその名前になります。
3	INVALID_IMAGE	画像が有効なbase64でない、またはインジェクション攻撃の疑いがある場合。
3	INVALID_DUI	ドキュメント番号が標準外、または存在しない場合。
3	IMAGE_TOO_LARGE	画像が最大サイズ800 KBを超えている場合。
3	UNSUPPORTED_IMAGE_FORMAT	画像フォーマットがPNG、JPEG、またはWebPでない場合。
3	MISSING_IMAGE	このフローに画像が必須であるにもかかわらず、送信されなかった場合。
3	MISSING_NAME	このフローに名前が必須であるにもかかわらず、送信されなかった場合。
3	MISSING_DUI	このフローにドキュメント番号が必須であるにもかかわらず、送信されなかった場合。
3	MISSING_PERSON	このフローに person オブジェクトが必須であるにもかかわらず、送信されなかった場合。
3	INVALID_REQUEST	リクエストボディがnull、または解釈できない場合。
3	TOKEN_ALREADY_USED	キャプチャトークンがすでに使用されている場合。一度だけ使用可能です。
3	TOKEN_EXPIRED	キャプチャトークンが期限切れの場合。10分以内に使用する必要があります。
3	INVALID_BUNDLE	リクエストがセキュリティ要件を満たしていない場合。
3	INVALID_NAME	名前が許可された最大文字数を超えている場合。
3	INVALID_EMAIL	メールアドレスの形式が不正、または長すぎる場合。
3	INVALID_PHONE	電話番号が20文字を超えている場合。
3	INVALID_DUI_TYPE	ドキュメントタイプがサポートされている値のいずれでもない場合。
3	INVALID_CLIENT_REFERENCE	clientReference が長すぎる、またはスペースや # を含む場合。
3	INVALID_CONSENT_TYPE	consentType が NONE、DIRECT、INDIRECT のいずれでもない場合。
3	INVALID_USE_CASE	useCase が認識されない、または長すぎる場合。
3	INVALID_DEVICE_TRUST_TOKEN	デバイストラストトークンが無効、またはすでに消費されている場合。
3	TOO_MANY_REFERENCES	references に複数のアイテムが送信された場合。
3	INVALID_REFERENCE_TYPE	referenceType が IMAGE_BASE64 または PROCESS_ID のいずれでもない場合。
3	INVALID_REFERENCE_PROCESS	リファレンスプロセスIDが有効な識別子でない場合。
3	REFERENCE_PROCESS_NOT_FOUND	参照されたプロセスが存在しない場合。
3	REFERENCE_PROCESS_NOT_READY	参照されたプロセスに再利用可能な結果がない、またはすでに消費されている場合。
3	REFERENCE_SELFIE_NOT_FOUND	参照されたプロセスに再利用可能なセルフィーがない場合。
3	INVALID_CAPTURE_TOKEN	キャプチャされた画像が、キャプチャSDKによって生成された有効なトークンでない場合。
3	INVALID_CAPTURE_SIGNATURE	キャプチャトークンの署名が検証できない場合。
3	PRIOR_CAPTURE_NOT_FOUND	このリクエストが基づく以前のキャプチャが見つからなかった場合。プロセスを再開してください。
3	PRIOR_CAPTURE_IN_PROGRESS	以前のキャプチャがまだ完了していない場合。しばらくしてから再試行してください。
3	PRIOR_CAPTURE_FAILED	以前のキャプチャを完了できなかった場合。プロセスを再開してください。
3	INVALID_DOCUMENT	ドキュメントファイルが読み取り不能、パスワード保護されている、またはサポートされていないフォーマットの場合。
3	INVALID_AUTH_PROCESS	document.authProcessId が無効、期限切れ、または他の人物に属している場合。
3	INVALID_DOCUMENT_PURPOSE	document.purpose がサポートされている値のいずれでもない場合。
3	PROCESS_REUSE_NOT_ENABLED	フローが画像なしで以前のプロセスを再利用することを許可していない場合。代わりに画像を送信してください。
9	PROCESS_FAILED	プロセスが作成中に終端の失敗に到達した場合。
9	Tenant API key is not configured	APIキーが正しく設定されていない場合。

401 Unauthorized

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

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

403 Forbidden

Code	Message	Description
7	INVALID_API_KEY	APIキーが無効、または欠落している場合。
7	INVALID_AUTH_TOKEN	認証トークンが無効な場合。
7	PERMISSION_DENIED	認証情報は有効だが、このアクションを実行する権限がない場合。
7	TOKEN_TENANT_MISMATCH	キャプチャトークンが別のテナント向けに発行されている場合。
7	MISSING_ACCESS_TOKEN	認証ヘッダーが欠落している場合。

404 Not Found

Code	Message	Description
5	NO_RESULTS_FOUND	リクエストが参照するドキュメントが見つからなかった場合。

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

500 Internal Server Error

Code	Message	Description
13	Internal failure! Try again later	内部エラーが発生した場合。

次のステップ

• ユーザーがジャーニーを完了した後、結果を取得するにはプロセスの取得を呼び出すか、Webhookを待ちます。
• すべてのレシピの組み合わせとその可能な結果値を確認するには、フローを参照してください。
• 実際の生体認証キャプチャなしで結果をテストするには、結果のシミュレーション（テストモック）を参照してください。