---
title: プロセスの作成
description: POST /v1/processes — 共通フィールド、検証の上限、フローのフィールド、Human Token とインテリジェンスを含む 201 レスポンス。
canonical: https://developer.unico.io/ja/human-plugin/api-reference/create-process
locale: ja
generated_by: markdown-export
---

# プロセスの作成

プロセスを開始し、Human Token と本人のインテリジェンスを取得します。

`POST /v1/processes`

[フロー](#flows)のいずれかでプロセスを開始し、`id`、`state`、および `data` 内の結果(Human Token と本人の[インテリジェンス](/ja/human-plugin/get-started/intelligence)である `data.ndocs`)を返します。

## 呼び出す前に

- Human Plugin が稼働しており、`GET /health/ready` が `200` を返します。
- アクセスキーが、使用する[フロー](#flows)に対して有効化されています。
- 書類を送信する場合、その `type` が[属性カタログ](/ja/human-plugin/additional-resources/attribute-catalog)にあります。

<a id="flows"></a>

## フロー

`flow` フィールドで、プロセスが何を行うかを選択します。Human Plugin は次のフローを、2 つの連携モデルで実行します。

- **API Only**: バックエンドが `imageBase64` で自撮りを送信し、作成リクエストが結果を返します。
- **Human Token Journey**: 本人がキャプチャ Journey で自撮りを行い、`callbackUri` に戻ります。作成リクエストは `token` と `link` を返し、結果は[プロセスの取得](/ja/human-plugin/api-reference/get-process)で読み取ります。

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `api+humantoken` | バックエンド経由で自撮りを受け取り、一意の顔識別子である Human Token を生成します。レスポンスが最終結果です。キャプチャも 2 回目の呼び出しもありません。 | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API |
| `humantoken` | キャプチャ Journey でライブネスチェックとともに自撮りをキャプチャし、Human Token を生成します。作成リクエストは `token` と `link` を返します。キャプチャが終了したら結果を読み取ります。 | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `humantoken+revalidation` | 自撮りをキャプチャし、期待する Human Token と顔を照合します。同一人物かどうかを返します。たとえば重要な操作の前に使用します。 | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

`clientId`、`correlationId`、`credential` は、どのフローでも共通です。

## リクエスト

```json
{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}
```

### 共通フィールド

| フィールド | 必須 | 上限(バイト) | 備考 |
| --- | --- | --- | --- |
| `flow` | はい | 64 | [フロー](#flows)のいずれか |
| `clientId` | はい | 128 | クライアントを識別する、お客様側の ID。インテリジェンスは異なる値の数を集計します |
| `correlationId` | はい | 128 | このプロセスに対する、お客様側の参照。**一意**である必要があります。状態にかかわらず、別のプロセスがすでに持っている値は `409` で拒否されます |
| `credential` | はい(ただし空でも可) | | キーは必ず存在する必要があります。下記を参照 |
| `credential.type` | 書類がある場合 | | 属性カタログのコード。完全一致で、大文字と小文字を区別します |
| `credential.value` | 書類がある場合 | 64 | 書類番号 |

`flow`、`clientId`、`correlationId` は文字列で、制御文字や前後の空白を含んではいけません。無効な値は拒否され、書き換えられることはありません。

### `credential` フィールド

- **書類がある場合:** `type` と `value` だけを持つオブジェクトで、どちらも文字列として一緒に送信します。
- **書類がない場合:** `null` または `{}`。この場合でも、プロセスはインテリジェンス上でトランザクションおよびクライアントとして数えられます。
- **省略、または空文字列のオブジェクト:** `400 MISSING_CREDENTIAL_TYPE` で拒否されます。これにより、何かが処理される前にキーの綴りミスを検出できます。
- `credential` 内のその他のキーは拒否されます。

### フローのフィールド

各フローが共通フィールドに追加するもの:

| フィールド | フロー | 必須 | 値 |
| --- | --- | --- | --- |
| `imageBase64` | `api+humantoken` | はい | base64 形式の自撮り。PNG、JPEG、WebP のいずれかで、最大 800 KB |
| `callbackUri` | `humantoken`、`humantoken+revalidation` | はい | キャプチャ終了時に本人が戻る先。お客様のページ、またはアプリの URL スキーム |
| `references` | `humantoken+revalidation` | はい | 上の例のように、期待する Human Token を持つ 1 件の項目 |

Human Plugin はこれらのフィールドを保存しません。また、綴りを誤った任意フィールドは、エラーなしに無視されることがあります。

`api+humantoken` では、正面から明るい環境で撮影した、顔が 1 つだけ写っている自撮りを使用してください。画像でない値は拒否され、プロセスは失敗として保存されます。[フローによる拒否](#flow-refusals)を参照してください。

`humantoken+revalidation` では、結果に `humanToken` の代わりに `humanTokenMatch` が含まれます。

- `"true"`: 同一人物です。プロセスはその人物のものとして数えられ、`ndocs` はその人物を表します。
- それ以外、またはライブでないキャプチャ: 確認できません。プロセスは誰のものとしても数えられず、`ndocs` もありません。

どちらの場合も `PROCESS_STATE_FINISHED` が返されます。`humanTokenMatch` を読み取ってください。[プロセスの取得](/ja/human-plugin/api-reference/get-process#finished-and-failed-processes)を参照してください。

`clientReference` など、Human Plugin が予約している名前は、`400 INVALID_REQUEST` で拒否されます。`client_id`、`correlation_id`、`Flow` など、Human Plugin 自身のフィールドの別の綴りも同様です。読み取られるのは、`flow`、`clientId`、`correlationId`、`credential` だけで、綴りも正確にこのとおりである必要があります。

### ボディのルール

- JSON オブジェクト 1 つで、最大 **2 MiB**(base64 形式の自撮り 1 枚が収まる程度)です。これより大きいボディは `400 REQUEST_TOO_LARGE` で拒否されます。
- JSON オブジェクトの後ろに何も続けてはいけません。

## レスポンス

`201 Created`。`Location: /v1/processes/<id>` が付きます。

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `id` は Human Plugin の UUID です。受理されたリクエストごとに新しいものが作成されます。
- `state` はローカルのステータスです。[ライフサイクル](/ja/human-plugin/api-reference/process-lifecycle)を参照してください。
- `humantoken` と `humantoken+revalidation` は、`token` と `link` を伴う `PROCESS_STATE_CREATED` を返します。これらは**1 回だけ**返され、保存されることはありません。必ず保管してください。[Human Token Journey](/ja/human-plugin/integrations/human-token-journey)と、お使いのプラットフォーム向けのキャプチャガイドを参照してください。
- `data.ndocs` は本人のインテリジェンスです。存在しない場合もあります。[インテリジェンス](/ja/human-plugin/get-started/intelligence)を参照してください。

<a id="result"></a>

### `data` 内の結果

完了したプロセスの `data` には、次のフィールドが含まれます。Journey フローでは、キャプチャ後に[プロセスを読み取る](/ja/human-plugin/api-reference/get-process)と、これらが返されます。

| フィールド | 条件 | 値 |
| --- | --- | --- |
| `humanToken` | `api+humantoken`、`humantoken` | 本人が誰であるか。`value` は Human Token で、生成された場合は `status` が `validated` になります |
| `humanTokenMatch` | `humantoken+revalidation` | `references` の Human Token と同一人物の場合は `"true"` |
| `liveness` | Journey フローなど、ライブネスを確認するフロー | キャプチャが生身の人物によるものであれば `value` は `live`、そうでなければ `not_live`。チェックが実行された場合、`status` は `validated` になります |
| `ndocs` | 本人のインテリジェンスがある場合 | 本人の[インテリジェンス](/ja/human-plugin/get-started/intelligence) |

Journey の結果は次のようになります。

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}
```

結果を信頼する前に `liveness` を確認してください。`not_live` の場合は、キャプチャが失敗したものとして扱い、本人にもう一度試してもらってください。`not_live` のプロセスは、誰のインテリジェンスにも数えられません。

## エラー

| ステータス | `message` | 意味 |
| --- | --- | --- |
| 400 | `INVALID_REQUEST`, `REQUEST_TOO_LARGE` | JSON オブジェクト 1 つではない、予約フィールド、型の誤り、または 2 MiB を超えるボディ |
| 400 | `MISSING_<FIELD>`, `INVALID_<FIELD>` | 必須フィールドがない、または形式が不正です(例: `MISSING_CLIENT_ID`) |
| 401 | 空(`""`) | Unico がアクセスキーを拒否しました。キーが未指定、誤り、または無効になっています。プロセスは失敗として保存されます。`HUMAN_API_ACCESS_KEY` を確認してください |
| 409 | `CORRELATION_ID_ALREADY_USED` | 別のプロセスがすでにその `correlationId` を使用しています。何も保存・送信されません |
| 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` がカタログにありません。何も保存・送信されません |
| 4xx | フローの `message` | フローがリクエストを拒否しました(例: 無効な画像)。[フローによる拒否](#flow-refusals)を参照してください |
| 502 | `UPSTREAM_UNAVAILABLE` | プロセスを時間内に確認できませんでした |
| 503 | `DATABASE_UNAVAILABLE` | データベースで障害が発生しました。何も処理されていません |
| 500 | `INTERNAL` | 予期しないエラー |

<a id="flow-refusals"></a>

### フローによる拒否

フローがリクエストを拒否した場合、作成リクエストは `4xx` を返し、理由は通常の[エンベロープ](/ja/human-plugin/api-reference/errors-and-retries)の `message` に入ります。よくあるものは次のとおりです。

| `message` | 原因 |
| --- | --- |
| `invalid flow` | `flow` が、お客様のアカウントで有効なフローではありません |
| `INVALID_IMAGE` (`400`) | `api+humantoken` で `imageBase64` がありません |
| `INVALID_REQUEST` (`400`) | `imageBase64` が base64 形式の画像ではありません |
| `IMAGE_TOO_LARGE` | 画像が 800 KB を超えています |
| `UNSUPPORTED_IMAGE_FORMAT` | 画像が PNG、JPEG、WebP のいずれでもありません |
| `PERMISSION_DENIED` (`403`) | アクセスキーが、このフローに対して有効化されていません |

拒否されたプロセスは失敗として保存されます。リクエストを修正し、新しい `correlationId` で新しいプロセスを作成してください。

リトライ処理を追加する前に、[エラーとリトライ](/ja/human-plugin/api-reference/errors-and-retries)をお読みください。新しい試行には新しい `correlationId` が必要です。

## 次へ

[プロセスの取得](/ja/human-plugin/api-reference/get-process)