--- title: "API 鉴权与签名机制" id: "578" type: "docs" slug: "signature" published_at: "2026-01-07T06:17:23+00:00" modified_at: "2026-08-19T09:55:08+00:00" url: "https://www.partnershare.net/help/api/signature" markdown_url: "https://www.partnershare.net/help/api/signature.md" excerpt: "PartnerShare API Authentication API 鉴权与签名机制 本文说明 Partne […]" 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 API Authentication ## API 鉴权与签名机制 本文说明 PartnerShare 开放接口的服务端鉴权方式。接入方需要在每次请求中携带 API Key、秒级时间戳和签名，PartnerShare 会基于 API Secret 重新计算签名并校验请求合法性，避免接口被伪造、重放或越权调用。 API Key 身份识别API Secret 服务端签名5 分钟时间窗SHA256 ### 1. 概述 [#](#0-toc-title) PartnerShare 开放接口默认使用 `API Key + API Secret + Timestamp + Signature` 的方式完成鉴权。API Key 用于识别调用方产品，API Secret 仅用于服务端生成签名，不会直接随请求发送。 **确认调用方身份**通过 `X-Api-Key` 定位产品和租户，确保请求来自已授权产品。 **防止请求伪造**签名由 API Secret 生成，攻击者即使知道 API Key，也无法构造合法签名。 **降低重放风险**`X-Api-Timestamp` 仅在 5 分钟时间窗内有效，过期请求会被拒绝。 **安全提醒**API Secret 必须保存在服务端，不允许暴露在浏览器、小程序、移动端 App、公开仓库或共享 Postman 环境中。 ### 2. 获取 API Key 和 API Secret [#](#1-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 **字段职责**`API Key` 用于请求头传输，标识调用方产品；`API Secret` 只用于本地计算签名，不参与明文传输。 ### 3. 请求头约定 [#](#2-toc-title) 调用需要鉴权的开放接口时，请在 Header 中携带以下参数： | Header | 必填 | 说明 | | --- | --- | --- | | X-Api-Key | 是 | PartnerShare 分配给产品的 API Key，用于识别调用方产品。 | | X-Api-Timestamp | 是 | 秒级时间戳。服务端会校验时间戳是否在有效时间窗内。 | | X-Api-Sign | 是 | 按本文签名规则生成的 SHA256 签名。 | | Content-Type | 是 | 推荐使用 application/json。 | Header 示例： ``` POST /api/open/v1/track/conversion HTTP/1.1 Host: api-service.partnershare.net Content-Type: application/json X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx X-Api-Timestamp: 1776677721 X-Api-Sign: 8473ee71d083d9d1650c0e9081b5777d5b6cde2508521d5322d603a007214afd ``` ### 4. 签名规则 [#](#3-toc-title) PartnerShare 的签名只使用请求参数的字段名参与计算，不使用字段值参与计算；Header 字段也不参与签名。 **收集请求参数**合并 URL Query、表单 Body、JSON Body 中的顶层字段名。 **字段名统一转小写**例如 `Product_Key` 会按 `product_key` 参与签名。 **按自然顺序排序**排序规则需与服务端保持一致，PHP 可使用 `SORT_NATURAL`。 **使用 & 连接字段名**例如 `extra&product_key&target_product_key&user_id`。 **追加时间戳和 API Secret**最终字符串为 `字段名串 + timestamp + api_secret`。 **计算 SHA256**对最终字符串做 SHA256，得到十六进制签名。 #### 4.1 签名公式 [#](#4-toc-title) ``` sha256(sorted_lowercase_param_keys_joined_by_ampersand + timestamp + api_secret) ``` #### 4.2 示例推导 [#](#5-toc-title) 请求参数： ``` { "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 = sk_your_api_secret ``` 最终待签名字符串： ``` extra&product_key&target_product_key&user_id1776677721sk_your_api_secret ``` ### 5. 签名示例 [#](#6-toc-title) #### 5.1 JavaScript [#](#7-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); } ``` #### 5.2 PHP [#](#8-toc-title) ``` str: keys = sorted([key.lower() for key in params.keys()]) sign_string = "&".join(keys) + timestamp + api_secret return hashlib.sha256(sign_string.encode("utf-8")).hexdigest() ``` ### 6. 完整请求示例 [#](#11-toc-title) 以下示例展示一次注册事件回传请求的 Header 和 Body 结构。不同接口的 Body 字段可能不同，但签名生成方式保持一致。 ``` POST /api/open/v1/track/conversion HTTP/1.1 Host: api-service.partnershare.net Content-Type: application/json X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx X-Api-Timestamp: 1776677721 X-Api-Sign: 8473ee71d083d9d1650c0e9081b5777d5b6cde2508521d5322d603a007214afd ``` ``` { "event_name": "signup", "invited_user_id": "user_10001", "invite_code": "abc123" } ``` **本示例的签名字段名**参与签名的字段名为 `event_name`、`invited_user_id`、`invite_code`，排序后拼接为 `event_name&invite_code&invited_user_id`。 ### 7. 常见错误与排查 [#](#12-toc-title) #### 7.1 为什么提示“API Key 或签名不能为空”？ [#](#13-toc-title) 通常是请求头缺少 `X-Api-Key`、`X-Api-Timestamp` 或 `X-Api-Sign`。请确认 Header 名称拼写正确，并且请求没有被网关或代理移除自定义 Header。 #### 7.2 为什么提示“签名错误”？ [#](#14-toc-title) 请重点检查：是否使用 API Secret 而不是 API Key 参与签名；字段名是否转为小写；字段名排序是否一致；参与签名的字段是否与实际请求 Body 顶层字段完全一致。 #### 7.3 为什么本地签名正确，线上仍然失败？ [#](#15-toc-title) 常见原因是线上请求参数被序列化格式改变，例如本地使用 JSON，线上使用表单；或反向代理改变了请求 Body。建议先打印实际发送给 PartnerShare 的 Body 顶层字段名进行对比。 #### 7.4 时间戳有效期是多久？ [#](#16-toc-title) 当前时间戳有效期为 5 分钟。请使用秒级时间戳，并确保服务器时间与标准时间保持同步。 #### 7.5 API Secret 可以放在前端吗？ [#](#17-toc-title) 不可以。API Secret 一旦暴露，任何人都可以伪造合法请求。请始终在服务端生成签名，前端只调用自己的业务服务端。 ### 8. 最佳实践 [#](#18-toc-title) - 只在服务端保存 API Secret，不写入前端代码、移动端包体或公开配置。 - 每次请求都重新生成时间戳和签名，不复用历史签名。 - 签名前记录参与签名的字段名列表，便于排查联调问题。 - 生产环境和测试环境使用不同的 API Key 与 API Secret。 - 如怀疑 API Secret 泄露，应立即在后台重置密钥并更新服务端配置。 更新 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/signature](https://www.facebook.com/sharer/sharer.php?u=https://www.partnershare.net/help/api/signature) - [https://twitter.com/intent/tweet?url=https://www.partnershare.net/help/api/signature](https://twitter.com/intent/tweet?url=https://www.partnershare.net/help/api/signature) - [https://www.linkedin.com/shareArticle?mini=true&url=https://www.partnershare.net/help/api/signature](https://www.linkedin.com/shareArticle?mini=true&url=https://www.partnershare.net/help/api/signature) - [https://pinterest.com/pin/create/button/?url=https://www.partnershare.net/help/api/signature](https://pinterest.com/pin/create/button/?url=https://www.partnershare.net/help/api/signature) [将 PartnerShare 内嵌到产品中](https://www.partnershare.net/help/api/iframe) 大纲 - [1. 概述](#0-toc-title) - [2. 获取 API Key 和 API Secret](#1-toc-title) - [3. 请求头约定](#2-toc-title) - [4. 签名规则](#3-toc-title) - [4.1 签名公式](#4-toc-title) - [4.2 示例推导](#5-toc-title) - [5. 签名示例](#6-toc-title) - [5.1 JavaScript](#7-toc-title) - [5.2 PHP](#8-toc-title) - [5.3 Go](#9-toc-title) - [5.4 Python](#10-toc-title) - [6. 完整请求示例](#11-toc-title) - [7. 常见错误与排查](#12-toc-title) - [7.1 为什么提示“API Key 或签名不能为空”？](#13-toc-title) - [7.2 为什么提示“签名错误”？](#14-toc-title) - [7.3 为什么本地签名正确，线上仍然失败？](#15-toc-title) - [7.4 时间戳有效期是多久？](#16-toc-title) - [7.5 API Secret 可以放在前端吗？](#17-toc-title) - [8. 最佳实践](#18-toc-title)