> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contentcare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# テスト API キー

> ファイルを処理したりクレジットを消費したりせずに BIZ MORI の注文ライフサイクルを検証します。

`sk_test_` プレフィックスの自動発行テスト API キーを使用すると、本番 API キーを使う前に連携を検証できます。

テスト API キーは本番 API キーと同じ Bearer 認証を使用しますが、Anti-AI、watermark、AI Detection の処理は実行しません。結果ファイルも作成されず、顧客のクレジットも消費されません。

> [!NOTE]
>
> 永続テスト注文とテスト Webhook は環境ごとに有効化されます。保存されない仮の注文だけが返される場合、その環境では従来のモック動作が使用されています。処理品質の確認や結果ファイルのダウンロードが必要な場合は、本番 API キーを使用してください。

## テスト注文のライフサイクル

**1. 注文を作成する**

本番連携で使用するものと同じ注文作成エンドポイントを呼び出します。`Authorization` ヘッダーにテストキーを渡し、`idempotencyKey` を指定してください。論理注文ごとに新しい UUIDv4 を生成し、ネットワーク障害後に同じリクエストを再試行する場合にだけ再利用してください。

```bash theme={null}
curl -X POST https://api.bizmori.com/api/v2/orders/anti-ai \
  -H "Authorization: Bearer $BIZMORI_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "2f1c3e4a-8b57-4a6d-9c20-7e5f1a3b6d42",
    "files": [{"fileName": "sample.png"}]
  }'
```

**2. テストファイルをアップロードする**

アップロード方式のテスト注文では、注文レスポンスの `uploadUrl` にファイルを送信します。テスト用のアップロード URL は `PUT /api/v2/test-uploads/{token}` ルートを使用します。

アップロード URL には独自の認証情報が含まれています。API キーヘッダーを追加しないでください。BIZ MORI はリクエストストリームを受け取り、アップロード完了を記録した後、ファイル内容を破棄します。

```bash theme={null}
curl -X PUT "TEST_UPLOAD_URL" \
  --data-binary @sample.png
```

テストアップロードのデフォルト上限は 50 MiB です。アップロード URL の有効期限が切れても注文がアップロード待ちの場合は、[アップロード URL の再発行](https://docs.contentcare.ai/ja/api-reference/orders/refresh-urls.md) を使用してください。

**3. 必要な場合に確認する**

Anti-AI のアップロード方式と AI Detection では、アップロード後に確認エンドポイントを呼び出します。Watermark Embed と Watermark Extract は、必要なアップロードが完了すると開始されます。Anti-AI の URL 方式は注文作成時に開始されます。

**4. 状態の遷移を確認する**

テスト注文も本番注文と同じ状態の形式に従います。

`pending → inProgress → complete` または `failed`

シミュレーション処理の遅延は約 5 秒です。[注文詳細の取得](https://docs.contentcare.ai/ja/api-reference/orders/get-order-v3.md) をポーリングするか、環境で Webhook が有効になっている場合はテスト Webhook を使用してください。

**5. テスト注文を確認する**

同じテストキーで [注文一覧](https://docs.contentcare.ai/ja/api-reference/orders/list-orders.md)、[最近の利用統計](https://docs.contentcare.ai/ja/api-reference/orders/recent-stats.md)、[注文詳細の取得](https://docs.contentcare.ai/ja/api-reference/orders/get-order-v3.md) を呼び出します。そのキーに関連付けられたアカウントが所有するテスト注文だけが返されます。

## サービスごとのフロー

| サービス | 作成 | アップロード | 確認 |
| - | - | - | - |
| Anti-AI アップロード方式 | `POST /api/v2/orders/anti-ai` | テストアップロード URL | 必要 |
| Anti-AI URL 方式 | `POST /api/v2/orders/anti-ai` | 不要 | 不要 |
| Watermark Embed | `POST /api/v3/orders/wtr-embed` | テストアップロード URL | 不要 |
| Watermark Extract | `POST /api/v3/orders/wtr-extract` | テストアップロード URL | 不要 |
| AI Detection | `POST /api/v2/orders/ai-detection` | テストアップロード URL | 必要 |

Watermark Embed または Watermark Extract では確認エンドポイントを呼び出さないでください。アップロード完了後に処理が開始されるため、確認リクエストは失敗します。

> [!WARNING]
>
> Watermark v2 エンドポイント（`POST /api/v2/orders/wtr-embed`、`POST /api/v2/orders/wtr-extract`）は 2026 年 10 月 9 日 09:00 KST（00:00 UTC）にサポートを終了しました。v3 エンドポイント（`/api/v3/orders/wtr-embed`、`/api/v3/orders/wtr-extract`）へ移行してください。このガイドでは Watermark Embed と Watermark Extract について v3 エンドポイントを説明します。

## 決定的な結果を選択する

入力ファイル名を使うと、外部処理サービスに依存せずに成功・失敗状態を検証できます。

| ファイル名のサフィックス | 結果 |
| - | - |
| `*_fail.<ext>` | 注文が失敗します |
| `*_detected.<ext>` | Watermark Extract が watermark を検出します（`detectionStatus` は `detected`） |
| `*_undetected.<ext>` | Watermark Extract が watermark を検出しません（`detectionStatus` は `undetected`） |
| `*_ai.<ext>` | AI Detection が確率 `0.98` を返します |
| `*_human.<ext>` | AI Detection が確率 `0.02` を返します |

サフィックスがない場合、Anti-AI と Watermark Embed は成功し、Watermark Extract は watermark を検出せず、AI Detection は確率 `0.02` を返します。複数ファイルの注文で 1 つでも `_fail` を使用すると、注文は失敗します。

Watermark Extract では、`detected` と `undetected` は検査対象ファイル名（`file.fileName`）だけで決まります。元ファイルの `_detected` サフィックスは結果に影響しませんが、どちらのファイルでも `_fail` があると注文は失敗します。

## テスト Webhook

Dashboard、本番 API キー、またはテスト API キーで、同じ所有者のテスト Webhook エンドポイントを作成できます。テストキーでは `isTest` を省略するか `true` に設定でき、`isTest: false` は `403 AUTH_FORBIDDEN` を返します。

```bash theme={null}
curl -X POST https://api.bizmori.com/api/v2/orders/webhooks \
  -H "Authorization: Bearer $BIZMORI_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integration test webhook",
    "url": "https://example.com/test-webhook",
    "isTest": true
  }'
```

* テスト API キーでは、同じ所有者のテストエンドポイントの作成、一覧・詳細取得、更新、削除、イベント取得、失敗イベントの再送を実行できます。本番モードと別所有者のリソースは公開されません。
* `isTest: true` のエンドポイントはテスト注文イベントだけを受信します。
* `isTest: false` のエンドポイントは本番注文イベントだけを受信します。
* テスト Webhook のイベント名、HMAC-SHA256 署名、再試行動作は本番 Webhook と同じです。
* 結果ファイルを作成しないため、Anti-AI と Watermark Embed のテストイベントでは `downloadUrl: null` になります。

所有者とモードの分離、署名検証、イベントペイロード、再送ルールについては [Webhook](https://docs.contentcare.ai/ja/webhooks.md) を参照してください。

## 注文詳細、ダウンロード、レポート

アップロードが完了すると、テスト注文は `inProgress` になり、約 5 秒後に `complete` または `failed` になります。[注文詳細を取得（v3）](https://docs.contentcare.ai/ja/api-reference/orders/get-order-v3.md)は、v2・v3 のどちらで作成したテスト注文も本番注文と同じ形式で返します。

| 操作 | テスト API キーの動作 |
| - | - |
| `GET /api/v3/orders/{orderId}` | テスト注文を返します。`pending` の間、`inputFiles[].uploadUrl` はテストアップロード URL です。Watermark Embed の注文では、watermark の文言ごとに `result.outputFiles` の項目が 1 件作成されます。`expiresAt` は注文作成の 7 日後です。 |
| `GET /api/v3/orders/{orderId}/download` | 完了した Anti-AI と Watermark Embed のテスト注文でのみ動作します。固定のサンプルファイルを指す `archiveUrl` と `files[]` を返します。`expiresInSeconds` は本番注文と同じルール（最大 3600 秒）に従います。 |
| `POST /api/v3/orders/{orderId}/reports`, `GET /api/v3/orders/{orderId}/reports/{locale}` | 結果が `detected` の Watermark Extract 注文でのみ動作します。`completed` と、300 秒間有効なサンプルレポート PDF の URL を返します。 |

* ダウンロード URL は実際の結果ではなく、固定のサンプルファイルを指します。v3 で作成した Watermark Embed の注文で結果が 1 つの場合、`archiveUrl` はサンプルファイルそのもので、それ以外はサンプル ZIP ファイルです。結果ファイルのない Anti-AI のテスト注文は `files: []` を返します。
* 検出結果が `detected` の場合、`watermarkText` は `MORI TEST WATERMARK` です。`reportSupported` は、v3 で作成した Watermark Extract の注文の結果が `detected` のときだけ `true` です。
* レポートは 1 ページのサンプル PDF です。実際の検出結果は含まれず、`locale` によって内容は変わりません。
* `undetected` の注文は `REPORT_NOT_AVAILABLE`、未完了または失敗した注文は `ORDER_NOT_COMPLETED`、Watermark Embed の注文は `ORDER_TYPE_NOT_MATCH` で拒否されます。別所有者の注文と本番注文は `ORDER_NOT_FOUND` を返します。

本番の Watermark 注文との違い:

* テストのレポートリクエストは即座に `200 completed` を返します。`202 queued` や `processing` は返さず、クレジットも消費しません。
* テストレポートは保存されないため、注文詳細の `result.reports` は常に空です。
* 同じ `idempotencyKey` を再送すると、リクエスト本文を比較せずに既存の注文を返すため、`409` は発生しません。

## API の動作と制限

| 操作 | テスト API キーの動作 |
| - | - |
| `GET /api/v2/orders` | アカウントの永続テスト注文を返します |
| `GET /api/v2/orders/stats/recent` | アカウントのテスト注文の統計を返します |
| `GET /api/v2/orders/{orderId}` | 非推奨。キーのアカウントが所有するテスト注文を返します |
| `POST /api/v2/orders/{orderId}/refresh-urls` | まだ使用されていないアップロード URL を再発行します |
| `GET /api/v2/orders/{orderId}/download` | 非推奨。`404 PROCESSED_FILE_NOT_FOUND` を返します |
| Webhook の管理と再送 | 同じ所有者のテストエンドポイントだけを管理できます。本番モードと別所有者の ID は `404`、`isTest: false` は `403 AUTH_FORBIDDEN` を返します |

テスト注文と本番注文は分離されています。テストキーでは本番注文を読み取ったり変更したりできず、本番キーでもテスト注文を読み取ったり変更したりできません。

テスト API キーは次の処理を実行しません。

* 画像またはドキュメントの実処理
* クレジットの予約または消費
* ダウンロード可能な結果ファイルの作成（Watermark のダウンロードおよびレポートのエンドポイントが返す固定サンプルファイルを除く）
* 本番 Webhook エンドポイントへのイベント送信

認証の詳細は [認証](https://docs.contentcare.ai/ja/authentication.md)、エラー処理は [エラーコード](https://docs.contentcare.ai/ja/errors.md) を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.