推广转化事件回传

1. 接口信息 #

2. 请求头 #

3. 请求参数 #

3.1 归因参数 #

用于确定本次转化由哪位推广者带来。两个参数二选一，优先传 click_id。

3.2 事件参数 #

自定义事件名需先在品牌主后台「产品管理 → 转化事件」中完成定义并启用，且在活动中关联奖励规则后才会生效。未完成配置时，事件仍会被记录，但不会产生奖励。

3.3 用户参数 #

3.4 交易参数 #

4. 归因规则 #

• 同时具备 click_id 和 invite_code 时，优先按 click_id 归因。
• 付费或自定义事件未携带归因参数时，按该用户此前注册事件已确认的归因关系自动补全；该用户没有注册事件记录则无法归因。
• 付费事件携带的 click_id 或 invite_code 需与注册事件的归因一致。
• 注册事件应在用户注册成功后立即回传，付费事件应在同一用户注册事件回传成功后再提交。

5. 请求示例 #

5.1 注册事件 #

{
  "click_id": "clk_7f8c0d1a2b3c",
  "invite_code": "LN088",
  "event_name": "signup",
  "invited_user_id": "user_10001",
  "invited_user_name": "Tom"
}

5.2 付费事件 #

{
  "click_id": "clk_7f8c0d1a2b3c",
  "event_name": "purchase",
  "invited_user_id": "user_10001",
  "transaction_id": "order_202604220001",
  "conversion_value": 99.9
}

6. 响应 #

6.1 成功 #

{
  "code": 0,
  "message": "Signup event reported successfully",
  "data": {
    "conversion_id": 1024,
    "campaign_id": 145,
    "affiliate_id": 204,
    "event_type": 1,
    "event_name": "signup",
    "status": 1
  }
}

6.2 响应字段 #

6.3 失败 #

{
  "code": 6000000,
  "message": "A conversion event with the same business identifier already exists",
  "data": null
}

7. 错误码 #

业务失败返回 HTTP 200，以 code 判断结果，0 为成功。

8. 接入注意事项 #

• 注册事件在用户注册成功后立即回传，不要延后到登录或资料完善阶段。
• 付费事件传入唯一的 transaction_id，否则同一用户的第二笔付费会被判定为重复；按比例奖励时同时传 conversion_value。
• 付费事件未携带归因参数时，确保该用户此前已成功回传注册事件。
• 全链路保留 ps_click_id 与 ps_ref，注册和付费事件都能获得稳定归因。前端参数的保存与透传见 推广点击跟踪 SDK 接入。