# BayAIU Partner API · 一键集成说明书(交给你的 AI 编程助手)

> **给人类的使用方法**:把这份文件**整个**发给你产品代码仓库里的 AI 编程助手(Claude Code / Cursor / Copilot Workspace 等),然后说:
> **"按这份说明书,把 BayAIU 课程分销集成进我的产品。"**
> 你只需要准备一样东西:你的 API Key(下面第 0 步)。其余全部由 AI 助手完成。

---

## 0. 人类要先准备的(2 分钟)

1. 登录 **https://bayaiu.ai/affiliate** → 找到 "BayAIU Partner API" 面板 → 点 **Generate API key**。
2. 复制 `bk_live_` 开头的密钥(**只显示一次**,存好)。
3. 把密钥交给 AI 助手时说明:"这是 BAYAIU_API_KEY,只能放服务端环境变量。"

---

## 1. 给 AI 编程助手的任务说明

你是集成工程师。请在当前产品里接入 BayAIU 课程分销:展示 BayAIU 的在售课程,用户点购买后跳转到 BayAIU 托管的 Stripe 结账页;每笔成交自动归因给本伙伴并计佣。**完成后向人类汇报你改了哪些文件、怎么测试。**

### 1.1 硬性安全规则(违反任何一条都算集成失败)

- **API Key 只存服务端环境变量 `BAYAIU_API_KEY`**——绝不写进前端代码、绝不提交进仓库、绝不出现在浏览器网络请求里。所有对 BayAIU 的调用都从你的服务端发起。
- **价格永远来自 API 返回值**——不要在本地写死任何价格数字;展示时用 `price_cents / 100` 格式化。
- **不要修改、拼接或代收任何款项**——收款方是 BayAIU 的 Stripe,你的产品只负责跳转。
- 买家邮箱(`student_email`)必填:在跳转前向用户收集,或用你产品里已登录用户的邮箱。

### 1.2 API 规格

- **Base URL**: `https://bayaiu.ai/api/v1`
- **认证**: 每个请求带头 `Authorization: Bearer ${BAYAIU_API_KEY}`
- **格式**: 全部 JSON;错误统一为 `{ "error": { "code": "...", "message": "..." } }`

#### GET /courses — 可售课程目录

响应(数组按价格升序):

```json
{
  "data": [
    {
      "slug": "opcs-2026-online",
      "title": "OPCS — One Person Companies (Online)",
      "short_title": "OPCS",
      "price_cents": 19900,
      "currency": "usd",
      "cohort_start": "2026-06-25T01:30:00+00:00",
      "hours": 16,
      "delivery_mode": "in_platform",
      "seats_left": 42,
      "enabled_for_you": true,
      "your_commission_rate": 0.2,
      "student_discount_rate": 0.1
    }
  ]
}
```

要点:只展示 `enabled_for_you === true` 且 `seats_left > 0` 的课程;`student_discount_rate` 是**你的用户能享受的折扣**(如 0.1 = 结账自动九折),可以作为卖点角标展示("通过本站购买享 10% 折扣")。

#### POST /checkout-sessions — 创建托管结账(核心)

请求体:

```json
{
  "course_slug": "opcs-2026-online",
  "student_email": "buyer@example.com",
  "success_url": "https://你的产品域名/bayaiu/thanks",
  "cancel_url": "https://你的产品域名/courses"
}
```

成功响应(201):

```json
{
  "id": "cs_live_…",
  "url": "https://checkout.stripe.com/c/pay/…",
  "course_slug": "opcs-2026-online",
  "student_email": "buyer@example.com",
  "discount_rate_applied": 0.1,
  "expires_at": "2026-07-15T12:00:00.000Z"
}
```

拿到 `url` 后把用户 302 重定向(或新窗口打开)过去。归因已写死在订单里,**不依赖 cookie**。

错误码 → 给用户的提示:

| code | HTTP | 用户提示 |
|---|---|---|
| `invalid_student_email` | 400 | 请填写有效邮箱 |
| `course_not_found` / `course_not_open` | 404/400 | 该课程暂不可售(刷新目录) |
| `cohort_full` | 409 | 本期已满员 |
| `already_enrolled` | 409 | 这个邮箱已拥有该课程 |
| `self_referral` | 403 | (不应发生:伙伴本人邮箱不能购买) |
| `rate_limited` | 429 | 稍后再试(每小时限 30 次创建) |
| `unauthorized` | 401 | (检查 BAYAIU_API_KEY 配置) |

#### GET /commissions — 佣金流水(可选,做伙伴后台用)

`?status=pending|approved|paid`;响应含 `data[]`(每条:金额/币种/费率快照/状态/解冻日期/课程 slug)和 `totals_cents`。状态机:成交 → `pending`(冻结 45 天,覆盖退款期)→ `approved` → 月度结算 `paid`;退款自动 `reversed`。

#### GET /me — 本伙伴条款(可选)

返回你的佣金率、层级(standard/core/board)、累计归因成交额、距自动升级 25% 的差额。

### 1.3 要实现的三件事

**① 服务端代理:课程目录**
新建服务端接口 `GET /api/bayaiu/courses`(按你产品的框架惯例放置):调用 BayAIU `GET /courses`,**缓存 5 分钟**(内存或你已有的缓存层),过滤 `enabled_for_you && seats_left > 0` 后返回给前端。前端永远不直连 bayaiu.ai。

**② 前端:课程展示组件**
在人类指定的页面(没指定就问)渲染课程卡片:课程名、价格(`$${(price_cents/100).toFixed(0)}`)、开课日期(本地化)、剩余席位、折扣角标(若 `student_discount_rate > 0`)、"立即报名"按钮。样式跟随你产品现有设计系统。

**③ 服务端:创建结账 + 跳转**
新建服务端接口 `POST /api/bayaiu/checkout`,入参 `{ course_slug, email }`(email 来自表单或登录态):调用 BayAIU `POST /checkout-sessions`(success_url/cancel_url 指向你产品的相应页面),把返回的 `url` 交给前端跳转。按上表映射错误提示。

**Node/Next.js 参考实现**(其他栈请等价翻译):

```ts
// lib/bayaiu.ts — 服务端专用,BAYAIU_API_KEY 来自环境变量
const BASE = "https://bayaiu.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.BAYAIU_API_KEY}`,
  "Content-Type": "application/json",
};

export async function bayaiuCourses() {
  const r = await fetch(`${BASE}/courses`, { headers, next: { revalidate: 300 } });
  if (!r.ok) throw new Error(`bayaiu courses ${r.status}`);
  const { data } = await r.json();
  return data.filter((c: any) => c.enabled_for_you && c.seats_left > 0);
}

export async function bayaiuCheckout(courseSlug: string, email: string, origin: string) {
  const r = await fetch(`${BASE}/checkout-sessions`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      course_slug: courseSlug,
      student_email: email,
      success_url: `${origin}/bayaiu/thanks`,
      cancel_url: `${origin}/courses`,
    }),
  });
  const j = await r.json();
  if (!r.ok) return { error: j.error?.code ?? "unknown" };
  return { url: j.url as string };
}
```

### 1.4 合规要求(必须照做,写进页面)

1. 课程展示区附近放一行披露:**"本站为 BayAIU 认证合作伙伴,通过本页购买我们将获得佣金"**(FTC 要求);
2. **禁止任何收入承诺话术**("学完月入 X 万"之类)——违反将被终止合作并冻结佣金;
3. 不得抓取/存储 BayAIU 学员数据;你只保留自己用户的邮箱。

### 1.5 验收清单(AI 助手自测后向人类汇报)

- [ ] `BAYAIU_API_KEY` 只出现在服务端环境变量(grep 全仓库确认无明文);
- [ ] 课程页能渲染真实目录(价格/日期来自 API,无写死价格);
- [ ] 点购买 → 输入邮箱 → 跳转到 checkout.stripe.com 页面(**不要真的付款**);
- [ ] `already_enrolled` / `cohort_full` 错误有友好提示;
- [ ] FTC 披露文案已上页面;
- [ ] 向人类汇报:改动文件清单 + 如何配置环境变量 + 如何测试。

---

## 2. 结算说明(给人类)

佣金月结,起付 $50:美国伙伴走 Stripe Connect(建设中,当前手动);中国大陆伙伴走 Wise→支付宝/银联,或**佣金抵课费(1:1.1,每 $100 佣金抵 $110 课费)**。结算前需提交 W-9(美国)/ W-8BEN(非美)。问题联系 contact@bayaiu.ai。

*BayAIU Partner API v1 · 文档主页 https://bayaiu.ai/partner-api · 本文件可直接转发*