> ## 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.

# Braze Catalogs から移行する

> Braze Catalog API の呼び出しとデータを Notifly Catalog REST API に移行するための違い、変換規則、切り替え手順を説明します。

Braze Catalogs と Notifly Catalogs は、カタログ、アイテム、フィールド、セレクションのパスとリクエスト構造がほぼ共通しています。ただし、**ベース URL と認証**、**プロジェクトのパス**、**レスポンスのラッパー形式**、**同期処理と非同期処理のステータスコード**、**データ分類の宣言**が異なります。URL を変更するだけでは移行できません。

このガイドは、2026 年 8 月 4 日時点の Braze 公式 Catalog API と Notifly Catalog REST API を比較しています。実際の移行時には、使用中の Braze クラスターの REST エンドポイントと、最新の Braze ドキュメントも確認してください。

## 主な違いを確認する

| 項目 | Braze Catalog API | Notifly Catalog API |
| - | - | - |
| ベース URL | ワークスペースのクラスターに対応する REST エンドポイント | `https://api.notifly.tech` |
| 認証 | REST API key を Bearer token として送信 | Access Key と Secret Key で発行する、有効期間 1 時間の Bearer token |
| プロジェクトの識別 | API key のワークスペースで決定 | すべてのパスに `/v1/projects/{projectId}` を含む |
| データ分類 | 作成リクエストに専用フィールドなし | `data_classification: "non_personal"` が必須 |
| レスポンス | 主に `message`、`catalogs`、`items`、`errors` | `{ "data": ..., "error": ... }` 形式でラップ |
| カタログとアイテムの削除、アイテムの一括書き込み、フィールドとセレクションの書き込み | 同期処理か非同期処理かはエンドポイントによって異なり、成功時は主に `202` | リクエスト内で処理し、`200` を返す |
| カタログのフィールド数 | REST API は最大 500。CSV アップロードは最大 1,000 列 | API カタログは `id` を含めて最大 500 |
| アイテムのページ | 50 件。`Link` ヘッダーとカーソルを使用 | 50 件。`Link` ヘッダーと `data.next_cursor` を使用 |
| セレクションの入力 | `external_id` と `source` を含む | 両フィールドは受け付けず、`name` で識別 |
| 専用のレート制限 | 同期カタログのエンドポイントは合計 50 req/min。同期アイテムのエンドポイントは別枠で合計 50 req/min。非同期フィールドとセレクションはさらに別枠で合計 50 req/min。非同期の一括アイテム操作は合計 16,000 req/min | 公開 API 仕様には、Braze と同等のエンドポイント間で共有する制限の記載なし |

> [!WARNING]
>
> Braze に保存したデータに、氏名、メールアドレス、電話番号、外部ユーザー ID などの個人を識別できる情報がある場合は、そのまま移行しないでください。
> Notifly の API カタログは、個人情報を含まない参照データのみをサポートします。

## エンドポイントを変更する

Braze のパスの前に、Notifly のプロジェクトプレフィックスを追加します。

```text theme={null}
Braze:   https://{BRAZE_REST_ENDPOINT}/catalogs/{catalog_name}/items
Notifly: https://api.notifly.tech/v1/projects/{projectId}/catalogs/{catalogName}/items
```

Braze のパスパラメーター `catalog_name`、`item_id`、`field_name` は、Notifly では `catalogName`、`itemId`、`fieldName` と表記します。実際の URL の値と役割は同じです。

### カタログ

| 操作 | メソッドとサフィックス | Notifly の成功ステータス |
| - | - | - |
| 一覧取得 | `GET /catalogs` | `200` |
| 作成 | `POST /catalogs` | `201` |
| 削除 | `DELETE /catalogs/{catalogName}` | `200` |

### アイテム

| 操作 | メソッドとサフィックス | Notifly の成功ステータス |
| - | - | - |
| ページ単位の一覧取得 | `GET /catalogs/{catalogName}/items` | `200` |
| 1 件取得 | `GET /catalogs/{catalogName}/items/{itemId}` | `200` |
| 1 件作成 | `POST /catalogs/{catalogName}/items/{itemId}` | `201` |
| 1 件を全置換または upsert | `PUT /catalogs/{catalogName}/items/{itemId}` | `200` |
| 1 件を部分更新 | `PATCH /catalogs/{catalogName}/items/{itemId}` | `200` |
| 1 件削除 | `DELETE /catalogs/{catalogName}/items/{itemId}` | `200` |
| 最大 50 件を作成 | `POST /catalogs/{catalogName}/items` | `200` |
| 最大 50 件を全置換または upsert | `PUT /catalogs/{catalogName}/items` | `200` |
| 最大 50 件を部分更新 | `PATCH /catalogs/{catalogName}/items` | `200` |
| 最大 50 件を削除 | `DELETE /catalogs/{catalogName}/items` | `200` |

`PUT` は、送信したアイテムの値をすべて置き換え、アイテムが存在しなければ作成します。`PATCH` は、既存アイテムの送信したフィールドのみを変更し、存在しない ID に対しては `404` を返します。配列フィールドでは、Braze と同じ `$add`、`$remove` 操作を使用できます。

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

### フィールドとセレクション

| 操作 | メソッドとサフィックス | Notifly の成功ステータス |
| - | - | - |
| フィールドを追加 | `POST /catalogs/{catalogName}/fields` | `200` |
| フィールドを削除 | `DELETE /catalogs/{catalogName}/fields/{fieldName}` | `200` |
| セレクションを作成 | `POST /catalogs/{catalogName}/selections` | `200` |
| セレクションを削除 | `DELETE /catalogs/{catalogName}/selections/{selectionName}` | `200` |

Notifly のセレクション作成リクエストでは、Braze の `external_id` と `source` を削除します。フィルター値に `null` は使用できません。フィールドの型ごとに使用できる演算子は、[セレクションのフィルター](https://docs.notifly.tech/ja/api-reference/catalogs/getting-started.md#セレクションのフィルター)を参照してください。

```diff theme={null}
 {
   "selection": {
     "name": "sale-products",
     "description": "할인 상품",
-    "external_id": "sale-products-v1",
-    "source": "custom",
     "filters": [
       { "field": "discount", "operator": "greater than", "value": 0 }
     ],
     "results_limit": 20,
     "sort_field": "discount",
     "sort_order": "desc"
   }
 }
```

## 認証コードを変更する

Braze の REST API key をリクエストごとに送信する代わりに、Notifly の `/authenticate` で認証トークンを発行し、再利用します。トークンの有効期間は 1 時間です。

```javascript theme={null}
async function issueNotiflyToken() {
  const response = await fetch("https://api.notifly.tech/authenticate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      accessKey: process.env.NOTIFLY_ACCESS_KEY,
      secretKey: process.env.NOTIFLY_SECRET_KEY
    })
  });

  const body = await response.json();
  if (!response.ok || typeof body.data !== "string") {
    throw new Error(`Notifly authentication failed: ${response.status}`);
  }
  return body.data;
}
```

> [!NOTE]
>
> 本番コードでは、リクエストごとにトークンを発行せず、有効期限が切れるまでメモリにキャッシュしてください。
> Access Key、Secret Key、トークン、認証レスポンスの本文はログに記録しないでください。
> 詳しくは、[APIの概要](https://docs.notifly.tech/ja/api-reference/getting-started.md)を参照してください。

## カタログ作成リクエストを変換する

Braze の `catalogs[0]` オブジェクトに `data_classification` を追加します。フィールドの順序を維持し、先頭のフィールドが `id:string` であることを確認してください。

```diff theme={null}
 {
   "catalogs": [
     {
       "name": "products",
       "description": "Product catalog",
+      "data_classification": "non_personal",
       "fields": [
         { "name": "id", "type": "string" },
         { "name": "name", "type": "string" },
         { "name": "price", "type": "number" }
       ]
     }
   ]
 }
```

作成前に、次の制約を確認してください。

* フィールドが 500 を超える場合は、不要なフィールドを削除するか、カタログを分割します。
* カタログとフィールドの識別子、およびアイテム ID は最大 250 文字です。英大文字、英小文字、数字、ハイフン、アンダースコアのみ使用できます。
* `array` 値は文字列の配列で、要素数は最大 100 です。
* `geo` 値は `[longitude, latitude]` の順序です。
* `time` 値は ISO 8601 文字列または Unix 秒です。保存時に UTC の ISO 8601 文字列に正規化されます。
* `object` のキーには、ピリオド（`.`）とドル記号（`$`）を使用できません。
* 文字列の値は最大 5,000 文字、アイテム 1 件は最大 1 MiB です。

## レスポンス処理を変更する

### 成功レスポンス

Braze でアイテムを 1 件作成すると、次の成功メッセージが返されます。

```json theme={null}
{ "message": "success" }
```

Notifly は、作成または取得したリソースを `data` に返します。

```json theme={null}
{
  "data": {
    "id": "sku-001",
    "name": "에브리데이 백팩",
    "price": 59000
  },
  "error": null
}
```

一括操作、フィールド操作、セレクション操作、削除のリクエストが成功すると、次の空の成功レスポンスが返されます。

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

既存のコードで `response.message === "success"` または `status === 202` のみを確認している場合は、`response.error === null` と、エンドポイントごとの成功ステータス `200` または `201` を確認するように変更してください。

### エラーレスポンス

Braze の `errors[]` を解析するコードを、Notifly の `error.code`、`error.message`、任意の `error.details` を読むコードに変更します。

```json theme={null}
{
  "data": null,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid bulk item request.",
    "details": [
      {
        "field": "items[0].unknown_field",
        "path": ["items", 0, "unknown_field"],
        "code": "invalid-fields",
        "message": "Unrecognized field: unknown_field."
      }
    ]
  }
}
```

エラーメッセージの文字列比較ではなく、HTTP ステータスと `error.code` に基づいて処理してください。`details` がある場合は、`field` または `path` で不正な入力箇所を特定できます。

### ページネーション

両 API とも、1 ページで最大 50 件のアイテムを返します。Notifly は、次のカーソルをレスポンス本文と `Link` ヘッダーの両方で返します。

```json theme={null}
{
  "data": {
    "items": [],
    "next_cursor": "eyJhZnRlciI6InNrdS0wNTAifQ",
    "links": {
      "next": "/v1/projects/.../catalogs/products/items?cursor=..."
    }
  },
  "error": null
}
```

Braze の `Link` ヘッダーをたどるコードは、引き続きヘッダーを使用できます。新しく実装する場合は、`data.next_cursor` が `null` になるまでページを取得する方法も使えます。カーソルは API の内部形式のため、解釈したり、自分で生成したりしないでください。

## データを移行する

### 1. Braze の資産を調査する

最初に、次の情報を記録します。

* カタログ名、説明、フィールドの順序と型。
* アイテム数とデータの総容量。
* メッセージで使用している `catalog_items` と `catalog_selection_items` の Liquid タグ。
* セレクション名、フィルター、並び順、取得件数の上限。
* カタログを使用するバッチジョブ、Webhook、運用ツール、API key の権限。
* フィールド数が `id` を含めて 500 以下で、JSON のネストが 50 階層以下であるか。
* object のキーに `.` または `$` がないか、個人を識別できる情報が含まれていないか。

Braze の公開 API には、セレクション一覧を取得するエンドポイントがありません。セレクションの定義は、Braze Dashboard と既存の設定を参照して確認してください。

### 2. Braze のアイテムをエクスポートする

`GET /catalogs/{catalog_name}/items` を呼び出し、`Link` ヘッダーから `rel="next"` がなくなるまで、50 件ずつ取得します。エクスポートした JSON とアイテム数は、変更前のデータを確認できる原本として保管してください。

移行ファイルは暗号化されたストレージに保存し、作業担当者には必要最小限のアクセス権だけを付与します。保管期間を決め、検証とロールバックの期間が終了したら削除してください。個人を識別できる情報が見つかった場合は、移行を中断し、ファイルを隔離します。該当フィールドを削除するか、ユーザー属性に分離してから移行を再開してください。ファイルの内容や認証情報を、チケット、チャット、アプリケーションログに貼り付けないでください。

### 3. Notifly のカタログを作成する

Braze のカタログ定義に `data_classification: "non_personal"` を追加し、`POST /v1/projects/{projectId}/catalogs` で作成します。同じ名前で再作成すると競合するため、再実行する前にカタログがすでに作成されていないか確認してください。

### 4. アイテムをインポートする

移行が完了するまでは、Braze を正本として扱います。エクスポートしたアイテムを最大 50 件ずつに分け、リクエスト本文が 4 MiB に近づく場合は、さらにバッチを小さくします。

全件コピーを繰り返す必要がある場合は、一括 `PUT /catalogs/{catalogName}/items` を使用してください。同じ ID のアイテムは全置換し、存在しない ID は新規作成します。新規アイテムだけを許可し、重複をエラーにする必要がある場合に限り、`POST` を使用してください。

バッチごとに、カタログ名、メソッド、ソート済みのアイテム ID、アイテム数、リクエスト本文のハッシュ、開始時刻と完了時刻、結果ステータスをチェックポイントに記録します。1 リクエスト内の変更はトランザクションとして処理されるため、`200` レスポンスを受け取ってから完了として記録してください。

レスポンスを受信できなかった場合や `500` が返された場合は、同じ `POST` をすぐに再送しないでください。単件の `GET /items/{itemId}` でバッチ内のアイテムが反映済みか確認し、未反映のアイテムだけを再送します。`PUT` は、リクエスト本文全体を再適用できます。再試行には、ランダムな待ち時間を加えた指数バックオフを使用し、次のように処理してください。

* `401` の場合は、認証トークンを再発行してから再試行します。
* ネットワークタイムアウトまたは `500` の場合は、反映状況を確認してから、回数を制限して再試行します。
* `400`、`403`、`404`、`409`、`413` の場合は、入力、権限、対象リソース、重複、バッチサイズを修正するまで自動再試行しません。

### 5. セレクションを再作成する

アイテムの読み込みが完了したら、調査時に記録したセレクションを `POST /catalogs/{catalogName}/selections` で 1 件ずつ作成します。Braze のリクエストから `external_id` と `source` を削除し、フィールドの型ごとの演算子規則と `null` の制限を適用してください。

`200` レスポンスを受け取った後、セレクション名とリクエストのハッシュをチェックポイントに記録します。Notifly の公開 API には、セレクションの一覧取得や更新のエンドポイントがありません。タイムアウトで結果が不明な場合は、まずそのセレクションを使用する Liquid をテストし、存在するか、期待どおりの結果が返るかを確認してください。定義が誤っている場合に限り、影響範囲を確認したうえで `DELETE` し、再作成します。

その後、アイテムやフィールドを変更すると、保存済みのセレクション結果は同じリクエスト内で再計算されます。

### 6. 移行結果を検証する

* Notifly の `GET /catalogs` が返す `num_items` と、Braze からエクスポートしたアイテム数が一致することを確認します。
* すべてのページを再取得し、ID の集合、リクエスト本文のハッシュ、主要フィールドの値を比較します。
* メッセージのプレビューで、本番で使用している Liquid を実行します。
* 存在しない ID、空の配列、`null`、ハングル、絵文字、`time`、`geo`、object、array の値など、境界ケースを確認します。
* セレクションごとのアイテム数と並び順を比較します。並び順を指定していないセレクションの結果はランダムなため、同じ順序になることは期待しないでください。
* 未解決のバッチやセレクションのチェックポイントが残っていないことを確認します。

### 7. 呼び出し先を切り替える

1. 読み取りとメッセージのレンダリングには、引き続き Braze を使用します。書き込みは先に Braze に適用し、同じ変更を Notifly に送信します。Notifly への書き込みに失敗した場合は、再処理キューに記録します。
2. 事前に決めた観察期間中に、アイテム数、ハッシュ、主要な値、セレクション結果、API エラーを比較します。
3. 不一致と未解決の再処理がなくなったら、読み取り先とメッセージの Liquid を Notifly に切り替えます。
4. 切り替え後に不一致、継続的な API エラー、Liquid のレンダリングエラーが発生した場合は、読み取り先を Braze に戻します。Notifly のみに対する書き込みを停止し、チェックポイントから再同期します。
5. ロールバック期間が終了し、両システムの一致が続いていれば、Braze への書き込みを停止します。
6. Braze Catalogs の削除は、別途承認を得て、バックアップを確認してから実行します。

> [!WARNING]
>
> 移行中に Braze Catalogs を先に削除しないでください。Notifly のアイテム数、主要な値、Liquid のレンダリングを検証した後、
> 別の変更作業として削除してください。

## Liquid を移行する

基本的な構文は同じため、カタログ名とフィールド名を維持していれば、多くの場合はそのまま使用できます。

```liquid theme={null}
{% catalog_items products {{ user["favorite_product_id"] }} %}
{% if items.size > 0 %}
  {{ items[0].name }} - {{ items[0].price }}원
{% endif %}
```

```liquid theme={null}
{% catalog_selection_items products sale-products %}
{% for item in items %}
  {{ item.name }}
{% endfor %}
```

> [!WARNING]
>
> Braze で `:rerender` の対象値に別の `catalog_items` または `catalog_selection_items` タグを含めている場合は、
> 移行前にそのタグを削除するか、1 階層に展開してください。Notifly は、再帰的なカタログタグをレンダリングエラーとして扱います。

Liquid の構文が共通していても、API レスポンスが同じという意味ではありません。Catalog REST クライアントの認証、URL、ステータスコード処理、レスポンスの解析は、前述の違いに合わせて個別に修正してください。

## 公式参考資料

* [Braze Catalog API](https://www.braze.com/docs/api/endpoints/catalogs)
* [Braze: Create catalog](https://www.braze.com/docs/api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog)
* [Braze: List multiple catalog item details](https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk)
* [Braze: Create catalog items in bulk](https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/asynchronous/post_create_catalog_items_bulk)
* [Braze: Create catalog selection](https://www.braze.com/docs/api/endpoints/catalogs/catalog_selections/asynchronous/post_create_catalog_selections)
* [Braze API のレート制限](https://www.braze.com/docs/api/api_limits)
* [Notifly カタログガイド](https://docs.notifly.tech/ja/user-guide/catalogs/guide.md)
* [Catalog REST APIを使い始める](https://docs.notifly.tech/ja/api-reference/catalogs/getting-started.md)


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