来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 1. 背景
Brand Portal 为品牌提供表现数据，帮助品牌了解其在 Shopee 平台上的业务表现，覆盖 sales、affiliate marketing、livestream 和 video 等场景。目前，品牌通常需要手动从 Brand Portal 下载数据，以便进行进一步分析。该人工流程耗时较长，通常需要 1-2 小时，并限制了品牌进行自动化数据分析和日常表现监控的能力。
为提升数据集成效率，Shopee Open Platform 将提供 Brand Portal 表现数据相关 API。开发者可以使用这些 API 获取销售表现、联盟表现、直播表现和视频表现指标，并根据不同接口获取店铺级、主体级或内容/会话级的数据，将数据直接集成至品牌内部系统，用于业务分析、报表构建、表现监控和决策制定。
§2 2. 适用范围
- 支持站点：目前 Brand Portal 表现数据相关 API 支持 Taiwan (TW)、Philippines (PH)、Vietnam (VN)、Indonesia (ID)、Singapore (SG)、Thailand (TH)、Malaysia (MY)、Brazil (BR)。
- 应用类型：只有 Brand Portal Service APP 才有权限调用 Brand Portal 服务 API ，请在对接 API 前于 Console 创建一个 Brand Portal Service 类型的 APP。
- 请注意：使用该功能前请确认您是Brand Portal 的品牌用户，否则将无法进行使用。
§3 3. 授权与鉴权
#§4 3.1 用户授权
3.1 用户授权
§5 3.1.1 生成授权链接
3.1.1 生成授权链接
对于Principal Management类型的应用，开发者需要创建一个授权链接，授权链接由固定授权URL和其他所需参数拼接而成，逻辑如下：
固定授权URL:
- 生产环境：
- https://open.shopee.com/auth
- https://open.shopee.cn/auth
- https://open.shopee.com.br/auth
其他所需参数：
| Name | Type | Required | Description |
|---|---|---|---|
| partner_id | int64 | True | 您应用的 partner_id，由 Shopee Open Platform 分配。 |
| auth_type | string | True | 需要授权的角色类型及其枚举值如下：- 卖家：如果您需要授权卖家管理其自有店铺，请选择“卖家”；- 用户：如果您需要授权联盟主播，请选择“用户”；- 委托人：如果您需要在品牌门户中授权委托人，请选择“委托人”。 |
| redirect_uri | string | True | 主管理员完成授权后，用于接收验证码的 URL。redirect_uri 的域名必须与您在 Shopee Open Platform 上创建并上线应用时声明的域名一致。 |
| response_type | string | True | 授权类型，其值为“code”。 |
| state | string | False | 用于防范跨站请求伪造攻击的不可预测的随机字符串。 |
注意：如果授权的角色principal管理者，则auth_type需要选择“principal”。
授权链接样例：
- 生产环境：https://open.shopee.com/auth?partner_id=10090&auth_type=principal&redirect_uri=https://open.shopee.com&response_type=code
§6 3.1.2 登陆授权
3.1.2 登陆授权
开发者需要将授权链接分享给principal管理者，principal管理者登陆账号进入授权页面后，即可操作授权。
§7 3.1.3 获取授权code
3.1.3 获取授权code
授权成功后，Shopee会将授权code返回到回调地址redirect_uri，开发者可以获取并使用该code首次换取access_token。
| Name | Type | Description |
|---|---|---|
| code | string | 此代码用于获取 access_token 和 refresh_token。它仅可使用一次，并在 10 分钟后失效。 |
§8 3.1.4 获取access_token
3.1.4 获取access_token
access_token是一个动态令牌，开发者需要传递access_token才能调用非公共接口。
授权成功后，使用回调地址中的授权code，调用v2.public.get_access_token接口，来获取access_token和refresh_token。
公共请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| partner_id | int64 | True | 从应用程序中获取的 partner_id。该 partner_id 会被放入查询中。 |
| timestamp | timestamp | True | 时间戳，有效期为5分钟。 |
| sign | string | True | 通过使用 partner_key 对签名基础字符串（顺序：partner_id、api_path、timestamp）进行 HMAC-SHA256 哈希运算生成的签名。 |
业务请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | True | 授权后重定向 URL 中的代码。该代码仅可使用一次，并在 10 分钟后失效。 |
响应参数：
| Name | Type | Description |
|---|---|---|
| error | string | API 请求的错误代码；始终返回。当 API 调用成功时，返回的错误代码为空。 |
| message | string | 提供 API 请求的详细错误信息；始终返回。当 API 调用成功时，返回的错误消息为空。 |
| request_id | string | API 请求的 ID；始终返回。用于诊断问题。 |
| principal_id_list | int64[] | 如果授权角色为“主要管理员”，则返回该授权下的所有 principal_id；如果授权角色为“附属主播”，则返回空值。 |
| access_token | string | API 调用成功时返回。这是一个可重复使用的动态令牌，有效期为 4 小时。 |
| refresh_token | string | API 调用成功时返回。使用 refresh_token 获取新的 access_token。每个 principal_id 对应的有效期均为 30 天。 |
| expire_in | timestamp | API 调用成功时返回。access_token 的有效期，单位为秒。 |
注意：所有principal相关的Open API，公共请求参数均为principal_id，因此，授权完成后：
- 对于principal管理者，请妥善保管principal_id；
§9 3.1.5 刷新access_token
3.1.5 刷新access_token
每个access_token的有效期是4小时，4小时内可以多次使用，开发者需要在access token过期前，使用refresh_token调用v2.public.refresh_access_token接口，去刷新获得一个新的access_token (refresh_token是用来刷新access_token的一个参数，每一个refresh_token的有效期是30天)，调用后会同时返回一个新refresh_token和access_token，需要在下一次调用此接口时使用新refresh_token。
公共请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| partner_id | int64 | True | 从应用程序中获取的 partner_id。该 partner_id 会被放入查询中。 |
| timestamp | timestamp | True | 时间戳，有效期为5分钟。 |
| sign | string | True | 通过使用 partner_key 对签名基础字符串（顺序：partner_id、api_path、timestamp）进行 HMAC-SHA256 哈希运算生成的签名。 |
业务请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| refresh_token | string | True | 使用 refresh_token 获取新的 access_token。每个 refresh_token 的有效期为 30 天，且每个 principal_id 仅能使用一次。 |
| partner_id | int64 | True | 从应用程序获取的 partner_id。该 partner_id 将被插入到正文中。 |
| principal_id | int64 | True | Shopee 用于标识主体的唯一标识符。 |
响应参数：
| Name | Type | Description |
|---|---|---|
| error | string | API 请求的错误代码；始终返回。当 API 调用成功时，返回的错误代码为空。 |
| message | string | 提供 API 请求的详细错误信息；始终返回。当 API 调用成功时，返回的错误消息为空。 |
| request_id | string | API 请求的 ID；始终返回。用于诊断问题。 |
| partner_id | int64 | API 调用成功时返回。您用于此次刷新操作的 partner_id。 |
| principal_id | int64 | API 调用成功时返回。本次刷新操作的 principal_id。 |
| access_token | string | API 调用成功时返回。新的 access_token。这是一个可重复使用的动态令牌，有效期为 4 小时。 |
| refresh_token | string | API 调用成功时返回。新的 refresh_token。使用 refresh_token 获取新的 access_token。每个 principal_id 对应的有效期均为 30 天。 |
| expire_in | timestamp | API 调用成功时返回。access_token 的有效期，单位为秒。 |
§10 3.2 用户取消授权
3.2 用户取消授权
§11 3.2.1 通过取消授权链接
3.2.1 通过取消授权链接
取消授权链接的生成方式，与授权链接生成方式基本一致，但是固定授权URL需要变为固定取消授权URL，逻辑如下：
固定取消授权URL:
- 生产环境：
- https://open.shopee.com/cancel_auth
- https://open.shopee.cn/cancel_auth
- https://open.shopee.com.br/cancel_auth
取消授权链接样例：
- 生产环境：https://open.shopee.com/cancel_auth?partner_id=10090&auth_type=principal&redirect_uri=https://open.shopee.com&response_type=code
§12 3.2.2 通过Brand Portal后台
3.2.2 通过Brand Portal后台
Principal管理者也可以访问Brand Portal后台的Partner Management页面，查看其账号授权给了哪些Principal类型的应用及其授权截止日期，并且可以在该页面直接取消和应用的授权关系。
§13 3.3 接口鉴权
3.3 接口鉴权
Principal相关接口均为principal类型，与Shop类型接口鉴权的区别在于公共参数需要principal_id，同时sign计算的base string有区别。
下面是关于公共参数的说明：
| Name | Description |
|---|---|
| partner_id | 注册成功后将分配合作伙伴 ID。所有请求均需提供该 ID。 |
| timestamp | 此字段用于标明请求的时间戳。所有请求均需提供此字段。有效期为5分钟。 |
| access_token | 用于访问 API 的令牌，用于验证您对该 API 的访问权限。该令牌可多次使用，有效期为 4 小时。 |
| principal_id | Shopee 用于标识principal的唯一标识符。 |
| sign | 通过 HMAC-SHA256 hashing algorithm，基于 partner_id, api path, timestamp, access_token, principal_id 和 partner_key 生成的签名（具体取决于不同的 API）。 |
§14 4. 接口目录及其能力
本部分概述 Brand Portal Performance Data APIs 当前支持的表现数据类别、对应的 API 名称，以及每个 API 的核心能力。
| Category | API Name | API Description |
|---|---|---|
| Sales Performance | v2.principal.get_shop_sales_performance_detail | 按店铺查询销售表现数据。 |
| Sales Performance | v2.principal.get_principal_sales_performance_detail | 按地区查询销售表现数据。 |
| Affiliate Performance | v2.principal.get_shop_affiliate_performance | 按店铺查询联盟表现数据。 |
| Affiliate Performance | v2.principal.get_principal_affiliate_performance | 按地区查询联盟表现数据。 |
| Affiliate Performance | v2.principal.get_content_affiliate_performance | 按内容查询联盟表现数据。 |
| Livestream Performance | v2.principal.get_shop_livestream_performance | 按店铺查询直播表现数据。 |
| Livestream Performance | v2.principal.get_principal_livestream_performance | 按地区查询直播表现数据。 |
| Livestream Performance | v2.principal.get_session_livestream_performance | 按直播场次查询直播表现数据。 |
| Video Performance | v2.principal.get_shop_video_performance | 按店铺查询视频表现数据。 |
| Video Performance | v2.principal.get_principal_video_performance | 按地区查询视频表现数据。 |
| Video Performance | v2.principal.get_clip_video_performance | 按视频查询视频表现数据。 |
§15 5. API 调用流程
以下为不同业务情境下 API 的基本建议呼叫流程：
§16 5.1 通用流程
5.1 通用流程
Step 1：完成 principal 授权，并获取 principal_id、access_token 和 refresh_token。
Step 2：根据业务场景选择接口和数据层级，例如 principal、shop、content、session 或 video。
Step 3：填写必要查询条件，包括 start_date、end_date、timezone、granularity，以及适用时的 currency。
Step 4：调用接口。若不填写对应的 list 参数，接口默认查询该 principal 下当前可访问的全部对象。
Step 5：根据返回结果中的 ID 或维度信息，再发起更精确的后续查询。
§17 5.2 按业务场景调用
5.2 按业务场景调用
- Principal / Region 维度：使用 principal 级别接口查看整体表现。不传 region_list 时，默认返回该 principal 下所有可访问 region 的数据；传入 region_list 时，仅查询指定 region。
- Shop 维度：使用 shop 级别接口查看店铺表现。不传 shop_list 时，默认返回该 principal 下所有可访问 shop 的数据；传入 shop_list 时，仅查询指定 shop。
- Content / Session / Video 维度：使用对应对象级别接口查看内容、场次或视频表现。不传 content_list、session_list 或 video_list 时，接口默认查询该 principal 下所有可访问对象；传入对应 list 时，仅查询指定对象。
§18 5.3 分页建议
5.3 分页建议
对于 content、session、video 这类对象级接口，当不传对应 list 参数时，返回的数据量可能较大，建议配合分页参数使用。
- 首次请求时，传入 page_size，cursor 可不传或传 0。
- 接口返回当前页 details 数据，以及 next_cursor。
- 后续请求使用上一次返回的 next_cursor 继续查询下一页。
- 当返回的 details 数量小于本次请求的 page_size 时，通常表示已经查询到最后一页。
- 如果继续使用末尾 cursor 查询，接口会返回空的 details，同时 next_cursor 保持当前位置不变。
§19 5.4 使用建议
5.4 使用建议
- 如果只需要查看汇总结果，可读取 response 中的 summary。
- 若需要逐个对象处理明细数据，可读取 response 中的 details。
- 建议在首次全量查询后，保存返回的 shop_id、content_id、session_id 或 video_id，后续按指定对象发起精确查询，以减少数据量并提升调用效率。
§20 6. FAQ
Q1：这些 API 是否必须按 principal → shop → content/session/clip 的顺序调用？ 不需要。各接口可根据所需数据维度直接调用。若需要从整体表现逐步下钻，可先调用 principal 级别接口，再按 shop 或对象维度进行后续查询。
Q2：不传 region_list / shop_list / content_list / session_list / video_list 时，接口会返回什么数据？ 若 list 参数为空，则默认按该 principal 当前可访问范围查询所有数据。
Q3：什么时候需要使用分页参数？ 当调用 v2.principal.get_content_affiliate_performance、v2.principal.get_session_livestream_performance、v2.principal.get_clip_video_performance 接口，且不传对应 list 时，返回数据量可能较大，建议使用分页参数。