# API リファレンス：キャンペーン

> https://okaeri.tech/developers/reference/campaigns/ の Markdown 版。

キャンペーン（`campaigns`）の操作です。共通の決まり（認証・レート制限・エラーの形）は[概要](https://okaeri.tech/developers/index.md)を、型の詳細は[スキーマ](https://okaeri.tech/developers/reference/schemas.md)を参照してください。

- [GET /api/v1/campaigns](https://okaeri.tech/developers/reference/campaigns.md#listCampaigns)　キャンペーンの一覧（`listCampaigns`）
- [POST /api/v1/campaigns](https://okaeri.tech/developers/reference/campaigns.md#createCampaign)　キャンペーンの作成（`createCampaign`）
- [GET /api/v1/campaigns/{campaign_id}](https://okaeri.tech/developers/reference/campaigns.md#getCampaign)　キャンペーンの取得（`getCampaign`）
- [PATCH /api/v1/campaigns/{campaign_id}](https://okaeri.tech/developers/reference/campaigns.md#updateCampaign)　キャンペーンの更新（`updateCampaign`）
- [PUT /api/v1/campaigns/{campaign_id}/url-rules](https://okaeri.tech/developers/reference/campaigns.md#replaceCampaignUrlRules)　キャンペーンの URL ルールの置き換え（`replaceCampaignUrlRules`）
- [PUT /api/v1/campaigns/{campaign_id}/form-profile](https://okaeri.tech/developers/reference/campaigns.md#replaceCampaignFormProfile)　キャンペーンのフォーム項目の置き換え（`replaceCampaignFormProfile`）
- [POST /api/v1/campaigns/{campaign_id}/duplicate](https://okaeri.tech/developers/reference/campaigns.md#duplicateCampaign)　キャンペーンの複製（`duplicateCampaign`）

## GET /api/v1/campaigns

**キャンペーンの一覧**

operationId：`listCampaigns`　必要なスコープ：`campaigns:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `site_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `status` | クエリ | `string`（null 可） | — | 値：`active`・`paused`・`archived`（今後増えることがある） |
| `limit` | クエリ | `integer` | — | 1〜200・既定値 `50` |
| `cursor` | クエリ | `string`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [CampaignListOut](https://okaeri.tech/developers/reference/schemas.md#CampaignListOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/campaigns

**キャンペーンの作成**

operationId：`createCampaign`　必要なスコープ：`campaigns:write`

作った時点でサイトの設置コードに並ぶ（サイト詳細がキャンペーン別のコードを出す）。

### リクエストの本文（JSON）

型：[CampaignIn](https://okaeri.tech/developers/reference/schemas.md#CampaignIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `site_id` | `string`（uuid） | 必須 | — |
| `key` | `string` | 必須 | — |
| `name` | `string` | 必須 | — |
| `product_name` | `string`（null 可） | — | — |
| `status` | `string`（null 可） | — | 省略時はセッション=active・APIキー=paused。APIキーは paused のみ指定可 値：`active`・`paused`・`archived`（今後増えることがある） |
| `abandon_wait_minutes` | `integer`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 201 | 成功 | [CampaignDetailOut](https://okaeri.tech/developers/reference/schemas.md#CampaignDetailOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | `site_id` のサイトが見つからない（`not_found`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`campaign_key_taken`（同じ `key` のキャンペーンがある）／`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## GET /api/v1/campaigns/{campaign_id}

**キャンペーンの取得**

operationId：`getCampaign`　必要なスコープ：`campaigns:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `campaign_id` | パス | `string`（uuid） | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [CampaignDetailOut](https://okaeri.tech/developers/reference/schemas.md#CampaignDetailOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## PATCH /api/v1/campaigns/{campaign_id}

**キャンペーンの更新**

operationId：`updateCampaign`　必要なスコープ：`campaigns:write`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `campaign_id` | パス | `string`（uuid） | 必須 | — |

### リクエストの本文（JSON）

型：[CampaignPatch](https://okaeri.tech/developers/reference/schemas.md#CampaignPatch)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `name` | `string`（null 可） | — | — |
| `product_name` | `string`（null 可） | — | — |
| `status` | `string`（null 可） | — | 値：`active`・`paused`・`archived`（今後増えることがある） |
| `abandon_wait_minutes` | `integer`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [CampaignDetailOut](https://okaeri.tech/developers/reference/schemas.md#CampaignDetailOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## PUT /api/v1/campaigns/{campaign_id}/url-rules

**キャンペーンの URL ルールの置き換え**

operationId：`replaceCampaignUrlRules`　必要なスコープ：`campaigns:write`

一括置換。**1件でも不正なら 422 で全体を保存しない**。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `campaign_id` | パス | `string`（uuid） | 必須 | — |

### リクエストの本文（JSON）

型：[UrlRulesIn](https://okaeri.tech/developers/reference/schemas.md#UrlRulesIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `rules` | [UrlRuleIn](https://okaeri.tech/developers/reference/schemas.md#UrlRuleIn) の配列 | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [CampaignDetailOut](https://okaeri.tech/developers/reference/schemas.md#CampaignDetailOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## PUT /api/v1/campaigns/{campaign_id}/form-profile

**キャンペーンのフォーム項目の置き換え**

operationId：`replaceCampaignFormProfile`　必要なスコープ：`campaigns:write`

フォーム項目の手動セレクタ。**空配列を送ると自動検出へ戻る**。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `campaign_id` | パス | `string`（uuid） | 必須 | — |

### リクエストの本文（JSON）

型：[FormProfileIn](https://okaeri.tech/developers/reference/schemas.md#FormProfileIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `tel_selectors` | `string` の配列（null 可） | — | — |
| `email_selectors` | `string` の配列（null 可） | — | — |
| `consent_selector` | `string`（null 可） | — | — |
| `tel_split_selectors` | `string` の配列（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [CampaignDetailOut](https://okaeri.tech/developers/reference/schemas.md#CampaignDetailOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/campaigns/{campaign_id}/duplicate

**キャンペーンの複製**

operationId：`duplicateCampaign`　必要なスコープ：`campaigns:write`・`messages:write`・`scenarios:write`（すべて必要）

複製。**必ず一度も稼働していない停止中（タグ設定に載らない）で作る**。

配下のシナリオ（下書きで）とメッセージ（実体コピー）も作る＝3つの書き込みスコープが要る。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `campaign_id` | パス | `string`（uuid） | 必須 | — |

### リクエストの本文（JSON）

型：[CampaignDuplicateIn](https://okaeri.tech/developers/reference/schemas.md#CampaignDuplicateIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `key` | `string`（null 可） | — | — |
| `name` | `string`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 201 | 成功 | [CampaignDetailOut](https://okaeri.tech/developers/reference/schemas.md#CampaignDetailOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`campaign_key_taken`（同じ `key` のキャンペーンがある）／`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |