---
title: "推广转化事件回传"
id: "582"
type: "docs"
slug: "event-report"
published_at: "2026-01-07T06:18:07+00:00"
modified_at: "2026-09-07T06:15:06+00:00"
url: "https://help-new-pro.partnershare.net/help/api/event-report"
markdown_url: "https://help-new-pro.partnershare.net/help/api/event-report.md"
excerpt: "被邀请用户在产品内完成注册、付费或其他关键转化后，由品牌方服务端调用本接口回传事件。 PartnerShare […]"
taxonomy_doc_category:
  - "技术集成"
---

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

## 快速入门

5

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

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

## 推广运营

5

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

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

## 支付与交易

2

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

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

## 账户管理

2

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

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

## 技术集成

8

- [API 鉴权与签名机制](https://help-new-pro.partnershare.net/help/api/signature)
- [推广转化事件回传](https://help-new-pro.partnershare.net/help/api/event-report)
- [推广点击跟踪 SDK 接入](https://help-new-pro.partnershare.net/help/api/sdk)
- [转化退款](https://help-new-pro.partnershare.net/help/api/conversion-refund)
- [转化作废](https://help-new-pro.partnershare.net/help/api/conversion-void)
- [将 PartnerShare 内嵌到产品中](https://help-new-pro.partnershare.net/help/api/iframe)
- [推广者资源接口](https://help-new-pro.partnershare.net/help/api/promoter-resources)
- [PartnerShare 产品授权推广登录接入指南](https://help-new-pro.partnershare.net/help/api/partnershare-integration)

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

## 常见问题

2

- [旧版帮助中心入口](https://help-new-pro.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://help-new-pro.partnershare.net/help/faq/withdrawal)

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

## 更新日志

2

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

View Categories

被邀请用户在产品内完成注册、付费或其他关键转化后，由品牌方服务端调用本接口回传事件。

PartnerShare 根据回传数据完成推广归因、奖励计算和佣金统计。

付费转化发生全额退款或被判定无效时，使用 [转化退款](https://www.partnershare.net/help/api/conversion-refund)
 或 [转化作废](https://www.partnershare.net/help/api/conversion-void)
 接口撤销对应奖励。

### 1. 接口信息 [#](#0-toc-title)

POST`/api/open/v1/track/conversion`

| 项目 | 说明 |
| --- | --- |
| 请求域名 | https://api-service.partnershare.net |
| 请求格式 | application/json |
| 鉴权 | X-Api-Key + X-Api-Timestamp + X-Api-Sign，算法见 API 鉴权与签名机制 |
| 支持的 API Key 版本 | v1、v2 |
| 调用方 | 品牌方服务端。API Secret 不得暴露在前端 |
| 去重 | 注册事件：同一产品下同一 invited_user_id 只接受一次。付费与自定义事件：传 transaction_id 时按 transaction_id 去重；未传时同一用户的同名事件只接受一次 |

### 2. 请求头 [#](#1-toc-title)

| Header | 必填 | 说明 |
| --- | --- | --- |
| X-Api-Key | 是 | 产品的 API Key |
| X-Api-Timestamp | 是 | 秒级 Unix 时间戳，300 秒内有效 |
| X-Api-Sign | 是 | 按密钥版本计算的签名 |
| Content-Type | 是 | application/json |

### 3. 请求参数 [#](#2-toc-title)

#### 3.1 归因参数 [#](#3-toc-title)

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

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| click_id | string | 二选一 | 点击追踪 ID，来自落地页 Cookie 中的 ps_click_id。归因精度最高 |
| invite_code | string | 二选一 | 推广邀请码，来自落地页参数或 Cookie 中的 ps_ref。无法获取 click_id 时使用 |

#### 3.2 事件参数 [#](#4-toc-title)

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event_name | string | 是 | 事件名称。注册事件传 signup，付费事件传 purchase，其他业务动作可传自定义事件名 |

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

#### 3.3 用户参数 [#](#5-toc-title)

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| invited_user_id | string | 是 | 被邀请用户在品牌方系统内的唯一 ID。注册事件必传；后续付费和自定义事件传入相同值，用于识别同一用户 |
| invited_user_name | string | 否 | 被邀请用户的展示名称，用于后台查看 |

#### 3.4 交易参数 [#](#6-toc-title)

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| transaction_id | string | 付费事件建议 | 交易单号或业务订单号，最长 255 字符。用于去重、追溯，以及后续退款或作废时定位转化 |
| conversion_value | number | 按规则 | 转化金额。奖励规则按比例结算时必传 |
| transaction_cycle_count | int | 否 | 分期奖励的分期次数，如 12 |

### 4. 归因规则 [#](#7-toc-title)

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

### 5. 请求示例 [#](#8-toc-title)

#### 5.1 注册事件 [#](#9-toc-title)

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

#### 5.2 付费事件 [#](#10-toc-title)

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

### 6. 响应 [#](#11-toc-title)

#### 6.1 成功 [#](#12-toc-title)

```
{
  "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 响应字段 [#](#13-toc-title)

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| conversion_id | int | 转化记录 ID |
| campaign_id | int | 归因到的活动 ID |
| affiliate_id | int | 归因到的推广者 ID |
| event_type | int | 1 注册，2 付费，3 自定义事件 |
| event_name | string | 事件名称 |
| status | int | 转化状态：1 待确认，2 已确认 |

#### 6.3 失败 [#](#14-toc-title)

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

### 7. 错误码 [#](#15-toc-title)

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

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

### 8. 接入注意事项 [#](#16-toc-title)

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

更新 07/09/2026

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

- ![Image](https://help-new-pro.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://help-new-pro.partnershare.net/help/api/event-report](https://www.facebook.com/sharer/sharer.php?u=https://help-new-pro.partnershare.net/help/api/event-report)
- [https://twitter.com/intent/tweet?url=https://help-new-pro.partnershare.net/help/api/event-report](https://twitter.com/intent/tweet?url=https://help-new-pro.partnershare.net/help/api/event-report)
- [https://www.linkedin.com/shareArticle?mini=true&url=https://help-new-pro.partnershare.net/help/api/event-report](https://www.linkedin.com/shareArticle?mini=true&url=https://help-new-pro.partnershare.net/help/api/event-report)
- [https://pinterest.com/pin/create/button/?url=https://help-new-pro.partnershare.net/help/api/event-report](https://pinterest.com/pin/create/button/?url=https://help-new-pro.partnershare.net/help/api/event-report)

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

大纲 - [1. 接口信息](#0-toc-title)
- [2. 请求头](#1-toc-title)
- [3. 请求参数](#2-toc-title)
  - [3.1 归因参数](#3-toc-title)
  - [3.2 事件参数](#4-toc-title)
  - [3.3 用户参数](#5-toc-title)
  - [3.4 交易参数](#6-toc-title)

- [4. 归因规则](#7-toc-title)
- [5. 请求示例](#8-toc-title)
  - [5.1 注册事件](#9-toc-title)
  - [5.2 付费事件](#10-toc-title)

- [6. 响应](#11-toc-title)
  - [6.1 成功](#12-toc-title)
  - [6.2 响应字段](#13-toc-title)
  - [6.3 失败](#14-toc-title)

- [7. 错误码](#15-toc-title)
- [8. 接入注意事项](#16-toc-title)