プロセスの作成

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

• オンボーディング — Unico の本人確認データベースに対して顔を照合し、ユーザーが誰であるかを検証します（subject.code が必須）。
• トランザクション — 顔と顔を照合することで、以前のプロセスと同一人物であるかを確認します（referenceProcessId または references 配列（selfie / process id 付き）が必須）。

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

完全な統合フローについては、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.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	いいえ	E.164 形式の電話番号。
useCase	string	いいえ	オペレーションのコンテキスト（例: Onboarding）。
imageBase64	string	はい	フロントエンドでキャプチャしたセルフィー（base64 形式）。

トランザクション

フィールド	型	必須	説明
references	array	条件付き	1:1 検証フロー用の参照入力。各要素は referenceType（REFERENCE_TYPE_IMAGE_BASE64 または REFERENCE_TYPE_PROCESS_ID）および referenceContent（base64 エンコードされた画像またはプロセスの UUID）を含みます。
referenceProcessId	string	条件付き	非推奨。 代わりに references を使用してください。比較対象となる参照オンボーディングプロセスの ID。参照が Unico によるプロセスの場合は authenticationInfo.authenticationId を使用してください。
imageBase64	string	はい	フロントエンドでキャプチャしたセルフィー（base64 形式）。
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	いいえ	E.164 形式の電話番号。
useCase	string	いいえ	オペレーションのコンテキスト（例: Transactional）。
subsidiaryId	string	いいえ	支店 ID — 複数の支店が存在する場合のみ必須。

情報

このユースケースでは、不正リスク分類とのオーケストレーションはできません。結果は常に POST レスポンスで同期的に返されます。

画像要件

• 最小解像度: 640 × 480（HD 標準）
• 最大ファイルサイズ: 800 KB（JPEG92 圧縮推奨）
• 対応フォーマット: PNG、JPEG、WebP
• 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",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "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',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

トランザクション — 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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "useCase": "Transactional",
    "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({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

レスポンス

オンボーディング

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

フィールド	型	説明
id	string (UUID)	プロセス識別子。再クエリには プロセスの取得 と組み合わせて使用します。
status	integer	1（処理中）、3（正常終了）、5（エラー）。すべての可能な値については、プロセスの取得 を参照してください。
unicoId.result	string	yes、no、inconclusive — 本人確認を参照。
identityFraudsters.result	string	yes、inconclusive — 不正リスク分類を参照。
government.serpro	integer	Serpro 類似スコア（0〜100、-1、-2）。Serpro類似度返却を参照。
liveness	integer	1（合格）、2（不合格）— ライブネスを参照。

情報

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

トランザクション

200 OK

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

フィールド	型	説明
id	string (UUID)	プロセス識別子。
status	integer	3（正常終了）、5（エラー）。すべての可能な値については、プロセスの取得 を参照してください。
biometryToken.result	boolean	提出された顔が参照プロセスと一致する場合は true、それ以外は false。
liveness	integer	1（合格）、2（不合格）— ライブネスを参照。

400 Bad Request

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

403 Forbidden

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

409 Conflict

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

429 Too Many Requests

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

エラーコード

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.	アップロードされた画像の解像度が低すぎます。
20513	The referenced process was not found.	referenceProcessId が、存在しないか、すでにアクセスできないプロセスを指しています。
20512	The referenced process is not available for reuse.	参照プロセスは存在しますが、再利用できません。
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.	標準外または存在しない CPF です。
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 フォーマットが無効または非対応です。
20065	The referenceProcessId field is invalid.	referenceProcessId が有効な UUID ではありません。
20062	The useCase field is invalid.	useCase フィールドに認識されない値が含まれています。
20024	The referenceProcessId field is missing.	referenceProcessId パラメーターが指定されておらず、代替として references も送信されていません。
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 のメール形式が無効です。
20006	O parâmetro subject.name não foi informado.	subject.name パラメーターが不足しています。
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が不正またはこの操作を実行する権限を持たないユーザーです。
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	内部エラーが発生した場合。

次のステップ

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