mcpField
B
bambuser-api

bambuser-api

github.com/sanderkorf营销与增长065 次安装13 周前更新
代码仓库

关于 bambuser-api

bambuser-api 是用于服务端自动化的 Bambuser Live REST API 操作技能，涵盖直播节目、商品、用户、Webhook 和统计数据。它还说明区域 API 地址、Token 认证及与播放器 SDK、商品目录 feed 的边界。

主要功能

  1. 01管理节目及关联资源
  2. 02查询和维护商品
  3. 03创建并核验 Webhook
  4. 04获取节目与流量统计
  5. 05按区域配置 API 与 Token 认证

适用场景

  1. 01同步节目字段到 CMS
  2. 02自动化节目和商品管理
  3. 03接收并核验 Webhook 事件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sanderkorf/skills --skill bambuser-api

安装后在 Claude Code 中输入/bambuser-api确认已加载。

附带文件reference/endpoints.mdreference/models.md

详细介绍

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。商品目录 Feed 身份验证（通常使用 Bearer 和 Feed 密钥）是用于不同接口的另一种凭据。

速率限制

默认值：每 10 秒 5 个请求（滑动窗口）。超出限制 → HTTP 429。部分端点可能注明更严格的限制；否则按默认值处理。请退避并重试。

资源（概览）

区域常见操作
直播场次列出／创建／获取／修补／删除；商品（包括批量添加）；精彩片段（Beta）；聊天／置顶评论；素材；标签；频道；直播；转录文本
商品列出／获取／修补／删除；精选商品和外观查询
Webhook创建订阅；通过 eventId 获取事件以验证投递
统计数据单场／多场／活动／流量／订单
用户／标签／频道邀请／列出／更新；标签 CRUD；创建／获取频道

完整表格：reference/endpoints.md。

直播场次模型（CMS 同步）

重要的 Show 字段（参见 models）。同步时常见的 CMS 字段名称：

Bambuser说明
id稳定的直播场次 ID → 例如 bambuserShowId
title / descriptionBamHub 文案 → 例如 bambuserTitle / bambuserDescription
stateupcoming | scheduled | live | ended
published / isTestShow店铺列表：published && !isTestShow
scheduledStartAt / startedAt / endedAt / createdAtISO 日期时间
preview预览图片 URL → 例如 previewUrl
allowArchivedPlayback / isArchived / showLengthSeconds播放／归档标记

商品

ProductModel：必需字段为 publicUrl；可选字段包括 productReference、title、thumbnail、brand。

productReference 是外部商品目录标识（SKU／商品 ID），应与 BamHub 商品目录 Feed 使用的标识一致。商品目录同步优先使用商品目录 Feed 和 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
商品目录 FeedBamHub 商品目录导入；通常使用 Bearer Feed 密钥，而非 Token API 密钥
CMS 同步可选——在项目需要时将直播场次字段映射到 CMS 文档

请勿在店铺客户端组件中调用 REST API。请勿将 Token API 密钥与 Feed 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（或同类工具）。

评论

支持 Markdown