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

# Catalog REST APIを使い始める

> Catalog REST APIの認証方法、カタログデータの管理、次のページの取得方法、書き込みエラーへの対処を説明します。

Catalog REST APIでは、商品やコンテンツなどの参照データをスキーマと一緒に管理できます。メッセージでは、Liquidの`catalog_items`または`catalog_selection_items`タグで保存した値を参照します。

> [!WARNING]
>
> カタログには個人を特定できない参照データだけを保存します。カタログの作成時は、`data_classification: "non_personal"`を指定してください。ユーザーID、メールアドレス、電話番号、デバイストークンなど、個人を特定できる値はフィールドやアイテムに含めないでください。

## 操作できるリソース

ベースURLは`https://api.notifly.tech`です。カタログのパスはプロジェクトごとに分かれています。

```text theme={null}
/v1/projects/{projectId}/catalogs
```

公開APIで読み取りや変更ができるのは、以下の条件をすべて満たすカタログです。

* データソースが`api`である。
* データ分類が`non_personal`である。
* ステータスが`active`である。

Googleスプレッドシートを使うカタログは、公開REST APIの一覧には表示されません。データソースと同期はコンソールで管理します。

| リソース | 対応する操作 |
| - | - |
| カタログ | 作成、一覧取得、完全削除 |
| フィールド | 追加、削除 |
| アイテム | 単件または一括での作成、取得、全体の置換、一部の更新、削除 |
| セレクション | 作成、削除 |

カタログの検索には一覧取得を使います。カタログの単件取得や、名前、説明、スキーマ全体の変更には対応していません。フィールド名や型を変える場合は、新しいフィールドを追加して値を移行します。セレクションは作成と削除に対応しています。一覧取得、単件取得、更新はできません。

リクエストとレスポンスはJSON形式です。CSVをインポートまたはエクスポートする公開エンドポイントはありません。カタログを削除する前に、参照しているメッセージとバックアップを確認してください。カタログに`DELETE`を実行すると、データと同期履歴が完全に削除されます。

## 認証する

Access KeyとSecret Keyを`/authenticate`に送信して、APIトークンを発行します。カタログへのリクエストには以下のヘッダーを指定します。

```http theme={null}
Authorization: Bearer <auth-token>
Content-Type: application/json
```

APIトークンの有効期間は、デフォルトで1時間です。期限が切れて`401`が返った場合は、トークンを再発行してからリクエストを再送します。認証の詳細は[APIの概要](https://docs.notifly.tech/ja/api-reference/getting-started.md)を参照してください。

## カタログを作成してアイテムを取得する

### 1. カタログを作成する

1回のリクエストでカタログを1つ作成します。`fields`の最初の要素に、`string`型の`id`を定義してください。

```json theme={null}
{
  "catalogs": [
    {
      "name": "products",
      "description": "メッセージのパーソナライズに使う商品情報",
      "data_classification": "non_personal",
      "fields": [
        { "name": "id", "type": "string" },
        { "name": "name", "type": "string" },
        { "name": "price", "type": "number" },
        { "name": "tags", "type": "array" }
      ]
    }
  ]
}
```

フィールドの型には`string`、`number`、`boolean`、`time`、`geo`、`object`、`array`を指定できます。

* `time`には、ISO 8601形式の文字列またはUnixエポックからの経過秒数（安全な整数の範囲内）を指定します。NotiflyはUTCのISO 8601形式で保存します。
* `geo`には、有限の数値を`[経度, 緯度]`の順に指定します。経度は-180から180、緯度は-90から90の範囲です。
* `array`には文字列の配列を指定します。

### 2. アイテムを追加する

アイテムをまとめて作成するには、`POST /items`を呼び出します。1回のリクエストで最大50件を送信できます。

```json theme={null}
{
  "items": [
    {
      "id": "sku-1001",
      "name": "コットンシャツ",
      "price": 39000,
      "tags": ["summer", "shirt"]
    }
  ]
}
```

スキーマに合わないアイテムが1件でもあると、リクエスト全体が失敗します。その場合、アイテムは1件も保存されません。

### 3. 次のページを取得する

`GET /items`はアイテムをIDの昇順で50件ずつ返します。次のページがある場合、レスポンスに`data.next_cursor`と`Link: <...>; rel="next"`ヘッダーが含まれます。

* `data.next_cursor`の値を変更せず、次のリクエストのクエリパラメーター`cursor`に指定します。
* `null`が返った場合は、そのページが最後です。

## セレクションのフィルター

セレクションには、メッセージで繰り返し使用するカタログアイテムの一部を保存できます。

| フィールドの型 | 演算子 |
| - | - |
| `string` | `equals`、`does not equal` |
| `number` | `equals`、`does not equal`、`greater than`、`less than` |
| `boolean` | `is` |
| `time` | `before`、`after` |
| `array` | `includes value`、`does not include value` |
| `geo`、`object` | フィルター対象外 |

フィルターの値に`null`は使えません。`sort_field`を指定する場合は、`sort_order`も指定します。`results_limit`のデフォルトは50件です。並べ替えを指定しない場合、セレクションの作成時に`results_limit`で指定した件数を上限として、アイテムを無作為に選びます。

## 書き込みメソッド

| メソッド | 操作 | 再試行時の確認事項 |
| - | - | - |
| `POST` | リソースを新規作成します。 | 同じIDが存在すると`409`が返ります。 |
| `PUT` | アイテム全体を置換します。指定したIDがなければ新規作成します。 | リクエストに含めなかったフィールドは削除されます。 |
| `PATCH` | 既存のアイテムのうち、指定したフィールドだけを変更します。 | 指定したIDがなければ`404`が返ります。配列には`$add`と`$remove`を使用できます。 |
| `DELETE` | 指定したリソースを削除します。 | 対象が存在しなければ`404`が返ります。 |

配列フィールドの値を一部だけ追加、削除する例です。

```json theme={null}
{
  "items": [
    {
      "id": "sku-1001",
      "tags": {
        "$add": ["sale"],
        "$remove": ["summer"]
      }
    }
  ]
}
```

アイテムの一括書き込みやフィールド、セレクションの変更に成功すると`200`が返ります。カタログや単一アイテムを作成すると`201`が返ります。

## レスポンスとエラー

Catalog APIは以下の形式でレスポンスを返します。

```json theme={null}
{
  "data": {},
  "error": null
}
```

エラーの場合、`data`は`null`になり、`error.code`と`error.message`が返ります。入力検証のエラーでは、対象のフィールドやパスを含む`error.details`が返る場合があります。

* `400`の場合は、プロジェクトIDの形式、スキーマ、フィールドの値を修正してから再送します。
* `401`の場合は、APIトークンを再発行します。
* `403`の場合は、プロジェクトIDとアクセス権限を確認します。
* `404`の場合は、カタログ、フィールド、アイテム、セレクションの名前を確認します。
* `409`の場合は、既存リソースとの重複や状態の競合を確認します。利用できる一覧または取得操作で確認するか、呼び出し側の処理記録を参照します。
* `413`の場合は、4 MiB未満に分割して送信します。
* `500`やタイムアウトでレスポンスを受け取れない場合、`POST`は一覧または取得操作で反映済みのリソースを確認してから、未反映のものだけを再送します。アイテム全体を安全に何度も適用できる場合は、`PUT`を使用します。再試行までの間隔は指数バックオフで延ばし、ランダムな待機時間を加えます。

> [!NOTE]
>
> 一括移行では、1回に最大50件のアイテムを送信します。大量の書き込みを継続する場合は、必要な処理量を事前にNotiflyと確認してください。Brazeのエンドポイントに適用される共有レート制限枠に相当する公開仕様は、Catalog APIにはありません。

## 主な上限

| 項目 | 上限 |
| - | - |
| プロジェクトあたりの有効なカタログ | 20個 |
| APIカタログあたりのフィールド（`id`を含む） | 500個 |
| 1回のリクエストで追加できるフィールド | 50個 |
| 1回のリクエストで書き込みまたは削除できるアイテム | 50件 |
| アイテム1件のサイズ | 1 MiB |
| カタログ1個のサイズ | 2 GiB |
| プロジェクト内の有効なカタログの合計サイズ | 15 GiB |
| 文字列値の長さ | 5,000文字 |
| 配列値に含められる文字列 | 100個 |
| `object`と`array`のネスト | 50階層 |
| カタログあたりのセレクション | 30個 |
| 1回のセレクションリクエストのフィルター | 4個 |

`object`フィールド内のキーには`.`や`$`を使用できません。`$add`と`$remove`は、配列フィールドを`PATCH`する演算子として使用できます。

> [card] [Catalog APIの操作一覧](https://docs.notifly.tech/ja/api-reference/catalog/list-api-catalogs.md)
>
> カタログ、アイテム、フィールド、セレクションのリクエストとレスポンスのスキーマを確認します。

> [card] [Brazeからカタログを移行する](https://docs.notifly.tech/ja/developer-guide/migration/braze-catalogs.md)
>
> 認証、レスポンス、ステータスコードの違いと移行手順を確認します。


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