bambuser-api

Bambuser Live REST API

番組、商品、ユーザーおよび関連リソースを自動化するための HTTPS/JSON API です。サーバーサイド専用です。ブラウザーから呼び出さないでください。

リファレンス： エンドポイント · モデル

ベース URL

BamHub のリージョンに合わせてください。

リージョン	BamHub ホスト	API ベース URL
グローバル	https://lcx.bambuser.com/	https://liveshopping-api.bambuser.com/v1
ヨーロッパ	https://lcx-eu.bambuser.com/	https://liveshopping-api-eu.bambuser.com/v1

OpenAPI のデフォルトサーバーは EU です。プロジェクトの環境設定に別の指定がない限り、EU を優先してください。

認証

BamHub → Settings → Integrations → API Keys でキーを作成します。各エンドポイントに記載されたスコープを割り当ててください。

Authorization: Token YOURAPIKEYHERE

Bearer ではありません。商品カタログフィードの認証（多くの場合、フィードシークレットを使う Bearer）は、別の接続先で使用する別の認証情報です。

レート制限

デフォルトは 10 秒あたり 5 リクエスト（移動ウィンドウ）です。超過すると HTTP 429 が返されます。一部のエンドポイントでは、より厳しい制限が定められている場合があります。そうでない場合はデフォルトを想定してください。バックオフして再試行してください。

リソース（一覧）

領域	代表的な操作
番組	一覧／作成／取得／パッチ／削除、商品（バッチ追加を含む）、ハイライト（ベータ版）、チャット／ピン留めコメント、アセット、タグ、チャンネル、ブロードキャスト、文字起こし
商品	一覧／取得／パッチ／削除、注目商品、外観の参照
Webhook	サブスクリプションの作成、配信確認のためのイベント取得（eventId を使用）
統計	番組ごと／複数番組／アクティビティ／トラフィック／注文
ユーザー／タグ／チャンネル	招待／一覧／更新、タグの CRUD、チャンネルの作成／取得

全一覧：reference/endpoints.md。

番組モデル（CMS 同期）

重要な Show フィールドについては、モデルを参照してください。同期時の一般的な CMS フィールド名：

Bambuser	備考
id	安定した番組 ID → 例：bambuserShowId
title / description	BamHub の文面 → 例：bambuserTitle / bambuserDescription
state	upcoming | scheduled | live | ended
published / isTestShow	ストアフロントの一覧：published && !isTestShow
scheduledStartAt / startedAt / endedAt / createdAt	ISO 日時
preview	プレビュー画像の URL → 例：previewUrl
allowArchivedPlayback / isArchived / showLengthSeconds	再生／アーカイブのフラグ

商品

ProductModel：publicUrl は必須です。productReference、title、thumbnail、brand は任意です。

productReference は外部カタログの識別子（SKU／商品 ID）で、BamHub のカタログフィードが使用するものに合わせます。カタログ同期にはカタログフィードと BamHub を優先し、REST は番組への商品の紐付けと管理の自動化に使用してください。

Webhook

POST /webhooks（WRITE_WEBHOOKS）の本文：name、url、topics、headers（すべて必須）。

トピック： show · product · user · product-highlight · broadcast

イベントのペイロード：

{
  collection: 'show' | 'product' | 'user'
  action: 'add' | 'update' | 'remove'
  payload: object
  eventId: string
  timestamp: string // ISO
}

GET /webhooks/{eventId}（READ_WEBHOOKS）で送信元と内容を検証してください。

統合の境界

接続先	役割
Live REST API	このスキル — サーバーサイドの番組、Webhook、管理の自動化
埋め込み／プレーヤー SDK	ストアフロントプレーヤー、カート連携、商品の詳細データ取得 — bambuser-live を使用
商品 カタログフィード	BamHub のカタログ取り込み。多くの場合、Token API キーではなくフィードシークレットを Bearer で使用
CMS 同期	任意 — プロジェクトで行う場合、番組フィールドを CMS ドキュメントにマッピング

ストアフロントのクライアントコンポーネントに REST 呼び出しを含めないでください。Token API キーとフィードの Bearer シークレットを混同しないでください。

Fetch テンプレート

const BAMBUUSER_API_BASE =
  process.env.BAMBUUSER_API_BASE ?? 'https://liveshopping-api-eu.bambuser.com/v1'

async function bambuserFetch<T>(
  path: string,
  init: RequestInit & { apiKey: string },
): Promise<T> {
  const { apiKey, ...rest } = init
  const response = await fetch(`${BAMBUUSER_API_BASE}${path}`, {
    ...rest,
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      Authorization: `Token ${apiKey}`,
      ...rest.headers,
    },
  })

  if (response.status === 429) {
    throw new Error('Bambuser rate limit (429). Back off and retry.')
  }

  if (!response.ok) {
    const body = await response.text()
    throw new Error(`Bambuser ${response.status}: ${body}`)
  }

  if (response.status === 204) {
    return undefined as T
  }

  return (await response.json()) as T
}

// Example: get show
// await bambuserFetch<Show>(`/shows/${showId}`, { method: 'GET', apiKey })

CMS またはドメイン型にデータを永続化する際は、システム境界で Zod（または同等のもの）を使用してください。