---
title: "推广者资源接口"
id: "1379"
type: "docs"
slug: "promoter-resources"
published_at: "2026-09-07T06:15:09+00:00"
modified_at: "2026-09-07T07:09:24+00:00"
url: "https://www.partnershare.net/help/api/promoter-resources"
markdown_url: "https://www.partnershare.net/help/api/promoter-resources.md"
excerpt: "推广者资源接口用于查询指定推广者的基本信息、推广链接、推广数据和账户余额，适用于在品牌方自有系统中展示推广者面 […]"
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)

## 技术集成

8

- [API 鉴权与签名机制](https://www.partnershare.net/help/api/signature)
- [推广转化事件回传](https://www.partnershare.net/help/api/event-report)
- [推广点击跟踪 SDK 接入](https://www.partnershare.net/help/api/sdk)
- [转化退款](https://www.partnershare.net/help/api/conversion-refund)
- [转化作废](https://www.partnershare.net/help/api/conversion-void)
- [将 PartnerShare 内嵌到产品中](https://www.partnershare.net/help/api/iframe)
- [推广者资源接口](https://www.partnershare.net/help/api/promoter-resources)
- [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

推广者资源接口用于查询指定推广者的基本信息、推广链接、推广数据和账户余额，适用于在品牌方自有系统中展示推广者面板。路径参数 `user_id` 为品牌方系统中的用户 ID，与 `/api/open/v1/promoter/login` 接口的 `user_id` 参数一致。

### 1. 接口列表 [#](#0-toc-title)

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /api/open/v1/promoters/{user_id} | 推广者资料，可按需展开其他资源 |
| GET | /api/open/v1/promoters/{user_id}/links | 推广链接列表 |
| GET | /api/open/v1/promoters/{user_id}/statistics | 推广统计，支持日期范围 |
| GET | /api/open/v1/promoters/{user_id}/balances | 按币种的余额 |

### 2. 通用说明 [#](#1-toc-title)

| 项目 | 说明 |
| --- | --- |
| 请求域名 | https://api-service.partnershare.net |
| 鉴权 | X-Api-Key + X-Api-Timestamp + X-Api-Sign，算法见 API 鉴权与签名机制 |
| 支持的 API Key 版本 | v2 |
| GET 签名 | 签名的 query 字符串需与实际发送内容逐字一致，请求体哈希取空字符串的 SHA256（e3b0c442…7852b855） |
| 权限 | 密钥配置了权限列表时需包含 promoter:read；未配置权限列表的密钥不受限制 |
| 产品范围 | 只能查询 API Key 所属产品下的推广者 |
| user_id | 品牌方用户 ID，最长 255 字符，包含特殊字符时需进行 URL 编码。该用户需已通过 /api/open/v1/promoter/login 接口创建为推广者，否则返回 1000001 |
| 金额格式 | 字符串，保留两位小数，如 "120.50" |
| 时间格式 | ISO 8601 带时区，如 2026-04-01T10:20:30+08:00；日期参数为 Y-m-d |
| 响应格式 | HTTP 200，code 为 0 时 data 为业务数据，否则 data 为 null |
| 分页 | 无，各接口返回完整数据 |

### 3. 推广者资料 [#](#2-toc-title)

GET`/api/open/v1/promoters/{user_id}`

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

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| user_id | path | string | 是 | 品牌方用户 ID |
| expand | query | string | 否 | 逗号分隔，可选值 links、statistics、balances。展开内容与对应的独立接口一致；statistics 展开时不支持日期范围。包含其他值时返回错误 |

#### 3.2 响应字段 [#](#4-toc-title)

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | string | 固定 promoter |
| user_string_id | string | PartnerShare 推广者字符串 ID，与 promoter/login 接口返回的 user_string_id 相同 |
| external_user_id | string | 品牌方用户 ID，即路径中的 user_id |
| status | string | unapplied 未申请、pending 待审核、approved 已通过、rejected 已拒绝、suspended 已暂停 |
| referral_code | string / null | 主推荐计划下的邀请码。产品没有推荐计划或推广者未加入时为 null |
| joined_at | string / null | 成为推广者的时间 |
| links | array | 仅 expand 含 links 时返回，结构见第 4 节 |
| statistics | object | 仅 expand 含 statistics 时返回，结构见第 5 节 |
| balances | array | 仅 expand 含 balances 时返回，结构见第 6 节 |

#### 3.3 示例 [#](#5-toc-title)

```
curl "https://api-service.partnershare.net/api/open/v1/promoters/user_10001?expand=links,balances" \
  -H "X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Api-Timestamp: 1776677721" \
  -H "X-Api-Sign: {signature}"
```

```
{
  "code": 0,
  "message": "Success",
  "data": {
    "object": "promoter",
    "user_string_id": "ps8xk2m9qa",
    "external_user_id": "user_10001",
    "status": "approved",
    "referral_code": "LN088",
    "joined_at": "2026-03-12T09:15:40+08:00",
    "links": [
      {
        "object": "promotion_link",
        "campaign_key": "referral",
        "campaign_name": "推荐计划",
        "url": "https://go.your-brand.com/LN088",
        "introduction": {
          "locale": "zh",
          "title": "邀请好友，双方各得 10 美元",
          "subtitle": "好友首单支付后到账"
        }
      }
    ],
    "balances": [
      {
        "object": "balance",
        "currency": "USD",
        "available": "120.50",
        "pending": "30.00",
        "withdrawing": "0.00"
      }
    ]
  }
}
```

### 4. 推广链接 [#](#6-toc-title)

GET`/api/open/v1/promoters/{user_id}/links`

返回推广者在当前产品推荐计划中已启用的推广链接，无可用链接时 `data` 为空数组。链接域名优先使用产品已配置且与推广者语言匹配的自定义追踪域名，否则使用产品默认追踪域名。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | string | 固定 promotion_link |
| campaign_key | string | 活动标识 |
| campaign_name | string | 活动名称 |
| url | string | 推广链接，格式 https://{追踪域名}/{邀请码} |
| introduction | object / null | 活动介绍文案，按推广者语言选取；字段 locale、title、subtitle。未配置时为 null |

### 5. 推广统计 [#](#7-toc-title)

GET`/api/open/v1/promoters/{user_id}/statistics?start_date=2026-04-01&end_date=2026-04-30`

#### 5.1 请求参数 [#](#8-toc-title)

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| start_date | query | string | 否 | Y-m-d，含当天 00:00:00。不传则不限制开始时间 |
| end_date | query | string | 否 | Y-m-d，含当天 23:59:59。不传则不限制结束时间。不能早于 start_date |

日期参数按 UTC+8 时区解析，按记录创建时间筛选。

#### 5.2 响应字段 [#](#9-toc-title)

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | string | 固定 promoter_statistics |
| clicks | int | 推广链接点击数 |
| signups | int | 注册用户数，按被邀请用户去重 |
| paying_customers | int | 付费用户数，按被邀请用户去重；已退款或作废的转化不计 |
| rewards_paid | string | 已发放奖励金额 |
| rewards_accrued | string | 累计奖励金额，含待审核、已通过、已发放 |
| currency | string | 产品币种，金额字段均按此币种 |
| start_date | string / null | 请求传入的开始日期 |
| end_date | string / null | 请求传入的结束日期 |

统计范围为产品的推荐计划活动，奖励金额包含人工发放的奖励，口径与推广者端一致。

#### 5.3 示例 [#](#10-toc-title)

```
{
  "code": 0,
  "message": "Success",
  "data": {
    "object": "promoter_statistics",
    "clicks": 358,
    "signups": 42,
    "paying_customers": 9,
    "rewards_paid": "90.00",
    "rewards_accrued": "150.50",
    "currency": "USD",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30"
  }
}
```

### 6. 余额 [#](#11-toc-title)

GET`/api/open/v1/promoters/{user_id}/balances`

每个币种返回一条记录，按币种代码排序。推广者尚无资金记录时，返回产品币种的一条零值记录。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | string | 固定 balance |
| currency | string | 币种 |
| available | string | 钱包可用余额 |
| pending | string | 待审核与已通过、尚未发放的奖励金额合计 |
| withdrawing | string | 待审核、已通过、处理中的提现金额合计 |

```
{
  "code": 0,
  "message": "Success",
  "data": [
    {
      "object": "balance",
      "currency": "USD",
      "available": "120.50",
      "pending": "30.00",
      "withdrawing": "0.00"
    }
  ]
}
```

### 7. 涉及资金与身份的操作 [#](#12-toc-title)

本组接口为只读。提现、绑定收款账号、实名认证等操作在 PartnerShare 推广中心内完成，品牌方无需自行实现相关流程。

使用 [/api/open/v1/promoter/login](https://www.partnershare.net/help/api/iframe)
 返回的 `token`，让用户免登进入推广中心：

| 方式 | 地址 | 适用场景 |
| --- | --- | --- |
| 整页免登 | https://promoter.partnershare.net?at={token} | 点击提现、实名认证等入口后整页跳转或新开窗口 |
| 内嵌 iframe | https://promoter.partnershare.net/iframe/{token} | 在当前页面弹层打开，用户不离开自有系统 |

推荐的接入形态：

1. 自有页面使用本组接口渲染推广者的资料、链接、统计和余额。
2. 「提现」「实名认证」「绑定收款账号」等入口请求自身服务端，调用 `/api/open/v1/promoter/login` 获取新的 `token`，再打开推广中心。
3. 用户操作完成返回后，重新调用 `balances`、`statistics` 刷新页面数据。

余额接口的 `withdrawing` 字段返回待审核、已通过、处理中的提现金额合计，可用于在自有页面展示处理中的提现总额。提现记录明细与实名认证状态暂未开放接口，需在推广中心查看。

### 8. 错误码 [#](#13-toc-title)

| code | message | 原因 |
| --- | --- | --- |
| 1000001 | The promoter was not found | 当前产品下没有该 user_id 的推广者，或产品已删除 |
| 1000004 | This endpoint requires signature version 2 | 使用了 v1 密钥 |
| 1000004 | 其他鉴权消息 | 请求头、签名、时间戳、IP 白名单等校验失败，见 API 鉴权与签名机制 |
| 6000000 | Missing required permission: promoter:read | 密钥权限列表未包含该权限 |
| 6000000 | The user_id path parameter has an invalid format | user_id 为空或超过 255 字符 |
| 6000000 | Unsupported expand value: {value} | expand 含不支持的值 |
| 6000000 | The expand parameter has an invalid format | expand 不是字符串 |
| 6000000 | The start_date parameter must use the Y-m-d format | 日期格式错误，end_date 相同 |
| 6000000 | The start_date must not be later than the end_date | 开始日期晚于结束日期 |
| 6000000 | Failed to retrieve promoter data | 服务端异常，可重试；持续出现时请联系 PartnerShare 技术支持 |

### 9. 接入注意事项 [#](#14-toc-title)

- 本组接口只接受 v2 密钥。密钥的签名版本可在品牌主后台「产品管理 → 基础设置 → 开发者集成」查看，v1 密钥需新建一组后使用。
- 首次为用户展示推广面板前，先调用 `/api/open/v1/promoter/login` 创建推广者，再调用本文接口。
- 接口为只读查询，可由服务端缓存后返回给前端。API Secret 仅可保存在服务端，不得在浏览器端直接调用。
- 需要同时展示多类数据时，可通过 `expand` 参数在一次请求中获取。

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

[转化作废](https://www.partnershare.net/help/api/conversion-void)

大纲 - [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)

- [4. 推广链接](#6-toc-title)
- [5. 推广统计](#7-toc-title)
  - [5.1 请求参数](#8-toc-title)
  - [5.2 响应字段](#9-toc-title)
  - [5.3 示例](#10-toc-title)

- [6. 余额](#11-toc-title)
- [7. 涉及资金与身份的操作](#12-toc-title)
- [8. 错误码](#13-toc-title)
- [9. 接入注意事项](#14-toc-title)