ドキュメントプロセスの作成

このエンドポイントは、同じパスを共有しながらもボディパラメーターが異なる 2 つのドキュメントフローを処理します：

• 新規キャプチャ — 処理のために base64 でドキュメント画像を送信します（document.files 必須）。
• 再利用 — 以前にキャプチャされたドキュメントを参照することでキャプチャをスキップします（document.documentId 必須）。

有効なフローは、リクエストボディに document.documentId が指定されているかどうかによって決まります。

ドキュメントプロセスを作成する前に、再利用可能なドキュメントの取得を使用して、ユーザーがすでに再利用可能なドキュメントを保有しているか確認してください。

完全なインテグレーションフローについては、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	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 形式の電話番号。
document.purpose	string	はい	ビジネス目的。値: creditprocess、carpurchase、paybypaycheck、onboarding、fgts。
document.authProcessId	string	はい	このドキュメントキャプチャに紐付けられた生体認証プロセスの ID。
document.files	array	はい	base64 形式のドキュメント画像（表面および/または裏面）。
document.files[].data	string	はい	base64 形式のドキュメント画像（PNG、JPEG、WebP、最大 800 KB）。
subsidiaryId	string	いいえ	支店 ID — 複数の支店が存在する場合のみ必須。

再利用

フィールド	型	必須	説明
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 形式の電話番号。
document.purpose	string	はい	ビジネス目的。値: creditprocess、carpurchase、paybypaycheck、onboarding、fgts。
document.authProcessId	string	はい	このドキュメントに紐付けられた生体認証プロセスの ID。
document.documentId	string	はい	以前にキャプチャされたドキュメントの ID（再利用可能なドキュメントの取得から取得）。指定する場合、document.files は省略可能。
subsidiaryId	string	いいえ	支店 ID — 複数の支店が存在する場合のみ必須。

例

新規キャプチャ — 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": "DUI_TYPE_BR_CPF",
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/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: 'DUI_TYPE_BR_CPF',
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

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 '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

再利用 — 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: 'DUI_TYPE_BR_CPF',
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

レスポンス

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

フィールド	型	説明
id	string (UUID)	プロセス識別子。
status	integer	3（正常終了）、5（失敗終了）。
document.id	string	キャプチャされたドキュメントの識別子。今後の再利用のため document.documentId リクエストでこの値を使用してください。
document.type	string	識別されたドキュメントタイプ。使用可能な値: unico.moja.dictionary.br.rg.v2.Rg、unico.moja.dictionary.br.cnh.v2.Cnh、unico.moja.dictionary.br.cin.v1.Cin、unico.moja.dictionary.br.passaporte.v1.Passaporte。
document.cpfMatch	boolean	ドキュメントから抽出された識別子が subject.code と一致する場合 true。
document.faceMatch	boolean	ドキュメントの顔写真が document.authProcessId の生体認証セルフィーと一致する場合 true。
document.content	object	OCR で抽出されたフィールド。構造はドキュメントタイプによって異なります — 以下を参照。
document.fileUrls	array	ドキュメント画像ダウンロード用の一時 URL（有効期限 10 分）。

400 Bad Request

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

403 Forbidden

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

409 Conflict

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

エラーコード

400 Bad Request

コード	メッセージ	説明
99989	The document is invalid.	document オブジェクトの構造が無効です。
99988	The document is empty.	リクエストボディに document オブジェクトが欠落しています。
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 のフォーマットが無効またはサポートされていません。
20068	The document.documentId or document.files parameter must be present.	document.documentId も document.files も指定されていません。
20067	The document.purpose parameter is invalid.	document.purpose に認識されない値が含まれています。
20066	The document.authProcessId parameter is invalid.	document.authProcessId の値が無効です。
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 は一度しか使用できません。
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	内部エラーが発生しました。

次のステップ

• この呼び出しの前にドキュメントが利用可能かどうかを確認するには、再利用可能なドキュメントの取得を参照してください。
• 生体認証プロセスの作成（document.authProcessId に必要）については、プロセスの作成を参照してください。