# API リファレンス：ポップアップ

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

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

- [GET /api/v1/popups](https://okaeri.tech/developers/reference/popups.md#listPopups)　ポップアップの一覧（`listPopups`）
- [POST /api/v1/popups](https://okaeri.tech/developers/reference/popups.md#createPopup)　ポップアップの作成（下書き）（`createPopup`）
- [GET /api/v1/popups/{popup_id}](https://okaeri.tech/developers/reference/popups.md#getPopup)　ポップアップの取得（`getPopup`）
- [PATCH /api/v1/popups/{popup_id}](https://okaeri.tech/developers/reference/popups.md#updatePopup)　ポップアップの更新（`updatePopup`）

## GET /api/v1/popups

**ポップアップの一覧**

operationId：`listPopups`　必要なスコープ：`popups:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `site_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `limit` | クエリ | `integer` | — | 1〜200・既定値 `50` |
| `cursor` | クエリ | `string`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [PopupListOut](https://okaeri.tech/developers/reference/schemas.md#PopupListOut) |
| 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 / Popup 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/popups

**ポップアップの作成（下書き）**

operationId：`createPopup`　必要なスコープ：`popups:write`

作成した時点で publish まで走る（draft＝KV のキーを消す）。**失敗しても 201**。

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

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

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `site_id` | `string`（uuid） | 必須 | — |
| `name` | `string` | 必須 | — |
| `kind` | `string` | 必須 | retain（引き止め型）／capture（連絡先取得型） 値：`retain`・`capture`（今後増えることがある） |
| `memo` | `string`（null 可） | — | — |
| `config` | `object`（項目は未掲載）（null 可） | — | 表示内容・トリガー・表示期間などの設定（項目は今後増える） |
| `priority` | `integer`（null 可） | — | — |
| `campaign_id` | `string`（uuid）（null 可） | — | 連絡先取得型の取得先キャンペーン（同じサイト・有効化に必須） |
| `status` | `string`（null 可） | — | 作成時は常に draft。draft 以外を指定すると 422 値：`draft`・`active`・`paused`（今後増えることがある） |
| `acknowledgements` | `string` の配列（null 可） | — | 注釈を確認したうえで使う設定の確認（保存されず、監査ログに残る）。`timer_end_of_day`＝カウントダウンを「当日 23:59 まで」（`config.content.timer.mode`＝`end_of_day`）に新しくする保存で必須。`back_button`＝戻るボタンのトリガー（`config.trigger.back_button`＝true）に新しくする保存で必須。無ければ 422 `acknowledgement_required`。APIキーでは新しく設定できない（403 `session_required`） |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 201 | 成功 | [PopupDetailOut](https://okaeri.tech/developers/reference/schemas.md#PopupDetailOut) |
| 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` のサイト・`campaign_id` のキャンペーンが見つからない（`not_found`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`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 / Popup 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/popups/{popup_id}

**ポップアップの取得**

operationId：`getPopup`　必要なスコープ：`popups:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `popup_id` | パス | `string`（uuid） | 必須 | — |
| `nonce` | クエリ | `boolean` | — | 既定値 `false` |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [PopupDetailOut](https://okaeri.tech/developers/reference/schemas.md#PopupDetailOut) |
| 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 / Popup 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/popups/{popup_id}

**ポップアップの更新**

operationId：`updatePopup`　必要なスコープ：`popups:write`

`status: active` は上限（active の数）と連絡先取得型のキャンペーン指定を通った時だけ。

保存に続けて publish（有効＝値を書く・それ以外＝キーを消す）。**失敗しても 200**。

### パラメータ

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

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

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

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `name` | `string`（null 可） | — | — |
| `memo` | `string`（null 可） | — | — |
| `config` | `object`（項目は未掲載）（null 可） | — | — |
| `priority` | `integer`（null 可） | — | — |
| `campaign_id` | `string`（uuid）（null 可） | — | — |
| `status` | `string`（null 可） | — | active＝有効化・paused＝停止。APIキーは送ると 403 値：`draft`・`active`・`paused`（今後増えることがある） |
| `acknowledgements` | `string` の配列（null 可） | — | 注釈を確認したうえで使う設定の確認（保存されず、監査ログに残る）。`timer_end_of_day`＝カウントダウンを「当日 23:59 まで」（`config.content.timer.mode`＝`end_of_day`）に新しくする保存で必須。`back_button`＝戻るボタンのトリガー（`config.trigger.back_button`＝true）に新しくする保存で必須。無ければ 422 `acknowledgement_required`。APIキーでは新しく設定できない（403 `session_required`） |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [PopupDetailOut](https://okaeri.tech/developers/reference/schemas.md#PopupDetailOut) |
| 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`）。`invalid_status_transition`（draft へは戻せない） | [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 / Popup 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) |