プロセスドキュメントの設定POST

ドキュメントなしでプロセスを作成し、ユーザーにキャプチャを完了させてから、バックエンドからドキュメントを送信します。その後、プロセスが完了します。

MarkdownChatGPTClaude

ライフサイクル

1. バックエンドが プロセスの作成 で、person.duiType と person.duiValue を指定せずにプロセスを作成します。フローが任意のドキュメントを許可している必要があります。プロセスは PROCESS_STATE_CREATED として開始します。
2. ユーザーがジャーニーを実行し、キャプチャを行います。
3. Unico API がプロセスを AWAITING_FOR_DOCUMENT に移行します。これは、プロセスがドキュメントを待機している間に プロセスの取得 が返す状態です。この時点で、duiValue に依存しないケイパビリティの部分的な結果をすでに読み取ることができます。
4. バックエンドが、URL にプロセス ID、ボディにドキュメントを指定してこのエンドポイントを呼び出します。その後、Unico API がプロセスを完了し、プロセスは PROCESS_STATE_FINISHED に移行します。

レスポンスには最終結果は含まれません

最終的な状態と結果は プロセスの取得 で読み取るか、Webhook を待ってください。

エンドポイント

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

リクエスト

ヘッダー

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

認証情報には、プロセスの作成 の呼び出しに使用するのと同じ権限が必要です。

パスパラメータ

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

ボディパラメータ

フィールド	型	必須	説明
duiType	enum	はい	ドキュメントの種類。DUI_TYPE_UNSPECIFIED は拒否されます。下記の duiType の値 を参照してください。
duiValue	string	はい	書式なしのドキュメント番号。最大 320 文字。

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	電話番号

呼び出しが受け付けられる条件

• プロセスが AWAITING_FOR_DOCUMENT にあること：ユーザーがすでにキャプチャを完了している。
• プロセスの有効期限が切れていないこと。
• フローが任意のドキュメントを許可していること。

ドキュメントは変更できません。プロセスがもうドキュメントを待機していないため、2 回目の呼び出しは失敗します。

例

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

レスポンス

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

フィールド	型	説明
processId	string (UUID)	プロセス識別子。
duiType	enum	プロセスに登録されたドキュメントの種類。
duiValue	string	プロセスに登録されたドキュメント番号。

例の値はプレースホルダーです。

エラーコード

400 Bad Request

コード	説明
3	processId が欠落しているか無効、duiType が未指定、または duiValue が空か 320 文字を超えています。
9	プロセスがドキュメントを待機していない（ドキュメントがすでに設定されている場合を含む）、有効期限切れまたは完了済み、あるいはフローが任意のドキュメントを許可していません。

401 Unauthorized

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

403 Forbidden

コード	説明
7	認証情報に プロセスの作成 で必要な権限がありません。

404 Not Found

コード	説明
5	プロセスが存在しないか、貴社に属していません。

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

500 Internal Server Error

コード	説明
13	ドキュメントを保存できませんでした。

メモ

ドキュメントは保存される前に本人確認サービスに登録されます。その登録が失敗した場合、呼び出しはその失敗のステータスを返します。

次のステップ

• 最終的な状態と結果を読み取るには、プロセスの取得 を参照してください。
• プロセスの完了時に通知を受け取るには、WebhookとEvents を参照してください。