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

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

Markdown

このガイドでは、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規格に準拠する必要があります（明るい背景、顔が中央に位置、識別を妨げるアクセサリーなし、適切な照明）。
  • 推奨サイズ: 1080x1920（縦向き）または1920x1080（横向き）。
  • 最大サイズ: 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 の値
国コード説明
AR6アルゼンチン パスポート
AR7アルゼンチン DNI
AR49アルゼンチン 運転免許証（Licencia Nacional de Conducir）
AT34オーストリア 納税者番号（STNR）
BE36ベルギー 国民番号（NN）
BR1ブラジル CPF
BR5ブラジル パスポート
BR14ブラジル CNPJ
CA28カナダ SIN
CH33スイス AHV/AVS番号
CL9チリ RUN
CL52チリ パスポート
CL57チリ 運転免許証（Licencia de Conducir）
CO26コロンビア NIT
CO53コロンビア パスポート
CO55コロンビア 運転免許証（Licencia de Conducción）
CO56コロンビア 市民証（Cédula de Ciudadanía）
DE41ドイツ 税務識別番号（IdNr）
DK29デンマーク CPR
EC10エクアドル NI
ES50スペイン 外国人識別番号（NIE）
ES51スペイン 国民身分証明書（DNI）
FI35フィンランド 個人識別番号（HETU）
FR46フランス 税務参照番号（SPI）
GB30英国 国民保険番号（NINO）
GT12グアテマラ CUI
ID16インドネシア NIK
IE47アイルランド 個人公共サービス番号（PPSN）
IT37イタリア 税務番号（CF）
LK60スリランカ NIC
LU48ルクセンブルク 国民識別番号（Matricule）
MX2メキシコ CURP
MX25メキシコ RFC（個人）
MX58メキシコ 運転免許証（Licencia de Conducir）
NG8ナイジェリア NIN
NG20ナイジェリア 銀行認証番号（BVN）
NG43ナイジェリア BVNトークン（ハッシュ化）
NG44ナイジェリア NINトークン（ハッシュ化）
NL42オランダ 市民サービス番号（BSN）
NO39ノルウェー 国民識別番号（Fødselsnummer）
PE27ペルー RUC
PE40ペルー DNI
PE54ペルー パスポート
PL31ポーランド PESEL
PT45ポルトガル 納税者番号（NIF）
SE32スウェーデン 個人番号（PNR）
SE38スウェーデン 調整番号（Samordningsnummer）
TR24トルコ 国民識別番号（TCKN）
US4アメリカ合衆国 SSN
US11アメリカ合衆国 パスポート
US18アメリカ合衆国 運転免許証
US21アメリカ合衆国 パスポートカード
US22アメリカ合衆国 ポリカーボネートパスポート
US23アメリカ合衆国 IDカード
UY13ウルグアイ CI
ZZ15メールアドレス
ZZ17電話番号
—0未指定
—3Unico 内部識別子

重要な注意事項​

  • セルフィーは適切な品質と照明で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）の場合は、リトライ/バックオフ制御で再処理してください。
最終更新 に