年齢確認

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

エンドポイント

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

リクエスト

ヘッダー

ヘッダー	値
Authorization	Bearer <access_token>（認証を参照）
APIKEY	年齢確認機能が有効なプロビジョニング済みAPIキー。
Content-Type	application/json

ボディパラメータ

フィールド	型	必須	説明
subject	object	はい	ユーザー情報コンテナ。
subject.code	string	条件付き	CPF（BR）またはCURP（MX）、フォーマットなし。フローにライブネスまたは本人確認が含まれる場合に必須（年齢確認機能を参照）。年齢確認のみのフローでは不要です。
subject.name	string	いいえ	ユーザーのフルネーム。
subject.gender	string	いいえ	男性は M、女性は F。
subject.birthDate	string (ISO 8601)	いいえ	生年月日（YYYY-MM-DD）。
subject.email	string	いいえ	ユーザーのメールアドレス。
subject.phone	string	いいえ	電話番号: 国番号 + 市外局番 + 番号、区切りなし（例: 5519725570707）。
useCase	string	いいえ	操作のユースケース識別子。
subsidiaryId	string	いいえ	支店ID - 複数の支店が存在する場合のみ必須。
imageBase64	string	はい	暗号化されたSDK出力またはbase64画像（PNG、JPEG、WebP）。

画像要件

• 最小解像度: 640 × 480（HD標準）
• 最大ファイルサイズ: 800 KB（JPEG92圧縮推奨）
• SDKからのJWTトークンは10分後に期限切れとなり、1回のみ使用可能

例

cURL

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": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      code: '12345678909',
      name: 'Luke Skywalker',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

レスポンス

200 OK

返されるレスポンスフィールドは、APIKEYで有効化されている機能によって異なります。

年齢確認のみ（ライブネスなし、本人確認なし）:

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

年齢確認 + ライブネス + 本人確認:

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "idAge": { "result": "yes" },
  "liveness": 1
}

フィールド	型	説明
id	string (UUID)	プロセス識別子。再クエリにはプロセスの取得で使用します。
status	integer	3（成功で完了）、5（エラー）。ビジネス判断には status = 3 のみを使用してください。すべての可能な値については、プロセスの取得を参照してください。
idAge.result	string	yes、no、inconclusive - 年齢確認結果。すべてのレスポンスに存在します。
unicoId.result	string	yes、no、inconclusive - 本人確認が有効な場合のみ存在します。
liveness	integer	1（合格）、2（不合格） - ライブネスが有効な場合のみ存在します。

400 Bad Request

ペイロードの形式が不正、画像が無効、または必須フィールドが欠落しています。

403 Forbidden

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

409 Conflict

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

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

500 Internal Server Error

予期しないサーバーエラー。

エラーコード

400 Bad Request

コード	メッセージ	説明
20900	O base64 informado não é válido.	無効なbase64パラメータ。画像またはインジェクションの問題の可能性があります。
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	画像の解像度が最小閾値を下回っています。
20509	The subject.name field is invalid.	subject.name に無効な文字が含まれています。
20508	The subject.gender field is invalid.	subject.gender は M または F でなければなりません。
20507	O parâmetro subject.code é inválido.	不正な形式または存在しない識別子の値。フローにライブネスまたは本人確認が含まれる場合のみ発生します。年齢確認のみのフローでは不要です。
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	ペイロードが800 KBを超えています。JPEG92に圧縮してください。
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	サポートされていないフォーマットまたは無効なbase64プレフィックス。
20062	The useCase field is invalid.	useCase フィールドの値が認識されません。
20021	The subject.phone field is invalid.	subject.phone のフォーマットが無効です（IDD + 市外局番 + 番号、13文字）。
20019	The subject.birthDate field is invalid.	subject.birthDate がISO 8601フォーマット（YYYY-MM-DD）の範囲外です。
20009	O parâmetro imagebase64 não foi informado.	セルフィー画像パラメータが欠落しています。
20008	The subject.email field is invalid.	subject.email のメールフォーマットが無効です。
20005	O parâmetro subject.code não foi informado.	subject.code パラメータが欠落しています。フローにライブネスまたは本人確認が含まれる場合のみ発生します。年齢確認のみのフローでは不要です。
20004	O parâmetro subject não foi informado.	subjectオブジェクトが欠落しています。
20003	The request body is missing or invalid.	ペイロードがnullまたは不正な形式です。
20002	O parâmetro APIKey não foi informado.	APIKEYヘッダーが欠落しています。
20001	O parâmetro authtoken não foi informado.	認証トークンヘッダーが欠落しています。
10508	The JWT with the captured face has already been used.	JWTは1回のみ使用可能です。
10507	The JWT with the captured face is expired.	JWTが10分の有効期限を超過しています。
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 がSDKで生成された有効なJWTではありません。

403 Forbidden

コード	メッセージ	説明
30017	User does not have permission to perform this action.	不正な形式のJWTまたはこの操作を実行する権限のないユーザー。
30017	Jwt header is an invalid JSON.	アクセストークンに無効な文字が含まれています。
10502	O token informado está expirado.	期限切れのアクセストークン。
10501	O token informado é inválido.	無効な認証トークン。
10201	O AppKey informado é inválido.	欠落または存在しないAPIKEY。

409 Conflict

コード	メッセージ	説明
20073	The processID already exists.	指定された processId はこのテナントに既に存在します。

500 Internal Server Error

コード	メッセージ	説明
99999	Internal failure! Try again later.	サーバー側の処理エラー。

次のステップ

• 既存のプロセスをクエリするには、プロセスの取得を参照してください。