View Categories

推广转化事件回传

当被邀请用户在你的产品内完成注册、付费或其他关键转化后，可通过本接口将事件回传给 PartnerShare，完成推广归因、奖励计算、佣金统计和后续数据沉淀。

1. 适用场景 #

注册事件用户完成注册后立即回传，用于建立推广归因关系与受邀用户关系。
付费事件用户完成支付、下单或订阅后回传，用于计算金额类奖励、佣金或转化收益。
自定义事件如激活、升级、续费、达标等业务动作，也可作为转化事件统一回传。
奖励与结算事件上报成功后，PartnerShare 会按活动规则完成奖励统计、效果归因和后续分佣结算。

2. 接口信息 #

项目说明
请求方式POST
接口路径/api/open/v1/track/conversion
请求域名https://api-service.partnershare.net
请求格式application/json
鉴权方式X-Api-Key + X-Api-Timestamp + X-Api-Sign
接口作用品牌方服务端在用户完成注册、付费或其他业务转化后，向 PartnerShare 回传转化结果，用于归因、奖励计算、效果统计与佣金结算。

3. 请求头 #

Header必填说明
X-Api-Key是PartnerShare 分配的 API Key
X-Api-Timestamp是秒级时间戳
X-Api-Sign是基于请求参数、时间戳和 API Secret 生成的签名
Content-Type是固定为 application/json
签名算法请参考《API 鉴权与签名机制》。建议所有转化事件都由服务端发起，不要在前端暴露 API Secret。

4. 请求参数 #

4.1 归因参数 #

PartnerShare 需要先确认“这次转化由哪位推广者带来”。对外接入仅保留以下两种归因方式，二选一即可，推荐优先传 click_id。

参数名类型是否必填说明
click_idstring二选一点击追踪 ID，通常来自落地页 Cookie 中的 ps_click_id，归因精度更高，推荐优先使用
invite_codestring二选一推广邀请码，通常来自落地页参数或 Cookie 中的 ps_ref，适用于无法获取 click_id 的场景
如果同时具备 click_id 和 invite_code，建议优先回传 click_id，这样归因链路会更稳定。

4.2 事件参数 #

参数名类型是否必填说明
event_namestring是事件名称。推荐使用 signup 表示注册事件，使用 purchase 表示付费事件；如有扩展业务场景，也可传自定义事件名称
对外接入时只需传 event_name 即可，建议直接使用统一的业务事件名，便于前后端、运营和财务团队共同理解。

4.3 用户参数 #

参数名类型是否必填说明
invited_user_idstring重要被邀请用户在品牌方系统内的唯一 ID。注册事件建议必传；后续付费或自定义事件也建议保持一致传入，便于识别同一用户
invited_user_namestring否被邀请用户展示名称，便于数据查看与运营排查
对于付费或自定义事件，如果同一用户此前已经成功上报过注册事件，且本次请求未携带 click_id 或 invite_code，PartnerShare 会优先根据该用户历史注册事件中已确认的归因关系，自动补全本次转化的推广归属。

4.4 交易参数（付费事件常用） #

参数名类型是否必填说明
transaction_idstring强烈建议交易单号或业务订单号，用于去重与追溯
conversion_valuefloat按规则而定转化金额。若奖励规则按比例结算，则该字段必须传
transaction_cycle_countint否分期奖励时可传分期次数，例如 12

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": "注册事件上报成功",
  "data": {
    "conversion_id": 1024,
    "campaign_id": 145,
    "affiliate_id": 204,
    "event_type": 1,
    "event_name": "signup",
    "status": 1
  }
}

6.2 失败响应 #

{
  "code": 6000000,
  "message": "该转化事件已存在",
  "data": null
}

7. 错误码说明 #

错误码说明
0请求成功
1000004鉴权失败，例如 API Key 无效、签名错误、时间戳过期或请求 IP 不在白名单内
1000005请求参数或业务前置条件校验失败，具体原因请查看 message
6000000业务校验失败，例如转化事件重复上报，具体原因请查看 message
业务异常统一返回 HTTP 200，请始终以响应体中的 code 判断调用是否成功，code = 0 才表示处理成功。

8. 接入注意事项 #

注册事件建议在用户注册成功后立即回传，不要延迟到登录或资料完善阶段。
付费事件必须在同一用户的注册事件成功上报后再提交；如同时传入 click_id 或 invite_code，必须与注册事件的归因信息一致。
付费事件如需严格去重，请务必传 transaction_id；若使用按比例奖励，请同时传 conversion_value。
若付费事件没有携带 click_id 或 invite_code，请确保该用户此前已经成功上报过注册事件，否则无法补全归因。
在业务允许的情况下，建议全链路保留 ps_click_id 与 ps_ref，这样注册和付费事件都能获得更稳定的归因结果。
更新 19/08/2026