年齢確認

完全なインテグレーションフローについては、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

レート制限に達しました。Retry-After レスポンスヘッダーに示された間隔の後に再試行してください。レート制限を参照してください。

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 のフォーマットが無効です（国際電話番号 + 市外局番 + 番号、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.	サーバー側の処理エラーです。

次のステップ

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