---
title: "推广转化事件回传"
id: "582"
type: "docs"
slug: "event-report"
published_at: "2026-01-07T06:18:07+00:00"
modified_at: "2026-08-19T09:55:08+00:00"
url: "https://www.partnershare.net/help/api/event-report"
markdown_url: "https://www.partnershare.net/help/api/event-report.md"
excerpt: "当被邀请用户在你的产品内完成注册、付费或其他关键转化后，可通过本接口将事件回传给 PartnerShare，完 […]"
taxonomy_doc_category:
  - "技术集成"
---

![快速入门 - PartnerShare](https://www.partnershare.net/wp-content/uploads/2026/01/lQLPJyGF1y8mfltQULD6hr47Eio3cwlDF3jyDucB_80_80.png)

## 快速入门

5

- [什么是推荐营销/老带新计划](https://www.partnershare.net/help/start-guides/referral-marketing)
- [什么是联盟营销](https://www.partnershare.net/help/start-guides/affiliate-marketing)
- [如何创建推荐计划](https://www.partnershare.net/help/start-guides/add-referral-marketing)
- [如何创建联盟营销活动](https://www.partnershare.net/help/start-guides/add-affiliate-marketing)
- [如何提升推广效果](https://www.partnershare.net/help/start-guides/improving-promotion-effectiveness)

![合作伙伴管理 - PartnerShare](https://www.partnershare.net/wp-content/uploads/2026/01/lQLPKHuo_8Hse9tQULBcxdOVHL3PdwlDF3jyDucC_80_80.png)

## 推广运营

5

- [活动管理](https://www.partnershare.net/help/promoters/%e6%b4%bb%e5%8a%a8%e7%ae%a1%e7%90%86)
- [产品管理](https://www.partnershare.net/help/promoters/%e4%ba%a7%e5%93%81%e7%ae%a1%e7%90%86)
- [推广者管理](https://www.partnershare.net/help/promoters/data)
- [合作伙伴支持的提现方式](https://www.partnershare.net/help/promoters/withdrawal-methods)
- [查询合作伙伴提现状态](https://www.partnershare.net/help/promoters/withdrawal-status)

![支付与交易 - ParterShare](https://www.partnershare.net/wp-content/uploads/2026/01/lQLPJwyP0mL5vltQULAn8_2d-Nx0hglDF3jyZ0QA_80_80.png)

## 支付与交易

2

- [佣金结算](https://www.partnershare.net/help/payment/commission)
- [提现托管功能](https://www.partnershare.net/help/payment/auto-payouts)

![合作伙伴管理 - PartnerShare](https://www.partnershare.net/wp-content/uploads/2026/01/lQLPKHuo_8Hse9tQULBcxdOVHL3PdwlDF3jyDucC_80_80.png)

## 账户管理

2

- [团队管理功能](https://www.partnershare.net/help/team/%e5%9b%a2%e9%98%9f%e7%ae%a1%e7%90%86%e5%8a%9f%e8%83%bd)
- [企业认证提示](https://www.partnershare.net/help/team/certification)

![技术集成 - PartnerShare](https://www.partnershare.net/wp-content/uploads/2026/01/lQLPJwDplrTBzltQULCNPWCeBswcaAlDF3jyZ0QB_80_80.png)

## 技术集成

5

- [API 鉴权与签名机制](https://www.partnershare.net/help/api/signature)
- [推广点击跟踪 SDK 接入](https://www.partnershare.net/help/api/sdk)
- [推广转化事件回传](https://www.partnershare.net/help/api/event-report)
- [将 PartnerShare 内嵌到产品中](https://www.partnershare.net/help/api/iframe)
- [PartnerShare 产品授权推广登录接入指南](https://www.partnershare.net/help/api/partnershare-integration)

![常见问题 - PartnerShare](https://www.partnershare.net/wp-content/uploads/2026/01/lQLPJwbpuanIXltQULBfzi8WsAsVUQlDF3jyDucA_80_80.png)

## 常见问题

2

- [旧版帮助中心入口](https://www.partnershare.net/help/faq/%e6%97%a7%e7%89%88%e5%b8%ae%e5%8a%a9%e4%b8%ad%e5%bf%83%e5%85%a5%e5%8f%a3)
- [提现相关](https://www.partnershare.net/help/faq/withdrawal)

![Image](https://www.partnershare.net/wp-content/uploads/2026/03/B706BBD1-A488-44A9-B7CC-AD90B607DD45-150x150.png)

## 更新日志

2

- [更新日志 – 2026.05.15](https://www.partnershare.net/help/update/%e6%9b%b4%e6%96%b0%e6%97%a5%e5%bf%97-2025-05-15)
- [更新日志-2026.03.05](https://www.partnershare.net/help/update/update2026-3-5)

View Categories

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

### 1. 适用场景 [#](#event-scenes)

**注册事件**用户完成注册后立即回传，用于建立推广归因关系与受邀用户关系。

**付费事件**用户完成支付、下单或订阅后回传，用于计算金额类奖励、佣金或转化收益。

**自定义事件**如激活、升级、续费、达标等业务动作，也可作为转化事件统一回传。

**奖励与结算**事件上报成功后，PartnerShare 会按活动规则完成奖励统计、效果归因和后续分佣结算。

### 2. 接口信息 [#](#event-api)

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

### 3. 请求头 [#](#event-headers)

| Header | 必填 | 说明 |
| --- | --- | --- |
| X-Api-Key | 是 | PartnerShare 分配的 API Key |
| X-Api-Timestamp | 是 | 秒级时间戳 |
| X-Api-Sign | 是 | 基于请求参数、时间戳和 API Secret 生成的签名 |
| Content-Type | 是 | 固定为 application/json |

签名算法请参考《API 鉴权与签名机制》。建议所有转化事件都由服务端发起，不要在前端暴露 `API Secret`。

### 4. 请求参数 [#](#event-params)

#### 4.1 归因参数 [#](#event-attribution)

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

| 参数名 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| click_id | string | 二选一 | 点击追踪 ID，通常来自落地页 Cookie 中的 ps_click_id，归因精度更高，推荐优先使用 |
| invite_code | string | 二选一 | 推广邀请码，通常来自落地页参数或 Cookie 中的 ps_ref，适用于无法获取 click_id 的场景 |

如果同时具备 `click_id` 和 `invite_code`，建议优先回传 `click_id`，这样归因链路会更稳定。

#### 4.2 事件参数 [#](#event-name)

| 参数名 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| event_name | string | 是 | 事件名称。推荐使用 signup 表示注册事件，使用 purchase 表示付费事件；如有扩展业务场景，也可传自定义事件名称 |

对外接入时只需传 `event_name` 即可，建议直接使用统一的业务事件名，便于前后端、运营和财务团队共同理解。

#### 4.3 用户参数 [#](#event-user)

| 参数名 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| invited_user_id | string | 重要 | 被邀请用户在品牌方系统内的唯一 ID。注册事件建议必传；后续付费或自定义事件也建议保持一致传入，便于识别同一用户 |
| invited_user_name | string | 否 | 被邀请用户展示名称，便于数据查看与运营排查 |

对于付费或自定义事件，如果同一用户此前已经成功上报过注册事件，且本次请求未携带 `click_id` 或 `invite_code`，PartnerShare 会优先根据该用户历史注册事件中已确认的归因关系，自动补全本次转化的推广归属。

#### 4.4 交易参数（付费事件常用） [#](#event-transaction)

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

### 5. 请求示例 [#](#event-example)

#### 5.1 注册事件示例 [#](#event-example-signup)

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

#### 5.2 付费事件示例 [#](#event-example-purchase)

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

### 6. 响应示例 [#](#event-response)

#### 6.1 成功响应 [#](#event-response-success)

```
{
  "code": 0,
  "message": "注册事件上报成功",
  "data": {
    "conversion_id": 1024,
    "campaign_id": 145,
    "affiliate_id": 204,
    "event_type": 1,
    "event_name": "signup",
    "status": 1
  }
}
```

#### 6.2 失败响应 [#](#event-response-fail)

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

### 7. 错误码说明 [#](#event-error)

| 错误码 | 说明 |
| --- | --- |
| 0 | 请求成功 |
| 1000004 | 鉴权失败，例如 API Key 无效、签名错误、时间戳过期或请求 IP 不在白名单内 |
| 1000005 | 请求参数或业务前置条件校验失败，具体原因请查看 message |
| 6000000 | 业务校验失败，例如转化事件重复上报，具体原因请查看 message |

业务异常统一返回 HTTP 200，请始终以响应体中的 `code` 判断调用是否成功，`code = 0` 才表示处理成功。

### 8. 接入注意事项 [#](#event-notes)

注册事件建议在用户注册成功后立即回传，不要延迟到登录或资料完善阶段。

付费事件必须在同一用户的注册事件成功上报后再提交；如同时传入 `click_id` 或 `invite_code`，必须与注册事件的归因信息一致。

付费事件如需严格去重，请务必传 `transaction_id`；若使用按比例奖励，请同时传 `conversion_value`。

若付费事件没有携带 `click_id` 或 `invite_code`，请确保该用户此前已经成功上报过注册事件，否则无法补全归因。

在业务允许的情况下，建议全链路保留 `ps_click_id` 与 `ps_ref`，这样注册和付费事件都能获得更稳定的归因结果。

更新 19/08/2026

###### 分享这篇文章 ：

- ![Image](https://www.partnershare.net/wp-content/plugins/betterdocs/assets/images/social/share-icon.svg?v=4.3.4)
- [https://www.facebook.com/sharer/sharer.php?u=https://www.partnershare.net/help/api/event-report](https://www.facebook.com/sharer/sharer.php?u=https://www.partnershare.net/help/api/event-report)
- [https://twitter.com/intent/tweet?url=https://www.partnershare.net/help/api/event-report](https://twitter.com/intent/tweet?url=https://www.partnershare.net/help/api/event-report)
- [https://www.linkedin.com/shareArticle?mini=true&url=https://www.partnershare.net/help/api/event-report](https://www.linkedin.com/shareArticle?mini=true&url=https://www.partnershare.net/help/api/event-report)
- [https://pinterest.com/pin/create/button/?url=https://www.partnershare.net/help/api/event-report](https://pinterest.com/pin/create/button/?url=https://www.partnershare.net/help/api/event-report)

[将 PartnerShare 内嵌到产品中](https://www.partnershare.net/help/api/iframe)
[推广点击跟踪 SDK 接入](https://www.partnershare.net/help/api/sdk)

大纲 - [1. 适用场景](#event-scenes)
- [2. 接口信息](#event-api)
- [3. 请求头](#event-headers)
- [4. 请求参数](#event-params)
  - [4.1 归因参数](#event-attribution)
  - [4.2 事件参数](#event-name)
  - [4.3 用户参数](#event-user)
  - [4.4 交易参数（付费事件常用）](#event-transaction)

- [5. 请求示例](#event-example)
  - [5.1 注册事件示例](#event-example-signup)
  - [5.2 付费事件示例](#event-example-purchase)

- [6. 响应示例](#event-response)
  - [6.1 成功响应](#event-response-success)
  - [6.2 失败响应](#event-response-fail)

- [7. 错误码说明](#event-error)
- [8. 接入注意事项](#event-notes)