プロセスの作成

MarkdownChatGPTClaude

このエンドポイントは、同じパスを共有しながらボディパラメータ、機能、レスポンスフィールドが異なる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

ボディパラメータ

オンボーディング

フィールド	型	必須	説明
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_AR_DNI、DUI_TYPE_BR_CPF、DUI_TYPE_ID_NIK、DUI_TYPE_MX_CURP、DUI_TYPE_NG_NIN、DUI_TYPE_US_SSN。
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レスポンスで同期的に返されます。

Cardholder Verification

フィールド	型	必須	説明
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 の値

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

画像要件

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

圧縮リクエスト

このAPIは、標準の Content-Encoding HTTPヘッダーを使用して、圧縮されたリクエストボディを送信することをサポートしています。これはオプションであり、完全に後方互換性があります。このヘッダーを送信しないクライアントは、これまでと同様に動作し続けます。

サポートされているフォーマット

エンコーディング	Content-Encoding ヘッダー	ステータス
Gzip	gzip	✅ 推奨
Deflate	deflate	✅ サポート対象
圧縮なし	(ヘッダーなし)	✅ サポート対象（デフォルトの動作）

推奨

gzip を使用してください。言語やHTTPライブラリを問わず最も広くサポートされており、他のフォーマットに見られる実装上の曖昧さを回避できます。

圧縮は、ボディが大きいリクエスト（大規模なJSONペイロード、base64エンコードされた画像アップロード、バッチ送信など）で推奨されます。小さなリクエストの場合、圧縮のオーバーヘッドが適切なメリットをもたらさない場合があります。

圧縮されたリクエストを送信する方法

1. 選択したアルゴリズムを使用して、リクエストボディ（例: シリアライズされたJSON）を圧縮します。
2. 圧縮されたボディをバイナリバイトとしてリクエストに送信します。
3. 対応する値（gzip または deflate）を指定した Content-Encoding ヘッダーを含めます。
4. Content-Type は、転送時のエンコーディングではなく、元のコンテンツ形式（例: application/json）を示すままにしてください。

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

ヒント

Pythonの例では、json=ではなくdata=パラメータを使用してください。json=パラメータはペイロードを自動的にシリアライズしますが、圧縮はしません。

deflate を使う場合: 上記の流れは同じです。変わるのは圧縮処理と Content-Encoding の値だけです。

言語	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate（qpdf に含まれる）を使い、その後 -H "Content-Encoding: deflate" を指定
Python	gzip.compress(data) の代わりに zlib.compress(data) を使用
.NET (C#)	GZipStream の代わりに System.IO.Compression.DeflateStream を使用

deflate は実運用では曖昧

HTTP の deflate コンテンツエンコーディングは zlib ストリーム（RFC 1950）として規定されていますが、一部のクライアントやサーバーは歴史的に raw DEFLATE（RFC 1951）を送信・期待する場合があります。この API は標準の zlib でラップされたストリームを想定しています — これは Python の zlib.compress() や .NET の DeflateStream がデフォルトで生成する出力と同じものです。判断に迷う場合は、こうした曖昧さのない gzip を優先してください。

エラー時の挙動

Content-Encoding にサポートされていない値が指定されている場合、またはボディが破損しているか宣言されたエンコーディングに対して無効な場合、APIは、リクエストボディの解凍に失敗したことを示すメッセージとともに 400 Bad Request を返します。

FAQ

圧縮を使用したくない場合、何か変更する必要がありますか？ いいえ。Content-Encoding のサポートは追加的なものです — このヘッダーがないリクエストは、これまでと同様に正常に処理されます。

これはAPIレスポンスに影響しますか？ いいえ。この機能は、クライアントが送信するボディ（リクエスト）のみに関係します。レスポンスの圧縮（APIが返すもの）は、Accept-Encoding ヘッダーによって別途制御されます。

どのフォーマットを選択すべきですか？ 特定の環境上の制約で他のフォーマットが必要な場合を除き、gzip を使用してください。

例

オンボーディング - 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": {
      "duiType": 1,
      "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: {
      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

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..."
  }'

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

const result = await res.json();

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

Cardholder Verification - 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: {
      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();

レスポンス

オンボーディング

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	意味	推奨アクション
approved	実在の人物であり、本人確認済み。	フローを継続します。
denied	本人確認が完了しなかった、ライブネスチェックに失敗した、または重大なリスクが検出された。	フローを終了するか、代替フローにリダイレクトします。
critical-risk	重大なリスクレベルが検出された。	フローを終了するか、手動レビューに振り分けます。
high-risk	高いリスクレベルが検出された。	手動レビューまたは代替フローに振り分けます。
retry	評価に十分なキャプチャまたはスコアが得られなかった。	ユーザーに新しいキャプチャを依頼します。
inconclusive	判定に十分な証拠がない。	手動レビューまたは代替フローに振り分けます。

返される値は、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を使用してください。

メキシコのクライアントはRENAPO検証ブロックを受け取る場合があります

レスポンスの構造は同じままで、idGov ブロックが追加されます。

RENAPO検証が有効なメキシコの統合は、ユーザーのCURPについてRENAPOが保有するレコードを含む追加の idGov ブロックを受け取ります。これは本人確認の結果とは別個の回答です。

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

フィールド	型	説明
idGov	object	CURPに対するRENAPOのレコード。ケイパビリティが有効でない場合は存在しません。RENAPOが応答しなかった場合は {}。メキシコのみで利用可能。RENAPO検証を参照してください。

トランザクション

200 OK

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

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

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

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

可能な結果の値

idCloud.result	意味	推奨アクション
approved	実在の人物であり、本人確認済み。	フローを継続します。
denied	本人確認が完了しなかった、ライブネスチェックに失敗した、または重大なリスクが検出された。	フローを終了するか、代替フローにリダイレクトします。
critical-risk	重大なリスクレベルが検出された。	フローを終了するか、手動レビューに振り分けます。
high-risk	高いリスクレベルが検出された。	手動レビューまたは代替フローに振り分けます。
retry	評価に十分なキャプチャまたはスコアが得られなかった。	ユーザーに新しいキャプチャを依頼します。
inconclusive	判定に十分な証拠がない。	手動レビューまたは代替フローに振り分けます。

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

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

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

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

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

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

Cardholder Verification

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

コード	メッセージ	説明
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ではありません。

403 Forbidden

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が無効または存在しません。

409 Conflict

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

429 Too Many Requests

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

ベストプラクティス:

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

警告

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

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

500 Internal Server Error

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

次のステップ

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