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

再処理と生体認証ベースのインポート

このガイドでは、Unicoプラットフォームでの再処理または生体認証ベースのインポートの実施方法について説明します。プラットフォームのベストプラクティスに従った効果的で安全な統合のための技術的・運用上の要件を詳述します。

スコープ​

この資料では、2種類のプロセスを対象としています:

  • 再処理: クライアントおよびUnicoのベースを既に通過したユーザーの生体認証レコードを、再評価またはシステム間の移行のために再処理します。
  • 生体認証ベースのインポート: 本人確認およびリスク分類を目的とした、セルフィーを含むベースの初期アップロードまたは更新。
  • 書類ベースのインポート: FacematchまたはCPF Match認証を目的として、セルフィーとともに書類ベースをアップロードします（ブラジル限定）。

前提条件​

  • クライアントは、Unicoとの有効な契約またはNDAに署名済みであり、統合フェーズにある必要があります（ガバナンスチームによる承認がある場合は例外）。
  • プロジェクトは正式なTPS（1秒あたりのトランザクション数）合意に従います。以下のTPS合意を参照してください。
  • 本番認証情報を取得する前に、データ品質、ペイロードの準拠性、安定したパフォーマンスを確保するために統合ホモロゲーションの完了が必須です。
  • 再処理またはインポート用に専用のサービスアカウントを作成する必要があります（例:「Reprocessing」または「Legacy_Import」）。
  • 再処理/インポート専用の専用APIキーが作成されます。
  • （オプション） 再処理/インポート用に専用の子会社を作成できます。このパラメータはペイロード内でsubsidiaryIdとして識別されます。以下のペイロードパラメータを参照してください。
  • APIキーとサービスアカウントは、合意された期間の終了後または処理完了後に無効化されます。

利用可能なケイパビリティ​

ケイパビリティ説明
本人確認送信されたセルフィーが識別子の実際の所有者のものであるかを確認します。
不正リスク分類その顔に関連する不正行為の履歴を確認します。
Facematch書類の写真が送信されたセルフィーと一致するかを確認します。
CPF Match BrazilBrazil only提供されたCPFが書類に印刷されたCPF番号と一致するかを確認します。注: すべてのRGにCPFが印刷されているわけではありません。

セルフィーの要件​

  • base64形式で送信する必要があります。
  • 画像はICAO規格に準拠する必要があります（明るい背景、顔が中央に位置、識別を妨げるアクセサリーなし、適切な照明）。
  • 推奨サイズ: 1920x1080または1080x1920の比率。
  • 最大サイズ: 800 KB（必要に応じてJPEG 92で圧縮してください）。
  • 向き: 縦向き。

書類の要件​

  • 対応している書類の種類: ドキュメントキャプチャと再利用 — 対応書類を参照してください。
  • 画像には書類の表面と裏面の両方が含まれている必要があり、切り取りなしで完全に表示されている必要があります。
  • 書類は読み取り可能である必要があります — 明瞭で、十分な照明があり、遮蔽物がないこと。

TPS合意​

  • このプロジェクトの合意された最大TPSは10 TPSです。
  • リクエストを大量のバーストで送信するのではなく、時間をかけて均等に分散してください。
  • Unicoチームからの正式な承認なしにこの制限を超えてはなりません。
  • 制限を超えたリクエストは自動的にドロップまたはブロックされる場合があります。
  • 一時的な増加が必要な場合は、事前の正式な合意が必要です。

統合​

エンドポイント​

環境ベースURLアクセス備考
ステージングhttps://api.id.uat.unico.appオープンテスト必須
本番https://api.id.unico.app承認されたホモロゲーション後のみ厳格なTPS管理が必要

必須ヘッダー​

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

ペイロードパラメータ​

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}
フィールド型必須説明
subjectobjectはいユーザー識別データ。
subject.duiTypeintegerはいドキュメントタイプ識別子。以下のduiTypeの値を参照してください。
subject.codestringはいCPFまたはその他のユーザー識別子。
subject.namestringはいユーザーのフルネーム。
subject.emailstringいいえユーザーのメールアドレス。
subject.phonestringいいえユーザーの電話番号。
subject.birthDatestringいいえユーザーの生年月日（DD/MM/YYYY）。
subject.genderstringいいえユーザーの性別（MまたはF）。
useCasestringはいユースケース名（「Reprocessamento」または「Importação de base」）。
subsidiaryIdstringいいえ子会社UUID（Unicoから提供）。
imageBase64base64はいbase64に変換されたユーザーのセルフィー画像。
documentobjectいいえプロセスに関連するドキュメントデータ。
document.purposestringいいえドキュメントの目的（例: "Reprocessamento"）。
document.documentIdstringいいえドキュメント識別子。
document.filesarrayいいえドキュメント画像ファイルのリスト。
document.files[].database64いいえbase64に変換されたドキュメント画像。
document.files[].faceDocumentMatchbooleanいいえドキュメント内の顔が送信されたセルフィーと一致するかどうかを示します。
duiType の値
値説明
0未指定
1ブラジル — CPF
2メキシコ — CURP
3Unico内部識別子
4アメリカ合衆国 — SSN
5ブラジル — パスポート
6アルゼンチン — パスポート
7アルゼンチン — DNI
8ナイジェリア — NIN
9チリ — RUN
10エクアドル — NI
11アメリカ合衆国 — パスポート
12グアテマラ — CUI
13ウルグアイ — CI
15メールアドレス
16インドネシア — NIK
17電話番号
18アメリカ合衆国 — 運転免許証

重要な注意事項​

  • セルフィーは適切な品質と照明でICAO規格に準拠している必要があります。
  • セルフィーはbase64形式である必要があります。
  • TPS管理なしの大量送信は避けてください。レート制限がトリガーされる可能性があります（以下のエラーハンドリングを参照）。
  • 常にステージング環境でデータと統合を先にテストしてください。

レスポンス​

成功 — 200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}
フィールド型説明
idstringプロセス識別子。将来のクエリや、後で1:1 バリデーションを実装する場合に備えて保存してください。
statusintegerトランザクションステータス。
unicoId.resultstring本人確認ケイパビリティのレスポンス。
identityFraudsters.resultstring不正リスク分類ケイパビリティのレスポンス。

画像処理エラー

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
}

一般的なエラー

4xx範囲のコードは、提供されたデータのバリデーションエラーを示します。5xx範囲のコードは、サーバー側の障害を示します。

HTTPコードエラータイプ原因の可能性推奨アクション
400Bad Request無効なペイロード構造と内容を検証してください。
401Unauthorized期限切れまたは無効なトークントークンを再生成してください。
403Forbidden不正なAPIキーまたは権限不足認証情報を確認してください。
429Too Many Requestsリクエストレート超過待機してTPS制限を遵守してください。
500+Internal Server Error内部障害数秒後にリトライしてください。持続する場合はチケットを起票してください。

エラーハンドリング​

  • **レート制限（HTTP 429）**は慎重に監視する必要があります。リクエストの過負荷はパイプラインをブロックする可能性があります。
  • Unicoと合意したTPSを常に遵守してください（TPS合意を参照）。
  • 持続的な障害（5xx）の場合は、リトライ/バックオフ制御で再処理してください。
最終更新 に