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

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

スコープ

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

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

前提条件

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

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

ケイパビリティ	説明
本人確認	送信されたセルフィーが識別子の実際の所有者のものであるかを確認します。
不正リスク分類	その顔に関連する不正行為の履歴を確認します。
Facematch	書類の写真が送信されたセルフィーと一致するかを確認します。
CPF Match Brazil 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"
      }
    ]
  }
}

フィールド	型	必須	説明
`subject`	object	はい	ユーザー識別データ。
`subject.duiType`	integer	はい	ドキュメントタイプ識別子。以下の`duiType`の値を参照してください。
`subject.code`	string	はい	CPFまたはその他のユーザー識別子。
`subject.name`	string	はい	ユーザーのフルネーム。
`subject.email`	string	いいえ	ユーザーのメールアドレス。
`subject.phone`	string	いいえ	ユーザーの電話番号。
`subject.birthDate`	string	いいえ	ユーザーの生年月日（`DD/MM/YYYY`）。
`subject.gender`	string	いいえ	ユーザーの性別（`M`または`F`）。
`useCase`	string	はい	ユースケース名（「Reprocessamento」または「Importação de base」）。
`subsidiaryId`	string	いいえ	子会社UUID（Unicoから提供）。
`imageBase64`	base64	はい	base64に変換されたユーザーのセルフィー画像。
`document`	object	いいえ	プロセスに関連するドキュメントデータ。
`document.purpose`	string	いいえ	ドキュメントの目的（例: `"Reprocessamento"`）。
`document.documentId`	string	いいえ	ドキュメント識別子。
`document.files`	array	いいえ	ドキュメント画像ファイルのリスト。
`document.files[].data`	base64	いいえ	base64に変換されたドキュメント画像。
`document.files[].faceDocumentMatch`	boolean	いいえ	ドキュメント内の顔が送信されたセルフィーと一致するかどうかを示します。

duiType の値

国	コード	説明
BR	1	ブラジル CPF
BR	5	ブラジルパスポート
MX	2	メキシコ CURP
AR	6	アルゼンチンパスポート
AR	7	アルゼンチン DNI
US	4	アメリカ合衆国 SSN
US	11	アメリカ合衆国パスポート
US	18	アメリカ合衆国運転免許証
ID	16	インドネシア NIK
NG	8	ナイジェリア NIN
CL	9	チリ RUN
EC	10	エクアドル NI
GT	12	グアテマラ CUI
UY	13	ウルグアイ CI
ZZ	15	メールアドレス
ZZ	17	電話番号
MX	25	メキシコ RFC（個人）
CO	26	コロンビア NIT
PE	27	ペルー RUC
CA	28	カナダ SIN
DK	29	デンマーク CPR
GB	30	英国国民保険番号（NINO）
PL	31	ポーランド PESEL
SE	32	スウェーデン個人番号（PNR）
AT	34	オーストリア納税者番号（STNR）
FI	35	フィンランド個人識別番号（HETU）
—	0	未指定
—	3	Unico 内部識別子

重要な注意事項

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

レスポンス

成功 — 200 OK

書類なし
書類あり（Facematch）

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}

フィールド	型	説明
`id`	string	プロセス識別子。将来のクエリや、後で1:1 バリデーションを実装する場合に備えて保存してください。
`status`	integer	トランザクションステータス。
`unicoId.result`	string	本人確認ケイパビリティのレスポンス。
`identityFraudsters.result`	string	不正リスク分類ケイパビリティのレスポンス。

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "identityFraudsters": {
    "result": "yes"
  }
}

フィールド	型	説明
`id`	string	プロセス識別子。将来のクエリや、後で1:1 バリデーションを実装する場合に備えて保存してください。
`status`	integer	トランザクションステータス。
`score`	number	Facematchスコア。
`unicoId.result`	string	本人確認ケイパビリティのレスポンス。
`faceDocumentMatch.faceMatch`	boolean	書類の写真が送信されたセルフィーと一致するかどうか。
`identityFraudsters.result`	string	不正リスク分類ケイパビリティのレスポンス。

画像処理エラー

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

一般的なエラー

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

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

エラーハンドリング

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

スコープ​

前提条件​

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

セルフィーの要件​

書類の要件​

TPS合意​

統合​

エンドポイント​

必須ヘッダー​

ペイロードパラメータ​

重要な注意事項​

レスポンス​

エラーハンドリング​