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

ドキュメントなしで作成されたプロセスに身分証明書（CPF、CURP、SSNまたはその他の duiType）を設定します。設定後、ドキュメントは変更不可になります。

カスタムフローがドキュメントなしでの作成を許可するプロセス、つまり AWAITING_FOR_DOCUMENT 状態のプロセスでのみ使用可能です。

エンドポイント

環境	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	はい	作成時に process.id で返されたプロセスID。

ボディパラメータ

フィールド	型	必須	説明
duiType	enum	はい	ドキュメントタイプ。値: DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN。このエンドポイントはプロセスの作成で受け入れられるドキュメントタイプのサブセットをサポートしています。オプションのドキュメント作成を許可するカスタムフローは、現在このより狭いリストに対して検証されます。
duiValue	string	はい	フォーマットなしのドキュメント番号。最大320文字（エンコードまたは複合識別子に対応。CPFやCURPなどの標準的なドキュメント番号は大幅に短くなります）。

例

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/abc-123/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678901"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  'https://api.idcloud.unico.app/client/v1/process/abc-123/document',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678901',
    }),
  }
);

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

レスポンス

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

フィールド	型	説明
process.id	string	プロセス識別子。
process.person.duiType	string	プロセスに設定されたドキュメントタイプ。
process.person.duiValue	string	プロセスに設定されたドキュメント値。

エラーコード

400 Bad Request

コード	メッセージ	説明
3	process id is invalid	プロセスIDが無効な場合。
3	dui_type is required	ドキュメントタイプが提供されていない場合。
3	dui_value is required	ドキュメント番号が提供されていない場合。
3	dui_value exceeds maximum length	ドキュメント番号が最大文字数制限を超えている場合。
9	process is not awaiting for document	指定されたプロセスがドキュメント送信を受け付けない場合。
9	process expired	指定されたプロセスが期限切れの場合。
9	document already set, cannot be modified	プロセスに既にリンクされたドキュメントがある場合。
9	process already finished	プロセスが既に完了している場合。
9	flow does not allow optional document	プロセスで実行されるフローにドキュメントが必須の場合。

401 Unauthorized

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

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

404 Not Found

コード	メッセージ	説明
5	error getting process: rpc error: code = NotFound desc = process not found	プロセスIDが見つからなかった場合。

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

500 Internal Server Error

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

次のステップ

• ドキュメントを設定した後、プロセスはパイプラインを続行します。結果を取得するにはプロセスの取得を呼び出すか、Webhookを待ちます。