プロセスの作成

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

オンボーディング - ユーザーの顔をUnicoの本人認証ベースと比較して本人確認を行います（subject.duiType + subject.code が必須）。
トランザクション - 以前のプロセスから同一人物であることを顔対顔の比較で検証します（referenceProcessId またはセルフィー/プロセスIDを含む references 配列が必須）。
Cardholder Verification - セルフィーの撮影を伴わずに、カードがその宣言された所有者に属することを確認します（subject.code + card が必須）。オプションで、事前に検証済みのプロセスを referenceProcessId 経由で再利用し、再利用ゲートをトリガーできます。指定しない場合、レスポンスは標準の unsure 結果にデフォルトします。Cardholder Verification ケイパビリティを参照してください。

アクティブな製品は、リクエストヘッダーで送信される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`

ボディパラメータ

オンボーディング
トランザクション
Cardholder Verification

フィールド	型	必須	説明
`subject.duiType`	integer	はい	ドキュメントタイプ識別子。以下の`duiType` の値を参照してください。
`subject.code`	string	はい	`subject.duiType` で定義された識別子の値。ドットやダッシュは使用しないでください。
`subject.name`	string	いいえ	フルネーム。
`subject.gender`	string	いいえ	`M` または `F`。
`subject.birthDate`	string (ISO 8601)	いいえ	生年月日（`YYYY-MM-DD`）。
`subject.email`	string	いいえ	メールアドレス。
`subject.phone`	string	いいえ	E.164形式の電話番号。
`subject.clientReference`	string	条件付き	あなたのシステムにおけるユーザーの一意の識別子。マルチアカウントケイパビリティに必須です。自社ベース内で一意、最大 256 文字、スペース不可。
`useCase`	string	いいえ	操作コンテキスト、例: `Onboarding`。
`subsidiaryId`	string	いいえ	ブランチID — 複数のブランチが存在する場合にのみ必要です。
`imageBase64`	string	はい	フロントエンドでキャプチャしたセルフィー（base64形式）。

フィールド	型	必須	説明
`references`	array	条件付き	1:1 バリデーションフローのリファレンス入力。各アイテムには `referenceType`（`REFERENCE_TYPE_IMAGE_BASE64` または `REFERENCE_TYPE_PROCESS_ID`）と `referenceContent`（base64エンコード画像またはプロセスUUID）が含まれます。
`referenceProcessId`	string	条件付き	非推奨。代わりに `references` を使用してください。比較対象のリファレンスオンボーディングプロセスのID。リファレンスがby-Unicoプロセスの場合は、`authenticationInfo.authenticationId` を使用してください。
`imageBase64`	string	はい	フロントエンドでキャプチャしたセルフィー（base64形式）。
`subject`	object	いいえ	ユーザー情報コンテナ。
`subject.duiType`	string	いいえ	識別子の種類。使用可能な値: `DUI_TYPE_BR_CPF`、`DUI_TYPE_MX_CURP`、`DUI_TYPE_US_SSN`、`DUI_TYPE_NG_NIN`、`DUI_TYPE_AR_DNI`、`DUI_TYPE_ID_NIK`。
`subject.code`	string	いいえ	`subject.duiType` で定義された識別子の値。ドットやダッシュは使用しないでください。
`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レスポンスで同期的に返されます。

フィールド	型	必須	説明
`subject.duiType`	integer	はい	ドキュメントタイプ識別子。以下の`duiType` の値を参照してください。現在は `DUI_TYPE_BR_CPF` のみです。
`subject.code`	string	はい	検証対象のカード所有者のCPF。ドットやダッシュは使用しないでください。
`card.bin`	string	条件付き	カードの先頭6桁または8桁（BIN）。`card.last4` と併せて必須です。
`card.last4`	string	条件付き	カードの末尾4桁。`card.bin` と併せて必須です。
`card.name`	string	いいえ	カードに印字されているカード所有者の氏名。
`referenceProcessId`	string (UUID)	いいえ	再利用する、事前に検証済みのプロセスのID — 同一CPFに対して承認済みの本人確認またはライブネス結果を持つものである必要があります。このケイパビリティの現在のバージョンは再利用ベースです。このフィールドがない場合、ゲートは一度もトリガーされず、レスポンスは標準の `unsure` 結果にデフォルトします — リクエスト自体が失敗することはありません。
`useCase`	string	いいえ	操作コンテキスト、例: `CardholderVerification`。
`subsidiaryId`	string	いいえ	ブランチID — 複数のブランチが存在する場合にのみ必要です。

情報

この製品では imageBase64 は送信されません — Cardholder Verificationはセルフィー撮影のステップなしに、完全にバックエンドで実行されます。

duiType の値

国	コード	説明
BR	1	ブラジル CPF
MX	2	メキシコ CURP
US	4	アメリカ合衆国 SSN
BR	5	ブラジルパスポート
AR	6	アルゼンチンパスポート
AR	7	アルゼンチン DNI
NG	8	ナイジェリア NIN
CL	9	チリ RUN
EC	10	エクアドル NI
US	11	アメリカ合衆国パスポート
GT	12	グアテマラ CUI
UY	13	ウルグアイ CI
BR	14	ブラジル CNPJ
ZZ	15	メールアドレス
ID	16	インドネシア NIK
ZZ	17	電話番号
US	18	アメリカ合衆国運転免許証
NG	20	ナイジェリア銀行認証番号（BVN）
US	21	アメリカ合衆国パスポートカード
US	22	アメリカ合衆国ポリカーボネートパスポート
US	23	アメリカ合衆国 IDカード
TR	24	トルコ国民識別番号（TCKN）
MX	25	メキシコ RFC（個人）
CO	26	コロンビア NIT
PE	27	ペルー RUC
CA	28	カナダ SIN
DK	29	デンマーク CPR
GB	30	英国国民保険番号（NINO）
PL	31	ポーランド PESEL
SE	32	スウェーデン個人番号（PNR）
CH	33	スイス AHV/AVS番号
AT	34	オーストリア納税者番号（STNR）
FI	35	フィンランド個人識別番号（HETU）
BE	36	ベルギー国民番号（NN）
IT	37	イタリア税務番号（CF）
SE	38	スウェーデン調整番号（Samordningsnummer）
NO	39	ノルウェー国民識別番号（Fødselsnummer）
PE	40	ペルー DNI
DE	41	ドイツ税務識別番号（IdNr）
NL	42	オランダ市民サービス番号（BSN）
NG	43	ナイジェリア BVNトークン（ハッシュ化）
NG	44	ナイジェリア NINトークン（ハッシュ化）
PT	45	ポルトガル納税者番号（NIF）
FR	46	フランス税務参照番号（SPI）
IE	47	アイルランド個人公共サービス番号（PPSN）
LU	48	ルクセンブルク国民識別番号（Matricule）
AR	49	アルゼンチン運転免許証（Licencia Nacional de Conducir）
ES	50	スペイン外国人識別番号（NIE）
ES	51	スペイン国民身分証明書（DNI）
CL	52	チリパスポート
CO	53	コロンビアパスポート
PE	54	ペルーパスポート
CO	55	コロンビア運転免許証（Licencia de Conducción）
CO	56	コロンビア市民証（Cédula de Ciudadanía）
CL	57	チリ運転免許証（Licencia de Conducir）
MX	58	メキシコ運転免許証（Licencia de Conducir）
—	0	未指定
—	3	Unico 内部識別子

画像要件

最小解像度: 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..."
  }'

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: {
      duiType: 1,
      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 -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

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({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

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"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

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: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

レスポンス

オンボーディング
トランザクション
Cardholder Verification

200 OK

このコントラクトは単一で、idCloud.result フィールドが使用されたケイパビリティの統合された判定結果を保持します。

Unicoは、実行されたケイパビリティの結果を単一の idCloud.result に統合します。個々の結果をオーケストレーションする必要はなく、フローの次のステップをすぐに判断できます。

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

フィールド	型	説明
`id`	string (UUID)	プロセス識別子。再クエリにはプロセスの取得で使用します。
`status`	integer	`1`（処理中）、`3`（成功で完了）、`5`（エラー）。

可能な結果の値

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

返される値は、APIKeyに設定されたレシピによって異なります。各レシピが返す結果値については、フローを参照してください。

ブラジルのクライアントはケイパビリティ単位のレスポンスを受け取る場合があります

全体のレスポンス構造は変わらず、単一の結果がデフォルトです。

ブラジルの統合はケイパビリティごとに開かれた結果を受け取る場合があります。APIKeyで有効化された各ケイパビリティがレスポンスに独自のブロックを追加し、無効なケイパビリティのフィールドは省略されます。

{
  "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のプロジェクトマネージャーにお問い合わせください。

フィールド	型	説明
`unicoId.result`	string	`yes`、`no`、`inconclusive` - 本人確認を参照。
`riskLevel.result`	string	`approved`、`reproved`、`risk-critical`、`risk-high`、`inconclusive` — 下記の使用可能な値または不正リスク分類を参照。
`idFace.result`	string	`FOUND` — 顔識別子を参照。
`idFace.personId`	string	顔の安定した不透明な識別子。`idFace.result = FOUND` とともに返されます。画像内で顔を識別できない場合、リクエストは `idFace` ブロックを返す代わりにエラー `20532` で失敗します。
`identityFraudsters.result`	string	非推奨。代わりに `riskLevel` を使用してください。現在インテグレーションを進行中のクライアントは、プロジェクトチームと移行を調整しながら引き続き使用できます。
`government.serpro`	integer	Serpro類似度スコア（0-100、-1、-2）。ブラジルのみで利用可能。Serpro類似度返却を参照。
`liveness`	integer	`1`（合格）、`2`（不合格） - ライブネスを参照。

riskLevel.result — 使用可能な値

値	意味
`approved`	本人の顔であり、不正に関連する証拠は見つかりませんでした。
`reproved`	複数の不正指標が検出されたため、拒否を推奨します。
`risk-critical`	拒否を推奨しますが、最終的な判断はお客様の裁量に委ねられます。クリティカルリスクは、強力な不正証拠が少なくとも2つ見つかったことを示します。
`risk-high`	拒否も推奨されますが、判断はお客様に委ねられます。ハイリスクは、強力な不正証拠が少なくとも1つ見つかったことを示します。
`inconclusive`	強力な不正証拠は見つかりませんでした。そのため、関連するリスクが存在するかどうかを判断することはできません。

情報

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

200 OK

このコントラクトは単一で、idCloud.result フィールドが使用されたケイパビリティの統合された判定結果を保持します。

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

フィールド	型	説明
`id`	string (UUID)	プロセス識別子。
`status`	integer	`3`（成功で完了）、`5`（エラー）。すべての可能な値については、プロセスの取得を参照してください。

可能な結果の値

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

返される値は、APIKeyに設定されたレシピによって異なります。各レシピが返す結果値については、フローを参照してください。

ブラジルのクライアントはケイパビリティ単位のレスポンスを受け取る場合があります

全体のレスポンス構造は変わらず、単一の結果がデフォルトです。

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

フィールド	型	説明
`biometryToken.result`	boolean	送信された顔がリファレンスプロセスと一致する場合は `true`、それ以外は `false`。
`liveness`	integer	`1`（合格）、`2`（不合格） - ライブネスを参照。

200 OK

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

フィールド	型	説明
`id`	string (UUID)	プロセス識別子。
`status`	integer	`1`（処理中）、`3`（成功で完了）、`5`（エラー）。すべての可能な値については、プロセスの取得を参照してください。
`cardholderVerification.result`	string	`approved` — CPFとカードが同一人物に属していることを示します。`unsure` — 再利用の条件が満たされなかった場合、または検証自体が判定不能だった場合です。`status` が `3` になるまでは存在しません。Cardholder Verificationを参照してください。

エラーコード

400 Bad Request
403 Forbidden
409 Conflict
429 Too Many Requests
500 Internal Server Error

コード	メッセージ	説明
`40221`	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	再利用フロー（`referenceProcessId`/`bioTokenId`、画像なし）は、このAPIキーでプロセスの再利用が有効になっていないため拒否されました。
`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.	アップロードされた画像の解像度が低すぎます。
`20532`	No face detected in image.	送信された画像内に顔を検出できませんでした。
`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` も送信されていません。Cardholder Verificationには適用されません — その `referenceProcessId` は必須として検証されることはなく、再利用の条件が満たされない場合は `unsure` が返されます。
`20533`	The card field is missing.	Cardholder Verification: `card` オブジェクトが提供されていません。
`20534`	The card.bin field is missing.	Cardholder Verification: `card.bin` が提供されていません。
`20535`	The card.last4 field is missing.	Cardholder Verification: `card.last4` が提供されていません。
`20536`	The card data is invalid.	Cardholder Verification: カードデータが無効として拒否されました。
`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` のメールフォーマットが無効です。
`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ではありません。

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

コード	メッセージ	説明
`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が無効または存在しません。

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

コード	メッセージ	説明
`99999`	Internal failure! Try again later	内部エラーが発生した場合。

次のステップ

オンボーディングプロセスの結果をクエリするには、プロセスの取得を参照してください。
すべてのレシピの組み合わせとその可能な結果値を確認するには、フローを参照してください。
ドキュメントおよび年齢確認の操作については、このセクションのそれぞれのページを参照してください。

エンドポイント​

リクエスト​

例​

レスポンス​

エラーコード​

次のステップ​

エンドポイント

リクエスト

例

レスポンス

エラーコード

次のステップ