---
title: バックエンドを統合する
description: バックエンドサービスから Human Plugin を呼び出す方法。保存すべき情報、ポーリング、結果の読み取り、失敗時の処理を説明します。
canonical: https://developer.unico.io/ja/human-plugin/integrations/backend
locale: ja
generated_by: markdown-export
---

# バックエンドを統合する

サーバーサイドのサービスから Human Plugin を呼び出すためのチェックリストです。

Human Plugin は、バックエンドからのみ呼び出すことを前提としています。ブラウザやモバイルアプリには公開しないでください。受信リクエストの認証機能がありません。

## 1. 作成

### curl

```bash
curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'
```

### Node.js

```javascript
const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body is { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;
```

クライアントのタイムアウトは**少なくとも 60 秒**に設定してください。作成の処理には最大 30 秒かかる場合があり、これにデータベースの処理が加わります。`id` は作成のレスポンスでしか返されないため、クライアントが早く諦めると、完了するプロセスを見失うおそれがあります。

## 2. 後で必要になる情報を保存する

| 保存するもの | 理由 |
| --- | --- |
| `id` | `GET` で使うハンドルです |
| Journey の `token` と `link`(ある場合) | 作成のレスポンスでのみ返されます。Human Plugin は保存しません |
| 自社の `correlationId` | 一意である必要があります。`503` の後を除き、再試行を含めて試行ごとに新しい値を生成してください |

## 3. 結果を読み取る

1. `state` が `PROCESS_STATE_FINISHED` の場合は、`data` から結果を読み取ります。`humanToken`(再検証では `humanTokenMatch`)、`liveness`、`ndocs` です。完了は承認と同じ意味ではありません。
2. `state` が `PROCESS_STATE_CREATED` の場合は、状態が変わるまでバックオフを入れて `GET /v1/processes/{id}` をポーリングします。プロセスを進めるものは他にありません。
3. `state` が `PROCESS_STATE_FAILED` の場合、プロセスは結果なしで終了しています。フローが許すなら、新しいプロセスを開始してください。

## 4. インテリジェンスを活用する

`data.ndocs` は、その人物が自社とこれまでにどう関わったかを示します。何件の自社クライアントとドキュメントで確認されたか、またその時期です。判断には Human Token と併せて使用してください。値が存在しない場合もあります。[インテリジェンス](/ja/human-plugin/get-started/intelligence)を参照してください。

## 5. 失敗時の処理

- 作成での `500` と `502` は、自動で再試行しないでください。[エラーと再試行](/ja/human-plugin/api-reference/errors-and-retries)を参照してください。
- 作成での `503` は同じ `correlationId` で、`GET` の失敗はすべて、バックオフを入れて再試行します。
- `409` は `correlationId` がすでに使われていることを意味します。再利用しないでください。
- `503` が繰り返される場合はアラートを出してください。Human Plugin がデータベースに接続できていないことを意味します。

## 運用上の注意

- Human Plugin は、コンテナと同じネットワークから呼び出してください。経路が信頼できないネットワークを通る場合は、前段で TLS を終端してください。
- Human Plugin の 1 つのインストールが、1 つの分離境界です。インテリジェンスを共有してはならない複数のクライアント、ブランド、環境には、それぞれ独立したインストールとデータベースが必要で、インテリジェンスもそれぞれ別になります。