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

1. 核心概念 #

2. 前置要求 #

2.1 注册品牌主后台账号 #

注册并登录 PartnerShare 品牌主后台：https://share.partnershare.com/nueshawu

2.2 完成产品基础配置 #

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

2.3 填写推广 URL #

推广 URL 是用户最终跳转到被推广方产品的落地页地址。PartnerShare 生成推广链接时在该地址上追加 ps_ref 和 x_auth_code。

2.4 创建联盟计划活动 #

被推广方产品需要创建联盟计划活动，用于承接推广方加入、推广关系生成、归因统计和分佣结算，也是生成推广落地链接的前置条件。

2.5 确认活动处于进行中 #

确认活动已在对应产品下生成、类型为联盟计划且处于进行中。活动未开始、已暂停或已结束时，推广链接生成、注册归因或分佣结算无法正常完成。

推广 URL、联盟计划活动及其状态是影响授权跳转和注册归因的关键配置，接口联调前先确认。

3. 流程图 #

4. 通用约定 #

4.1 请求 #

4.2 响应 #

{
  "code": 0,
  "message": "Success",
  "data": {}
}

4.3 落地页 URL 参数 #

用户跳转到被推广方落地页时，URL 携带以下参数：

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

4.4 字段约定 #

5. 鉴权 #

所有接口需携带 API Key 签名请求头，签名由服务端生成。API Key 与 API Secret 在品牌主后台「产品管理 → 基础设置 → 开发者集成」获取，签名算法按密钥版本执行，见 API 鉴权与签名机制。

6. 接口 #

6.1 生成推广授权链接 #

推广方产品在用户完成授权后调用。PartnerShare 生成一次性授权码，返回携带 ps_ref 与 x_auth_code 的推广链接，由推广方自行控制跳转。调用方：推广方产品服务端。

{
  "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": 0,
  "message": "Success",
  "data": {
    "code": "2fwth3pfj8",
    "redirect_url": "https://target.example.com/landing?ps_ref=INVITE_CODE&x_auth_code=2fwth3pfj8"
  }
}

直接使用 redirect_url 跳转，不要在业务侧重新拼接链接。x_auth_code 有效期 5 分钟，不作为长期凭证保存。

6.2 授权并直接跳转 #

由 PartnerShare 完成授权处理并直接返回 302，跳转到携带 ps_ref 与 x_auth_code 的被推广方落地页。适用于点击后立即跳转的场景；需要先拿到链接再自行控制跳转时使用 6.1。调用方：推广方产品服务端。

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
Host: api-service.partnershare.net
X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx
X-Api-Timestamp: 1776677721
X-Api-Sign: {signature}

成功响应：

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

失败响应：

{
  "code": 1000001,
  "message": "The target product was not found or is not accessible",
  "data": null
}

6.3 通过授权码获取用户信息 #

被推广方落地页接收到 x_auth_code 后，由服务端调用本接口换取授权用户信息，再基于 user_key 完成本地账号绑定、自动注册或登录。调用方：被推广方产品服务端。

{
  "code": "2fwth3pfj8"
}

{
  "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"
    }
  }
}

• 授权码只能成功兑换一次，兑换后立即失效；有效期 5 分钟，过期需重新发起授权。
• 当前 API Key 所属产品必须是该授权码对应的被推广方产品。
• 接口不返回推广方产品内部的原始用户 ID。

6.4 获取调试授权码 #

联调阶段生成测试授权码，用于验证落地页接收参数、服务端换码、自动注册、登录和注册事件回传流程。仅用于调试，正式流程使用 6.1 或 6.2。调用方：被推广方产品服务端，被推广方产品即当前 API Key 所属产品。

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

{
  "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"
  }
}

6.5 回传注册事件 #

被推广方完成自动注册或确认有效转化后回传注册事件，PartnerShare 按推广邀请码归因并用于分佣结算。完整参数见 推广转化事件回传。本场景下，落地页接收到的 ps_ref 作为 invite_code 传入。调用方：被推广方产品服务端。

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

{
  "code": 0,
  "message": "Signup event reported successfully",
  "data": {
    "conversion_id": 10001,
    "campaign_id": 20001,
    "affiliate_id": 30001,
    "event_type": 1,
    "event_name": "signup",
    "status": 1
  }
}

• 注册事件在本地用户创建成功或确认有效注册后回传；同一 invited_user_id 只回传一次。
• 后续付费事件基于同一 invited_user_id 上报 purchase。

6.6 调用顺序 #

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 回传注册事件。

7. 常见问题 #

8. 链路检查清单 #

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