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

プロセスの作成

このエンドポイントは、同じパスを共有しながらボディパラメータ、機能、レスポンスフィールドが異なる2つのユースケースを処理します:

  • オンボーディング - ユーザーの顔をUnicoの本人認証ベースと比較して本人確認を行います（subject.duiType + subject.code が必須）。
  • トランザクション - 以前のプロセスから同一人物であることを顔対顔の比較で検証します（referenceProcessId または セルフィー/プロセスIDを含む references 配列が必須）。

アクティブなユースケースは、リクエストヘッダーで送信されるAPIKEYによって決定されます。

完全なインテグレーションフローについては、API概要を参照してください。

エンドポイント​

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

リクエスト​

ヘッダー
ヘッダー値
AuthorizationBearer <access_token>（認証を参照）
APIKEYプロビジョニング済みAPIキー - アクティブなユースケースと有効な機能を定義します。
Content-Typeapplication/json
ボディパラメータ
フィールド型必須説明
subject.duiTypeintegerはいドキュメントタイプ識別子。以下のduiType の値を参照してください。
subject.codestringはいsubject.duiType で定義された識別子の値。ドットやダッシュは使用しないでください。
subject.namestringいいえフルネーム。
subject.genderstringいいえM または F。
subject.birthDatestring (ISO 8601)いいえ生年月日（YYYY-MM-DD）。
subject.emailstringいいえメールアドレス。
subject.phonestringいいえE.164形式の電話番号。
useCasestringいいえ操作コンテキスト、例: Onboarding。
subsidiaryIdstringいいえブランチID — 複数のブランチが存在する場合にのみ必要です。
imageBase64stringはいフロントエンドでキャプチャしたセルフィー（base64形式）。
duiType の値
国コード説明
BR1ブラジル CPF
BR5ブラジル パスポート
MX2メキシコ CURP
AR6アルゼンチン パスポート
AR7アルゼンチン DNI
US4アメリカ合衆国 SSN
US11アメリカ合衆国 パスポート
US18アメリカ合衆国 運転免許証
ID16インドネシア NIK
NG8ナイジェリア NIN
CL9チリ RUN
EC10エクアドル NI
GT12グアテマラ CUI
UY13ウルグアイ CI
ZZ15メールアドレス
ZZ17電話番号
MX25メキシコ RFC（個人）
CO26コロンビア NIT
PE27ペルー RUC
CA28カナダ SIN
DK29デンマーク CPR
GB30英国 国民保険番号（NINO）
PL31ポーランド PESEL
SE32スウェーデン 個人番号（PNR）
AT34オーストリア 納税者番号（STNR）
FI35フィンランド 個人識別番号（HETU）
—0未指定
—3Unico 内部識別子
画像要件
  • 最小解像度: 640 × 480（HD標準）
  • 最大ファイルサイズ: 800 KB（JPEG92圧縮推奨）
  • 受け入れ可能なフォーマット: PNG、JPEG、WebP
  • SDKからのJWTトークンは10分後に期限切れとなり、1回のみ使用可能

例​

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

レスポンス​

200 OK
{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}
レスポンスフィールドはAPIKeyによって異なります

上記の例は、すべての可能な機能フィールドを示しています。実際のレスポンスには、APIKey設定で有効になっている機能のフィールドのみが含まれます。無効な機能のフィールドは完全に省略されます。機能の有効化または調整については、Unicoのプロジェクトマネージャーにお問い合わせください。

フィールド型説明
idstring (UUID)プロセス識別子。再クエリにはプロセスの取得で使用します。
statusinteger1（処理中）、3（成功で完了）、5（エラー）。
unicoId.resultstringyes、no、inconclusive - 本人確認を参照。
riskLevel.resultstringapproved、reproved、risk-critical、risk-high、inconclusive — 下記の使用可能な値または不正リスク分類を参照。
idFace.resultstringFOUND、NOT_FOUND — 顔識別子を参照。
idFace.personIdstring顔の安定した不透明な識別子。idFace.result = FOUND の場合のみ存在します。
identityFraudsters.resultstring非推奨。 代わりに riskLevel を使用してください。現在インテグレーションを進行中のクライアントは、プロジェクトチームと移行を調整しながら引き続き使用できます。
government.serprointegerSerpro類似度スコア（0-100、-1、-2）。ブラジルのみで利用可能。Serpro類似度返却を参照。
livenessinteger1（合格）、2（不合格） - ライブネスを参照。
riskLevel.result — 使用可能な値
値意味
approved本人の顔であり、不正に関連する証拠は見つかりませんでした。
reproved複数の不正指標が検出されたため、拒否を推奨します。
risk-critical拒否を推奨しますが、最終的な判断はお客様の裁量に委ねられます。クリティカルリスクは、強力な不正証拠が少なくとも2つ見つかったことを示します。
risk-high拒否も推奨されますが、判断はお客様に委ねられます。ハイリスクは、強力な不正証拠が少なくとも1つ見つかったことを示します。
inconclusive強力な不正証拠は見つかりませんでした。そのため、関連するリスクが存在するかどうかを判断することはできません。
情報

unicoId.result = inconclusive かつリスクスコアオーケストレーションがアクティブな場合、プロセスは status: 1（処理中）を返す場合があります。最終結果を取得するには、プロセスの取得をポーリングするか、Webhookを使用してください。

400 Bad Request

ペイロードの形式が不正、画像が無効、または必須フィールドが欠落しています。以下のエラーコードを参照してください。

403 Forbidden

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

409 Conflict

指定された processId はこのテナントに既に存在します。以下のエラーコードを参照してください。

429 Too Many Requests

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

ベストプラクティス:

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

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

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

エラーコード​

コードメッセージ説明
20900O base64 informado não é válido.base64パラメータが無効です。画像でないか、インジェクションの試みの可能性があります。
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.アップロードされた画像の解像度が低すぎます。
20513The referenced process was not found.referenceProcessId が存在しないか、アクセスできなくなったプロセスを指しています。
20512The referenced process is not available for reuse.リファレンスプロセスは存在しますが、再利用できません。
20509The subject.name field is invalid.subject.name に無効な文字が含まれています。
20508The subject.gender field is invalid.subject.gender は M または F でなければなりません。
20507O parâmetro subject.code é inválido.非標準または存在しないCPF。
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.画像サイズが800 KBを超えています。JPEG92に圧縮してください。
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.base64フォーマットが無効またはサポートされていません。
20065The referenceProcessId field is invalid.referenceProcessId が有効なUUIDではありません。
20062The useCase field is invalid.useCase フィールドの値が認識されません。
20024The referenceProcessId field is missing.referenceProcessId パラメータが提供されておらず、代替として references も送信されていません。
20021The subject.phone field is invalid.subject.phone のフォーマットが無効です（IDD + 市外局番 + 番号、13文字）。
20019The subject.birthDate field is invalid.subject.birthDate がISO 8601フォーマット（YYYY-MM-DD）の範囲外です。
20009O parâmetro imagebase64 não foi informado.セルフィー画像パラメータが欠落しています。
20008The subject.email field is invalid.subject.email のメールフォーマットが無効です。
20006O parâmetro subject.name não foi informado.subject.nameパラメータが欠落しています。
20005O parâmetro subject.code não foi informado.subject.codeパラメータが欠落しています。
20004O parâmetro subject não foi informado.subjectパラメータが欠落しています。
20003The request body is missing or invalid.ペイロードがnullまたは無効です。
20002O parâmetro APIKey não foi informado.リクエストヘッダーにAPIKEYパラメータが欠落しています。
20001O parâmetro authtoken não foi informado.リクエストヘッダーにインテグレーショントークンパラメータが欠落しています。
10508The JWT with the captured face has already been used.JWTは1回のみ使用可能です。
10507The JWT with the captured face is expired.JWTが期限切れです。10分以内に送信する必要があります。
10506The imageBase64 field is not a valid JWT from SDK.imageBase64 がSDKで生成された有効なJWTではありません。

次のステップ​

  • オンボーディングプロセスの結果をクエリするには、プロセスの取得を参照してください。
  • ドキュメントおよび年齢確認の操作については、このセクションのそれぞれのページを参照してください。
最終更新 に