推广者资源接口

1. 接口列表 #

2. 通用说明 #

3. 推广者资料 #

3.1 请求参数 #

3.2 响应字段 #

3.3 示例 #

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. 推广链接 #

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

5. 推广统计 #

5.1 请求参数 #

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

5.2 响应字段 #

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

5.3 示例 #

{
  "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. 余额 #

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

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

7. 涉及资金与身份的操作 #

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

使用 /api/open/v1/promoter/login 返回的 token，让用户免登进入推广中心：

推荐的接入形态：

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

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

8. 错误码 #

9. 接入注意事项 #

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