联盟营销对接指南(Affiliate Integration)

平台内置完整的推广归因 → 订单转化 → 佣金账本 → 提现闭环,并为对接外部联盟营销网络预留了两级扩展点(Webhook 事件外推 + 静态适配器)。

1. 内置闭环(开箱即用)

| 环节 | 机制 |

|---|---|

| 推广链接 | /go/<推广码>:记录点击、写入 llx_ref cookie(默认 30 天,后台可调),302 跳转到落地页 |

| 归因 | 落地页 URL 带 ?ref=<推广码> 或存在 ref cookie 时,新邮箱创建即绑定 mailboxes.ref_code,并记入 referrals |

| 转化 | 订单系统调 POST /api/orders 建单,支付成功后调 POST /api/orders/pay |

| 佣金 | 支付回调时按订单邮箱回溯归因,按后台配置的佣金比例自动生成 commissions(pending) |

| 结算 | 后台 → 联盟营销:批准/标记已付/作废;/api/withdrawals 提现并校验已付余额 |

| 统计 | 后台报表:每个推广码的点击数/带来的邮箱/转化率/佣金;GET /api/affiliate/summary |

2. API(全部需 `X-API-Key`,后台设置页查看/轮换)

POST /api/orders
  {order_id, email, amount, product}
  → {success, order:{status:"created"}}

POST /api/orders/pay
  {order_id}
  → {success, order:{status:"paid"}, commission:{ref_code, commission, status:"pending"}|null}

POST /api/withdrawals
  {ref_code, amount}          # 只能提取"已付"佣金减去在途提现后的余额
  → {success, withdrawal}

GET  /api/affiliate/summary   → 点击/推广/佣金/提现汇总

POST /api/inbound             # 邮件接收(第三方解析服务或自建网关回调)
  {to, from, from_name, subject, text, html,
   attachments:[{filename, content_type, content_base64}]}

3. Webhook 事件外推(推荐对接方式)

后台 → 联盟营销 → 填写 Webhook 回调 URL 后,平台会把关键事件 POST 给联盟网络/你自己的中台:

POST <回调URL>
X-LLX-Event: order.paid | withdrawal.requested
X-LLX-Signature: sha256(webhook_secret + raw_body)
{
  "event": "order.paid",
  "ts": 1792050703,
  "data": {
    "order": {"id":"...","email":"...","amount":19.9,"product":"vip","status":"paid"},
    "commission": {"ref_code":"AFF1","commission":1.99,"status":"pending", ...},
    "ref_code": "AFF1"
  }
}

对接方(如 Ahrefs 式 SaaS 联盟、CPS 网络、自研中台)按 X-LLX-Signature 验签即可安全消费;通常只需处理 order.paid 做转化回传。

4. 静态适配器(进程内扩展)

src/adapters/index.js 内已给出模板:

ahrefs_style(默认关闭):拿到联盟网络 API 凭据后,把 onEvent 里的 TODO 替换成其转化回传 API 调用,enabled: true。
webhook_generic:本地日志占位。

新增网络 = 新增一个导出 {name, enabled, onEvent(event, data)} 的文件并在 ADAPTERS 注册,无需改核心代码。

5. 归因边界(与行业惯例一致)