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

1. 概述 #

2. 核心概念 #

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

3. 前置要求 #

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

3.1 注册 PartnerShare 品牌主后台账号 #

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

https://share.partnershare.com/nueshawu

3.2 完成产品基础配置 #

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

3.3 填写推广 URL #

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

3.4 创建联盟计划活动 #

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

3.5 确认联盟计划活动已生成并处于进行中状态 #

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

4. 流程图 #

5. 数据约定 #

5.1 请求数据约定 #

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

请求示例：

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

5.2 响应数据约定 #

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

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

成功响应示例：

{
  "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 参数约定 #

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

示例：

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

5.4 重要字段约定 #

6. 签名机制 #

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

6.1 获取 API Key 和 API Secret #

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

6.2 请求头 #

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

6.3 签名规则 #

签名生成规则如下：

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 签名示例 #

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 签名示例 #

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 签名示例 #

<?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 注意事项 #

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

7. 接口列表 #

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

/api/open/v1

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

https://api-service.partnershare.net

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

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

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

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
}

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

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

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

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