sale-tracking

用途

Sale Tracking 用于在客户完成付款后记录收入，使佣金能够归属到正确的推广合作伙伴（affiliate partner）。它解决的是“付款发生后如何把收入与推广来源关联起来”的问题。

主要能力

通过 Sale API 记录销售，适用于任意支付服务商。
通过 Stripe Checkout 的 metadata 传递归属信息，支持一次性付款与订阅。
提供 CLI 命令自动配置 Stripe webhook，并支持测试销售事件。

使用方式

方式 A：Sale API（任意支付服务商）

向以下端点发送 POST 请求：

POST https://api.affitor.com/api/v1/track/sale
Authorization: Bearer YOUR_PROGRAM_API_KEY
Content-Type: application/json

{
  "transaction_id": "txn_unique_id",
  "customer_key": "user_123",
  "amount_cents": 4900,
  "currency": "USD"
}

必填字段：

字段	类型	说明
transaction_id	string	每笔销售唯一（重复会返回 409）
amount_cents	number	以分为单位的正整数
customer_key 或 click_id	string	至少提供一个用于归属

Node.js 示例：

await fetch('https://api.affitor.com/api/v1/track/sale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AFFITOR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transaction_id: order.id,
    customer_key: currentUser.id,
    click_id: req.cookies.affitor_click_id,
    amount_cents: order.totalCents,
    currency: 'USD',
  }),
});

方式 B：Stripe Metadata

在 Stripe Checkout session 的 metadata 中加入以下字段：

const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'payment',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  metadata: {
    affitor_click_id: clickId,
    affitor_customer_key: currentUser.id,
    program_id: 'YOUR_PROGRAM_ID',
  },
});

订阅场景需在两处重复 metadata：

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  metadata: {
    affitor_click_id: clickId,
    affitor_customer_key: currentUser.id,
    program_id: 'YOUR_PROGRAM_ID',
  },
  subscription_data: {
    metadata: {
      affitor_click_id: clickId,
      affitor_customer_key: currentUser.id,
      program_id: 'YOUR_PROGRAM_ID',
    },
  },
});

若缺少 subscription_data.metadata，续费归属将失败。

方式 C：通过 CLI 自动配置 Stripe

npx affitor setup stripe

该命令通过 OAuth 自动配置所有 Stripe webhook，付款事件无需手动设置 metadata。

测试

npx affitor test sale

适用场景

使用任意支付服务商，需要在付款后记录销售并归属佣金。
使用 Stripe Checkout 处理一次性付款或订阅，需要将收入与推广来源关联。
希望通过 CLI 快速完成 Stripe webhook 配置。

限制

transaction_id 必须唯一，重复提交会返回 409。
amount_cents 必须为以分为单位的正整数。
归属至少需要 customer_key 或 click_id 之一。
订阅续费归属依赖 subscription_data.metadata，缺失会导致失败。
资料未提供收费、价格、平台支持范围及效果数据。