メインコンテンツへスキップ

再利用可能なドキュメントの取得

このエンドポイントを使用して、新しいドキュメントキャプチャフローを開始する前に、ユーザーが再利用可能なドキュメントを既に持っているかどうかを確認します。ドキュメントが見つかった場合、その documentId を POST /processes/v1（ドキュメントタイプ）に直接渡してキャプチャステップをスキップできます。

エンドポイント​

環境URL
本番GET https://api.id.unico.app/documents/v1
サンドボックスGET https://api.id.uat.unico.app/documents/v1

リクエスト​

ヘッダー
ヘッダー値
AuthorizationBearer <access_token>（認証を参照）
APIKEYドキュメントキャプチャと再利用が有効なプロビジョニング済みAPIキー。
クエリパラメータ
パラメータ型必須説明
codestringはいユーザー識別子（フォーマットなしのCPFまたはCURP）。
typestringはいクエリするドキュメントタイプ。受け入れ可能な値: BR_RG、BR_CNH、BR_CIN、BR_PASSPORT。
メモ

上記の type の値はこのエンドポイント固有のものです。以下と混同しないでください:

  • POSTリクエストの subject.duiType - DUI_TYPE_* プレフィックスを使用し、ドキュメントタイプではなく人物を識別します（例: DUI_TYPE_BR_CPF）。
  • レスポンスの documentType - 完全なレジストリパスを使用します（例: unico.moja.dictionary.br.cnh.v2.Cnh）。

例​

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

レスポンス​

200 OK
{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}
フィールド型説明
itemsarrayユーザーに見つかった再利用可能なドキュメントのリスト。指定した code と type に対して再利用可能なドキュメントが見つからない場合は空の配列。
items[].documentTypestringドキュメントタイプ識別子。可能な値: unico.moja.dictionary.br.rg.v2.Rg、unico.moja.dictionary.br.cnh.v2.Cnh、unico.moja.dictionary.br.cin.v1.Cin、unico.moja.dictionary.br.passaporte.v1.Passaporte。
items[].documentIdstringドキュメント識別子。ドキュメントを再利用するには、POST /processes/v1 の document.documentId にこの値を渡します。
403 Forbidden

Bearerトークンまたは APIKEY が欠落、期限切れ、または無効です。

429 Too Many Requests

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

ベストプラクティス:

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

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

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

documentIdを使用した再利用​

documentId を取得したら、ドキュメントプロセスリクエストに渡してキャプチャをスキップします:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}
フィールド説明
document.purposeこのドキュメントプロセスのビジネス目的。受け入れ可能な値: creditprocess、carpurchase、paybypaycheck、onboarding、fgts。これらの値はドキュメントAPI固有のものであり、生体認証SDKの purpose enumとは異なります。
document.authProcessIdこのユーザー用に以前作成された生体認証プロセスのID（POST /processes/v1 から取得）。
document.documentIdこのエンドポイントのレスポンスから取得したドキュメントID。指定した場合、document.files を省略できます。プラットフォームが以前にキャプチャされたドキュメントを自動的に取得します。

完全なドキュメントプロセスリクエストスキーマについては、ドキュメントプロセスの作成を参照してください。

エラーコード​

コードメッセージ説明
20507O parâmetro subject.code é inválido.不正な形式または存在しない識別子の値（CPFまたはCURP）。
20002O parâmetro APIKey não foi informado.APIKEYヘッダーが欠落しています。
20001O parâmetro authtoken não foi informado.認証トークンヘッダーが欠落しています。
最終更新 に