---
title: "PartnerShare 产品授权推广登录接入指南"
id: "1128"
type: "docs"
slug: "partnershare-integration"
published_at: "2026-04-22T02:33:47+00:00"
modified_at: "2026-08-19T09:55:08+00:00"
url: "https://www.partnershare.net/help/api/partnershare-integration"
markdown_url: "https://www.partnershare.net/help/api/partnershare-integration.md"
excerpt: "PartnerShare Integration Guide 产品授权推广登录接入指南 面向跨产品合作推广场景 […]"
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 Integration Guide

## 产品授权推广登录接入指南

面向跨产品合作推广场景，PartnerShare 统一承接授权中继、推广关系维护、授权码换码、注册事件归因与分佣结算，让推广方和被推广方以更低成本完成用户互通与增长闭环。

授权中继推广归因自动注册登录分佣结算

### 1. 概述 [#](#0-toc-title)

**能力定位**

PartnerShare 产品授权推广登录是一套面向跨产品合作推广场景的标准化授权中继能力。推广方产品在用户完成授权后，将用户授权信息提交至 PartnerShare，由 PartnerShare 自动生成携带推广关系的跳转链接和一次性授权码；被推广方产品通过授权码换取用户信息，完成自动注册或登录，并基于 `ps_ref` 回传注册事件，实现从用户跳转、授权登录、注册归因到推广分佣结算的完整闭环。

接入后，双方无需重复建设推广账号维护、授权换码、来源识别、归因统计和分佣结算等能力，可显著降低跨产品推广合作的开发成本、联调成本、运营成本和用户转化流失。

---

### 2. 核心概念 [#](#1-toc-title)

为便于理解接入流程，本文档统一使用以下概念：

| 概念 | 说明 |
| --- | --- |
| 推广方产品 | 发起授权并导流用户的一方。用户通常已在推广方产品内登录，完成授权后由推广方产品将用户跳转至被推广方产品。 |
| 被推广方产品 | 接收用户并完成注册或登录的一方。被推广方产品通过授权码向 PartnerShare 换取用户信息，并在完成注册后回传注册事件。 |
| PartnerShare | 授权中继与推广归因平台。负责生成授权码、维护推广关系、返回推广链接、校验授权码、接收注册事件，并支持后续推广分佣结算。 |
| 授权码 x_auth_code | PartnerShare 生成的一次性短时授权码，用于被推广方产品服务端换取授权用户信息，不可作为长期登录凭证使用。 |
| 推广邀请码 ps_ref | PartnerShare 生成或维护的推广归因标识，会随推广链接传递到被推广方产品，用于注册事件回传和推广效果归因。 |
| 授权用户 user_key | PartnerShare 返回的授权用户唯一标识。被推广方产品应基于 user_key 建立本地用户绑定关系。 |
| 推广链接 promotion link | PartnerShare 返回给推广方产品的跳转链接，通常指向被推广方产品落地页，并携带 ps_ref 和 x_auth_code。 |
| 注册事件 | 被推广方产品完成自动注册或首次有效转化后，向 PartnerShare 回传的事件，用于后续推广归因、数据统计和分佣结算。 |

---

### 3. 前置要求 [#](#2-toc-title)

在接入产品授权推广登录前，请先完成以下准备工作：

#### 3.1 注册 PartnerShare 品牌主后台账号 [#](#3-toc-title)

请先注册并登录 PartnerShare 品牌主后台：

[https://share.partnershare.com/nueshawu](https://share.partnershare.com/nueshawu)

![注册 PartnerShare 品牌主后台账号](https://help-new-pro.partnershare.net/wp-content/uploads/2026/04/01-register-partnershare-account-scaled.png)

注册 PartnerShare 品牌主后台账号

#### 3.2 完成产品基础配置 [#](#4-toc-title)

在 PartnerShare 后台创建并保存产品，按需完成产品基础信息、奖励规则、追踪集成、API 对接等配置。

![完成产品基础配置](https://help-new-pro.partnershare.net/wp-content/uploads/2026/04/02-product-basic-config-scaled.png)

完成产品基础配置

#### 3.3 填写推广 URL [#](#5-toc-title)

请务必在产品基础配置中填写 `推广 URL`。该地址是用户最终跳转到被推广方产品的落地页地址。PartnerShare 生成推广链接时，会在该地址上自动携带 `ps_ref` 和 `x_auth_code` 参数。

![填写推广 URL](https://help-new-pro.partnershare.net/wp-content/uploads/2026/04/03-product-promotion-url-scaled.png)

填写推广 URL

#### 3.4 创建联盟计划活动 [#](#6-toc-title)

被推广产品需要先在 PartnerShare 后台创建联盟计划活动。该活动用于承接推广方加入、推广关系生成、归因统计和后续分佣结算，也是产品授权推广登录链路生成有效推广落地链接的前置条件。

创建联盟计划活动时选择联盟计划（Affiliate）

#### 3.5 确认联盟计划活动已生成并处于进行中状态 [#](#7-toc-title)

联盟计划活动创建完成后，请确认该活动已在对应产品下生成，活动类型为联盟计划，并且活动处于进行中状态。后续推广方会基于该联盟计划活动申请推广，被推广产品也会通过该活动承接推广关系、归因统计和后续分佣结算。若活动未开始、已暂停或已结束，可能导致推广链接生成、注册归因或分佣结算无法正常完成。

确认联盟计划活动已生成

**前置检查重点**

`推广 URL`、联盟计划活动、活动状态是影响授权跳转和注册归因的关键配置。接口联调前建议优先确认这些配置已完成且状态正常。

---

### 4. 流程图 [#](#8-toc-title)

![产品授权推广登录流程图](https://help-new-pro.partnershare.net/wp-content/uploads/2026/04/product-oauth-flow-scaled.png)

产品授权推广登录流程图

---

### 5. 数据约定 [#](#9-toc-title)

#### 5.1 请求数据约定 [#](#10-toc-title)

除特殊说明外，本文档中的接口均遵循以下请求约定：

| 项目 | 约定 |
| --- | --- |
| HTTP Method | POST |
| Content-Type | application/json |
| 请求格式 | Raw JSON |
| 调用方式 | 建议由服务端发起调用，避免在前端暴露接口密钥或敏感参数 |

请求示例：

```
{
  "product_key": "your_product_key",
  "target_product_key": "target_product_key",
  "user_id": "your_user_id"
}
```

#### 5.2 响应数据约定 [#](#11-toc-title)

除特殊说明外，所有接口响应数据均为 JSON 格式，基础结构如下：

```
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 响应状态码，0 表示成功，非 0 表示失败 |
| message | string | 响应描述信息 |
| data | object / array / null | 响应数据，具体结构以各接口说明为准 |

成功响应示例：

```
{
  "code": 0,
  "message": "success",
  "data": {
    "code": "AUTH_CODE_EXAMPLE",
    "redirect_url": "https://example.com/landing?ps_ref=xxx&x_auth_code=AUTH_CODE_EXAMPLE"
  }
}
```

失败响应示例：

```
{
  "code": 1000004,
  "message": "API Key 或签名不能为空",
  "data": null
}
```

#### 5.3 URL 参数约定 [#](#12-toc-title)

当 PartnerShare 返回推广链接后，最终跳转到被推广方产品落地页时，URL 中会携带以下参数：

| 参数名 | 类型 | 说明 |
| --- | --- | --- |
| ps_ref | string | 推广邀请码，用于注册事件回传和推广归因 |
| x_auth_code | string | 一次性授权码，用于被推广方产品服务端换取授权用户信息 |

示例：

```
https://example.com/landing?ps_ref=abc123&x_auth_code=AUTH_CODE_EXAMPLE
```

#### 5.4 重要字段约定 [#](#13-toc-title)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| product_key | string | 推广方产品标识 |
| target_product_key | string | 被推广方产品标识 |
| user_id | string | 推广方产品内的用户唯一标识 |
| x_auth_code | string | 一次性授权码，用于换取授权用户信息 |
| ps_ref | string | 推广邀请码，用于注册事件归因 |
| user_key | string | PartnerShare 返回的授权用户唯一标识，被推广方产品应基于该字段建立本地用户绑定关系 |

---

### 6. 签名机制 [#](#14-toc-title)

为保证接口调用安全，PartnerShare 开放接口需要通过 API Key 和 API Secret 进行签名校验。所有签名参数均应由服务端生成，请勿在浏览器、移动端或小程序前端暴露 API Secret。参考链接：https://www.partnershare.net/help/api/signature

#### 6.1 获取 API Key 和 API Secret [#](#15-toc-title)

在 PartnerShare 后台进入：`产品管理` → `选择对接产品` → `开发者集成`，即可获取 API Key 和 API Secret。

![获取 API Key 和 API Secret](https://help-new-pro.partnershare.net/wp-content/uploads/2026/04/06-api-key-secret-scaled.png)

获取 API Key 和 API Secret

#### 6.2 请求头 [#](#16-toc-title)

调用接口时，请在请求头中携带以下参数：

| Header | 必填 | 说明 |
| --- | --- | --- |
| X-Api-Key | 是 | PartnerShare 分配给产品的 API Key |
| X-Api-Timestamp | 是 | 当前秒级时间戳 |
| X-Api-Sign | 是 | 按签名规则生成的签名 |
| Content-Type | 是 | 固定为 application/json |

#### 6.3 签名规则 [#](#17-toc-title)

签名生成规则如下：

1. 获取当前请求参数中的所有字段名。
2. 将字段名统一转换为小写。
3. 按字段名进行自然排序。
4. 使用 `&` 拼接排序后的字段名。
5. 在拼接结果后追加 `timestamp` 和 `api_secret`。
6. 对最终字符串进行 SHA256 计算，得到十六进制签名。

签名字符串格式：

```
字段名1&字段名2&字段名3 + timestamp + api_secret
```

示例请求参数：

```
{
  "product_key": "your_product_key",
  "target_product_key": "target_product_key",
  "user_id": "user_10001",
  "extra": {
    "locale": "zh"
  }
}
```

参与签名的字段名为：

```
product_key
target_product_key
user_id
extra
```

排序并拼接后：

```
extra&product_key&target_product_key&user_id
```

假设：

```
timestamp = 1776677721
api_secret = your_api_secret
```

最终待签名字符串为：

```
extra&product_key&target_product_key&user_id1776677721your_api_secret
```

对该字符串进行 SHA256 后，即可得到 `X-Api-Sign`。

#### 6.4 JavaScript 签名示例 [#](#18-toc-title)

```
function makeSign(params, timestamp, apiSecret) {
  const keys = Object.keys(params)
    .map((key) => key.toLowerCase())
    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));

  const signString = keys.join('&') + timestamp + apiSecret;

  return CryptoJS.SHA256(signString).toString(CryptoJS.enc.Hex);
}
```

#### 6.5 Go 签名示例 [#](#19-toc-title)

```
package main

import (
    "crypto/sha256"
    "fmt"
    "sort"
    "strings"
)

func MakeSign(params map[string]interface{}, timestamp string, apiSecret string) string {
    keys := make([]string, 0, len(params))
    for key := range params {
        keys = append(keys, strings.ToLower(key))
    }

    sort.Strings(keys)

    signString := strings.Join(keys, "&") + timestamp + apiSecret
    sum := sha256.Sum256([]byte(signString))

    return fmt.Sprintf("%x", sum)
}
```

#### 6.6 PHP 签名示例 [#](#20-toc-title)

```
<?php

function makeSign(array $params, string $timestamp, string $apiSecret): string
{
    $keys = array_map('strtolower', array_keys($params));
    sort($keys, SORT_NATURAL);

    $signString = implode('&', $keys) . $timestamp . $apiSecret;

    return hash('sha256', $signString);
}
```

#### 6.7 注意事项 [#](#21-toc-title)

- `X-Api-Timestamp` 请使用秒级时间戳。
- `X-Api-Sign` 必须由服务端生成。
- `api_secret` 仅用于服务端签名，不允许暴露在前端代码中。
- 参数字段名需要统一转为小写后再参与排序。
- 当前签名规则只使用参数字段名参与计算，不使用字段值参与计算。

---

### 7. 接口列表 [#](#22-toc-title)

本文档中的接口统一使用以下接口前缀：

```
/api/open/v1
```

所有接口的请求域名（Host）为：

```
https://api-service.partnershare.net
```

完整请求 URL 由请求域名 + 接口前缀 + 接口地址组成，例如`https://api-service.partnershare.net/api/open/v1/oauth/authorize`。

除特殊说明外，接口均需要按照“签名机制”章节携带鉴权请求头。

| Header | 必填 | 说明 |
| --- | --- | --- |
| Content-Type | 是 | 推荐使用 application/json。 |
| X-Api-Key | 是 | PartnerShare 分配给产品的 API Key。 |
| X-Api-Timestamp | 是 | 秒级时间戳。 |
| X-Api-Sign | 是 | 按签名规则生成的 SHA256 签名。 |

#### 7.1 生成推广授权链接 [#](#23-toc-title)

**接口说明**

推广方产品在用户完成授权后，调用该接口向 PartnerShare 提交用户授权信息。PartnerShare 会生成一次性授权码，并返回携带 `ps_ref` 与 `x_auth_code` 的推广链接。

该接口适用于推广方希望先获取跳转地址，再由自身业务控制跳转的场景。

**请求信息**

| 项目 | 内容 |
| --- | --- |
| 请求方式 | POST |
| 接口地址 | /api/open/v1/oauth/authorize |
| Content-Type | application/json |
| 调用方 | 推广方产品服务端 |

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| product_key | string | 是 | 推广方产品 key。 |
| target_product_key | string | 是 | 被推广方产品 key。 |
| user_id | string | 是 | 推广方产品内稳定的用户唯一标识。 |
| extra | object | 否 | 推广方传入的扩展用户信息，可用于被推广方补全用户资料。 |

**请求示例**

```
{
  "product_key": "your_product_key",
  "target_product_key": "target_product_key",
  "user_id": "source_user_001",
  "extra": {
    "user_name": "Demo User",
    "email": "demo@example.com",
    "locale": "zh"
  }
}
```

**响应参数**

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 一次性授权码，即跳转链接中的 x_auth_code。 |
| redirect_url | string | 被推广方产品落地页链接，已携带 ps_ref 与 x_auth_code。 |

**响应示例**

```
{
  "code": 0,
  "message": "success",
  "data": {
    "code": "2fwth3pfj8",
    "redirect_url": "https://target.example.com/landing?ps_ref=INVITE_CODE&x_auth_code=2fwth3pfj8"
  }
}
```

**注意事项**

- `product_key` 必须与当前 API Key 所属产品一致。
- 被推广方落地页需要接收并保留 `ps_ref` 与 `x_auth_code`。
- `x_auth_code` 为一次性短时授权码，不应作为长期登录凭证保存。

#### 7.2 授权并直接跳转 [#](#24-toc-title)

**接口说明**

推广方产品可通过该接口让 PartnerShare 完成授权处理并直接返回 `302` 跳转。跳转目标为携带 `ps_ref` 与 `x_auth_code` 的被推广方产品落地页。

该接口适用于推广方希望用户点击后立即跳转的场景。如果推广方需要先拿到跳转链接再自行控制跳转，建议使用 `POST /api/open/v1/oauth/authorize`。

**请求信息**

| 项目 | 内容 |
| --- | --- |
| 请求方式 | GET |
| 接口地址 | /api/open/v1/oauth/authorizeAndRedirect |
| 调用方 | 推广方产品服务端或跳转入口 |

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| product_key | string | 是 | 推广方产品 key。 |
| target_product_key | string | 是 | 被推广方产品 key。 |
| user_id | string | 是 | 推广方产品内稳定的用户唯一标识。 |
| extra | string | 否 | JSON 字符串格式的扩展用户信息。 |

**请求示例**

```
GET /api/open/v1/oauth/authorizeAndRedirect?product_key=your_product_key&target_product_key=target_product_key&user_id=source_user_001
```

**成功响应**

```
HTTP/1.1 302 Found
Location: https://target.example.com/landing?ps_ref=INVITE_CODE&x_auth_code=2fwth3pfj8
```

**失败响应**

```
{
  "code": 1000001,
  "message": "授权目标产品不存在",
  "data": null
}
```

#### 7.3 通过授权码获取用户信息 [#](#25-toc-title)

**接口说明**

被推广方产品在落地页接收到 `x_auth_code` 后，调用该接口向 PartnerShare 换取授权用户信息。换取成功后，被推广方产品可基于返回的 `user_key` 完成本地账号绑定、自动注册或登录。

**请求信息**

| 项目 | 内容 |
| --- | --- |
| 请求方式 | POST |
| 接口地址 | /api/open/v1/oauth/getUserByAuthorizationCode |
| Content-Type | application/json |
| 调用方 | 被推广方产品服务端 |

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 被推广方落地页接收到的 x_auth_code。 |

**请求示例**

```
{
  "code": "2fwth3pfj8"
}
```

**响应参数**

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| user_key | string | PartnerShare 生成的授权用户唯一标识。 |
| user_name | string | 授权用户展示名称。 |
| ref | string | 推广方产品名称。 |
| ref_product_key | string | 推广方产品 key。 |
| locale | string | 用户语言偏好。 |
| extra | object | 推广方传入的扩展用户信息。 |

**响应示例**

```
{
  "code": 0,
  "message": "success",
  "data": {
    "user_key": "uk_abc123xyz",
    "user_name": "Demo User",
    "ref": "Source Product",
    "ref_product_key": "source_product_key",
    "locale": "zh",
    "extra": {
      "user_name": "Demo User",
      "email": "demo@example.com",
      "locale": "zh"
    }
  }
}
```

**注意事项**

- `code` 只能成功兑换一次，兑换成功后即失效。
- `code` 具有有效期，过期后需要重新发起授权流程。
- 当前 API Key 所属产品必须与授权目标产品一致。
- 被推广方产品应使用 `user_key` 建立本地用户绑定关系。
- 该接口不会返回推广方产品内部的原始用户 ID。

#### 7.4 获取调试授权码 [#](#26-toc-title)

**接口说明**

该接口用于联调阶段生成测试授权码，方便被推广方产品验证落地页接收参数、服务端换码、自动注册、登录和注册事件回传流程。

该接口仅用于调试，不建议作为正式业务流程依赖。

**请求信息**

| 项目 | 内容 |
| --- | --- |
| 请求方式 | POST |
| 接口地址 | /api/open/v1/oauth/getDebugAuthCode |
| Content-Type | application/json |
| 调用方 | 接入方服务端 |

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| source_product_key | string | 是 | 推广方产品 key。 |
| target_product_key | string | 是 | 被推广方产品 key。 |
| user_id | string | 是 | 调试用户 ID。 |
| extra | object | 否 | 调试用户扩展信息。 |

**请求示例**

```
{
  "product_key": "your_product_key",
  "target_product_key": "target_product_key",
  "user_id": "debug_user_001",
  "extra": {
    "user_name": "OAuth Debug User",
    "email": "debug_user@example.com",
    "locale": "zh"
  }
}
```

**响应参数**

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 调试授权码。 |
| redirect_url | string | 携带调试授权码的推广链接。 |

**响应示例**

```
{
  "code": 0,
  "message": "success",
  "data": {
    "code": "debug_code_example",
    "redirect_url": "https://target.example.com/landing?ps_ref=INVITE_CODE&x_auth_code=debug_code_example"
  }
}
```

#### 7.5 回传注册事件 [#](#27-toc-title)

**接口说明**

被推广方产品完成自动注册或确认有效转化后，调用该接口向 PartnerShare 回传注册事件。PartnerShare 根据推广邀请码完成归因统计，并用于后续推广分佣结算。参考文档：[https://www.partnershare.net/help/api/event-report](https://www.partnershare.net/help/api/event-report)

在产品授权推广登录场景中，被推广方落地页接收到的 `ps_ref` 需要在回传时作为 `invite_code` 传入。

**请求信息**

| 项目 | 内容 |
| --- | --- |
| 请求方式 | POST |
| 接口地址 | /api/open/v1/track/conversion |
| Content-Type | application/json |
| 调用方 | 被推广方产品服务端 |

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event_name | string | 是 | 事件名称。注册事件固定传 signup。 |
| invited_user_id | string | 是 | 被推广方产品内的本地用户唯一标识。 |
| invite_code | string | 是 | 推广邀请码。取值为落地页 URL 中的 ps_ref。 |
| invited_user_name | string | 否 | 被推广方产品内的用户展示名称。 |
| click_id | string | 否 | 点击 ID。若接入方不确定 ps_ref 的归因类型，可与 invite_code 一样传入 ps_ref。 |

**请求示例**

```
{
  "event_name": "signup",
  "invited_user_id": "local_user_10001",
  "invited_user_name": "Demo User",
  "invite_code": "INVITE_CODE"
}
```

兼容写法示例：

```
{
  "event_name": "signup",
  "invited_user_id": "local_user_10001",
  "invited_user_name": "Demo User",
  "invite_code": "INVITE_CODE",
  "click_id": "INVITE_CODE"
}
```

**响应参数**

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| conversion_id | int | 转化事件 ID。 |
| campaign_id | int | 推荐计划活动 ID。 |
| affiliate_id | int | 归因到的推广账号 ID。 |
| event_type | int | 事件类型。注册事件为 1。 |
| event_name | string | 事件名称。注册事件为 signup。 |
| status | int | 转化事件状态。 |

**响应示例**

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

**注意事项**

- `invite_code` 必须取自落地页 URL 中的 `ps_ref`。
- `invited_user_id` 建议传被推广方产品内稳定且唯一的本地用户 ID。
- 注册事件应在本地用户创建成功或确认有效注册后再回传。
- 同一被推广方产品、同一 `invited_user_id` 的注册事件不可重复上报。
- 若后续需要上报付费事件，可在注册事件成功后，基于同一 `invited_user_id` 上报 `purchase` 事件。

#### 7.6 推荐调用顺序 [#](#28-toc-title)

1. 推广方产品调用 `POST /api/open/v1/oauth/authorize` 获取推广链接。
2. 推广方产品将用户跳转至 `redirect_url`。
3. 被推广方产品落地页接收 `ps_ref` 与 `x_auth_code`。
4. 被推广方产品服务端调用 `POST /api/open/v1/oauth/getUserByAuthorizationCode` 换取用户信息。
5. 被推广方产品基于 `user_key` 完成本地自动注册或登录。
6. 被推广方产品调用 `POST /api/open/v1/track/conversion`，将 `ps_ref` 作为 `invite_code` 回传注册事件。

---

## 8. 常见问题

### 8.1 为什么接口提示“API Key 或签名不能为空”？ [#](#29-toc-title)

通常是请求头中缺少鉴权字段。请确认请求中已携带以下 Header：

| Header | 说明 |
| --- | --- |
| X-Api-Key | PartnerShare 分配给产品的 API Key |
| X-Api-Timestamp | 秒级时间戳 |
| X-Api-Sign | 按签名规则生成的签名 |

请同时确认请求头名称是否拼写正确，并确保签名逻辑由服务端生成。

### 8.2 为什么接口提示“签名错误”？ [#](#30-toc-title)

常见原因包括：

- API Secret 使用错误。
- 时间戳不是秒级时间戳。
- 参与签名的参数字段名不完整。
- 参数字段名未统一转换为小写。
- 字段名排序规则不一致。

### 8.3 为什么生成推广授权链接失败？ [#](#31-toc-title)

常见原因包括：

- `product_key` 不存在或不属于当前 API Key。
- `target_product_key` 不存在。
- 被推广方产品未完成基础配置。
- 被推广方产品未填写推广 URL。
- 被推广方产品下没有可用的联盟计划活动。
- 联盟计划活动未处于进行中状态。

建议先检查 PartnerShare 后台中的产品配置、推广 URL 和联盟计划活动状态。

### 8.4 为什么推广链接没有携带 `ps_ref` 或 `x_auth_code`？ [#](#32-toc-title)

常见原因包括：

- 被推广方产品未正确配置推广 URL。
- 推广 URL 本身格式不正确。
- 联盟计划活动不可用。
- 推广关系未成功生成。
- 业务侧跳转时重新拼接 URL，导致参数丢失。

建议直接使用 PartnerShare 返回的 `redirect_url` 进行跳转，不要在业务侧重新改写链接。

### 8.5 被推广方落地页需要接收哪些参数？ [#](#33-toc-title)

被推广方落地页至少需要接收以下参数：

| 参数 | 说明 |
| --- | --- |
| x_auth_code | 一次性授权码，用于服务端换取用户信息 |
| ps_ref | 推广邀请码，用于注册事件回传和推广归因 |

其中，`x_auth_code` 应尽快提交至被推广方服务端完成换码；`ps_ref` 需要保留到注册事件回传阶段。

### 8.6 为什么通过授权码获取用户信息失败？ [#](#34-toc-title)

常见原因包括：

- `x_auth_code` 已过期。
- `x_auth_code` 已经被成功兑换过。
- 当前 API Key 所属产品不是该授权码对应的被推广方产品。
- 传入的字段名错误，换码接口应传 `code`，不是 `x_auth_code`。
- 授权流程未完整生成授权码。

正确请求示例：

```
{
  "code": "落地页收到的 x_auth_code"
}
```

### 8.7 授权码可以重复使用吗？ [#](#35-toc-title)

不可以。`x_auth_code` 是一次性短时授权码，成功换取用户信息后即失效。

被推广方产品应在服务端消费授权码，并避免前端重复提交。

### 8.8 授权码可以作为登录凭证保存吗？ [#](#36-toc-title)

不可以。`x_auth_code` 只用于一次性换取授权用户信息，不应作为长期登录凭证、会话凭证或用户唯一标识保存。

被推广方产品应使用 PartnerShare 返回的 `user_key` 建立本地用户绑定关系。

### 8.9 被推广方产品应该如何处理 `user_key`？ [#](#37-toc-title)

建议将 `user_key` 与被推广方产品本地用户 ID 建立唯一绑定关系。

推荐处理逻辑：

1. 根据 `user_key` 查询是否已有本地绑定用户。
2. 如果存在，直接登录该用户。
3. 如果不存在，创建本地用户并保存 `user_key` 绑定关系。
4. 后续同一授权用户再次进入时，复用该绑定关系。

### 8.10 为什么注册事件回传后没有完成归因？ [#](#38-toc-title)

常见原因包括：

- 没有传 `invite_code`。
- `invite_code` 没有使用落地页接收到的 `ps_ref`。
- `ps_ref` 在注册流程中丢失。
- 被推广方产品没有在注册成功后回传事件。
- 当前联盟计划活动不可用。
- 注册事件重复上报，被系统判定为重复转化。

在产品授权推广登录场景中，注册事件回传时应将 `ps_ref` 作为 `invite_code` 传入。

### 8.11 注册事件回传应该传哪些参数？ [#](#39-toc-title)

注册事件建议传：

```
{
  "event_name": "signup",
  "invited_user_id": "local_user_10001",
  "invited_user_name": "Demo User",
  "invite_code": "INVITE_CODE"
}
```

字段说明：

| 参数 | 说明 |
| --- | --- |
| event_name | 固定传 signup |
| invited_user_id | 被推广方产品内的本地用户唯一标识 |
| invited_user_name | 被推广方产品内的用户展示名称，可选 |
| invite_code | 落地页接收到的 ps_ref |

### 8.12 `ps_ref` 和 `invite_code` 是什么关系？ [#](#40-toc-title)

`ps_ref` 是推广链接 URL 中携带的参数名，`invite_code` 是注册事件回传接口中的字段名。

在产品授权推广登录场景中，两者的关系是：

```
invite_code = ps_ref
```

也就是说，被推广方落地页收到 `ps_ref` 后，需要在回传注册事件时将其作为 `invite_code` 提交给 PartnerShare。

### 8.13 如果注册流程跨多个页面，如何避免 `ps_ref` 丢失？ [#](#41-toc-title)

建议在落地页收到 `ps_ref` 后，将其保存到服务端会话、短期缓存或安全 Cookie 中，并在注册成功时取出用于注册事件回传。

不建议只依赖前端页面参数在多页面之间传递，否则容易因为跳转、刷新或第三方登录流程导致参数丢失。

### 8.14 为什么注册事件提示“该转化事件已存在”？ [#](#42-toc-title)

说明同一被推广方产品下，相同 `invited_user_id` 的注册事件已经上报过。

建议接入方做好幂等处理：

- 同一个本地用户只回传一次注册事件。
- 前端注册按钮防止重复点击。
- 后端注册成功回调避免重复触发。

### 8.15 调试授权码接口可以用于正式业务吗？ [#](#43-toc-title)

不建议。`/api/open/v1/oauth/getDebugAuthCode` 主要用于联调阶段验证换码、自动注册、登录和注册事件回传流程。

正式业务流程应使用以下接口之一：

```
POST /api/open/v1/oauth/authorize
GET /api/open/v1/oauth/authorizeAndRedirect
```

### 8.16 推广方是否需要自己创建推广账号或推广链接？ [#](#44-toc-title)

不需要。在首次发生推广方产品到被推广方产品的授权推广登录时，PartnerShare 会自动创建或复用对应的推广关系，并生成推广链接。

推广方只需要调用授权接口获取 `redirect_url`。

### 8.17 被推广方是否还能自行控制注册和登录逻辑？ [#](#45-toc-title)

可以。PartnerShare 只负责授权中继、推广关系维护、授权码换码和注册事件归因。

被推广方产品仍然负责自己的本地账号创建、用户绑定、登录态生成和业务权限控制。

### 8.18 是否可以在前端直接调用换码接口？ [#](#46-toc-title)

不建议。换码接口需要携带 API Key 和签名，API Secret 不应暴露在前端。

建议由被推广方服务端调用换码接口，前端只负责把 `x_auth_code` 提交给自己的服务端。

### 8.19 `extra` 字段可以传哪些内容？ [#](#47-toc-title)

`extra` 用于传递推广方希望提供给被推广方的用户辅助信息，例如：

```
{
  "user_name": "Demo User",
  "email": "demo@example.com",
  "locale": "zh"
}
```

建议只传递完成自动注册或登录所需的必要信息，不要传递敏感数据或超出用户授权范围的数据。

### 8.20 如何判断接入链路是否完整？ [#](#48-toc-title)

可以按以下顺序检查：

1. 推广方可以成功获取 `redirect_url`。
2. `redirect_url` 中包含 `ps_ref` 和 `x_auth_code`。
3. 被推广方落地页可以读取这两个参数。
4. 被推广方服务端可以通过 `x_auth_code` 换取用户信息。
5. 被推广方可以基于 `user_key` 完成自动注册或登录。
6. 注册成功后可以将 `ps_ref` 作为 `invite_code` 回传注册事件。
7. PartnerShare 后台可以看到对应的归因和推广数据。

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

[推广点击跟踪 SDK 接入](https://www.partnershare.net/help/api/sdk)

大纲 - [1. 概述](#0-toc-title)
- [2. 核心概念](#1-toc-title)
- [3. 前置要求](#2-toc-title)
  - [3.1 注册 PartnerShare 品牌主后台账号](#3-toc-title)
  - [3.2 完成产品基础配置](#4-toc-title)
  - [3.3 填写推广 URL](#5-toc-title)
  - [3.4 创建联盟计划活动](#6-toc-title)
  - [3.5 确认联盟计划活动已生成并处于进行中状态](#7-toc-title)

- [4. 流程图](#8-toc-title)
- [5. 数据约定](#9-toc-title)
  - [5.1 请求数据约定](#10-toc-title)
  - [5.2 响应数据约定](#11-toc-title)
  - [5.3 URL 参数约定](#12-toc-title)
  - [5.4 重要字段约定](#13-toc-title)

- [6. 签名机制](#14-toc-title)
  - [6.1 获取 API Key 和 API Secret](#15-toc-title)
  - [6.2 请求头](#16-toc-title)
  - [6.3 签名规则](#17-toc-title)
  - [6.4 JavaScript 签名示例](#18-toc-title)
  - [6.5 Go 签名示例](#19-toc-title)
  - [6.6 PHP 签名示例](#20-toc-title)
  - [6.7 注意事项](#21-toc-title)

- [7. 接口列表](#22-toc-title)
  - [7.1 生成推广授权链接](#23-toc-title)
  - [7.2 授权并直接跳转](#24-toc-title)
  - [7.3 通过授权码获取用户信息](#25-toc-title)
  - [7.4 获取调试授权码](#26-toc-title)
  - [7.5 回传注册事件](#27-toc-title)
  - [7.6 推荐调用顺序](#28-toc-title)

- [8.1 为什么接口提示“API Key 或签名不能为空”？](#29-toc-title)
- [8.2 为什么接口提示“签名错误”？](#30-toc-title)
- [8.3 为什么生成推广授权链接失败？](#31-toc-title)
- [8.4 为什么推广链接没有携带 ps_ref 或 x_auth_code？](#32-toc-title)
- [8.5 被推广方落地页需要接收哪些参数？](#33-toc-title)
- [8.6 为什么通过授权码获取用户信息失败？](#34-toc-title)
- [8.7 授权码可以重复使用吗？](#35-toc-title)
- [8.8 授权码可以作为登录凭证保存吗？](#36-toc-title)
- [8.9 被推广方产品应该如何处理 user_key？](#37-toc-title)
- [8.10 为什么注册事件回传后没有完成归因？](#38-toc-title)
- [8.11 注册事件回传应该传哪些参数？](#39-toc-title)
- [8.12 ps_ref 和 invite_code 是什么关系？](#40-toc-title)
- [8.13 如果注册流程跨多个页面，如何避免 ps_ref 丢失？](#41-toc-title)
- [8.14 为什么注册事件提示“该转化事件已存在”？](#42-toc-title)
- [8.15 调试授权码接口可以用于正式业务吗？](#43-toc-title)
- [8.16 推广方是否需要自己创建推广账号或推广链接？](#44-toc-title)
- [8.17 被推广方是否还能自行控制注册和登录逻辑？](#45-toc-title)
- [8.18 是否可以在前端直接调用换码接口？](#46-toc-title)
- [8.19 extra 字段可以传哪些内容？](#47-toc-title)
- [8.20 如何判断接入链路是否完整？](#48-toc-title)