来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 1. 初识Shopee直播
Shopee直播是平台为主播提供的一种即时营销工具，允许主播通过视频直播的方式向观众展示商品、介绍商品并进行实时互动。直播过程中，观众可以与主播实时互动、提问商品相关问题，并下单购买商品。Shopee直播支持卖家主播、Affiliate主播等角色，适用于多样化的经营场景。
Shopee开放平台提供了一系列直播相关的Open API接口，包括直播间管理、直播商品管理、评论互动及直播数据获取等，开发者可通过Shopee提供的接口能力，为主播构建直播管理系统。
§2 2. 适用范围
- 适用站点：目前直播Open API已开放 台湾 (TW)、印尼 (ID)、泰国 (TH) 、菲律宾 (PH)、马来西亚 (MY)、新加坡 (SG)、越南 (VN) 七个站点。
- 授权对象：支持 卖家主播、Affiliate主播 两种角色。
- 应用类型：仅限 Livestream Management 类型的应用，具有调用直播Open API的权限，请先在Console创建 Livestream Management 类型的应用。
§3 3. 授权与鉴权
#§4 3.1 用户授权
3.1 用户授权
§5 3.1.1 生成授权链接
3.1.1 生成授权链接
对于Livestream Management类型的应用，开发者需要创建一个授权链接，授权链接由固定授权URL和其他所需参数拼接而成，逻辑如下：
固定授权URL:
- 生产环境：
- https://open.shopee.com/auth
- https://open.shopee.cn/auth
- https://open.shopee.com.br/auth
- 沙箱测试环境：
- https://open.test-stable.shopee.com/auth
- https://open.test-stable.shopee.cn/auth
- https://open.test-stable.shopee.com.br/auth
其他所需参数：
| Name | Type | Required | Description |
|---|---|---|---|
| partner_id | int64 | True | The partner_id of your application, assigned by Shopee Open Platform. |
| auth_type | string | True | The type of roles need to authorize, the enumeration values are as follows:- seller: If you need to authorize seller with their own shops, please select "seller";- user: If you need to authorize affiliate streamer, please select "user". |
| redirect_uri | string | True | The URL used for receiving the code after seller completes the authorization.The domain of redirect_uri must be consistent with the domain declared when you create and go live the application on Shopee Open Platform. |
| response_type | string | True | The authorization type, with the value of "code". |
| state | string | False | An unguessable random string for protecting against cross-site request forgery attacks. |
注意：如果授权的角色是卖家主播，则auth_type需要选择“seller”，如果授权的角色是Affiliate主播，则auth_type需要选择“user”。
授权链接样例：
- 生产环境：https://open.shopee.com/auth?partner_id=10090&auth_type=seller&redirect_uri=https://open.shopee.com&response_type=code
- 沙箱测试环境：https://open.test-stable.shopee.com/auth?partner_id=1000016&auth_type=seller&redirect_uri=https://open.test-stable.shopee.com&response_type=code
§6 3.1.2 登陆授权
3.1.2 登陆授权
开发者需要将授权链接分享给卖家主播/Affiliate主播，卖家主播/Affiliate主播登陆账号进入授权页面后，即可操作授权。
§7 3.1.3 获取授权code
3.1.3 获取授权code
授权成功后，Shopee会将授权code返回到回调地址redirect_uri，开发者可以获取并使用该code首次换取access_token。
| Name | Type | Description |
|---|---|---|
| code | string | This code is used to obtain access_token and refresh_token. It is valid for only once and expires after 10 minutes. |
§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 | The partner_id obtained from the App. This partner_id is put into the query. |
| timestamp | timestamp | True | Timestamp, valid for 5 minutes. |
| sign | string | True | The signature obtained by sign base string (order: partner_id, api_path, timestamp) HMAC-SHA256 hashing with partner_key. |
业务请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | True | The code in the redirect URL after authorization. It is only valid once and expires after 10 minutes. |
响应参数：
| Name | Type | Description |
|---|---|---|
| error | string | Error code for API requests; always returned.When the API call is successful, the error code returned is empty. |
| message | string | Provides Detailed error information for API requests; always returned.When the API call is successful, the error message returned is empty. |
| request_id | string | ID of API requests; always returned. Used to diagnose problems. |
| shop_id_list | int64[] | If the authorized role is seller, return all shop_id under this authorization.If the authorized role is affiliate streamer, return empty. |
| user_id_list | int64[] | If the authorized role is seller, return all user_id corresponding to shop_id under this authorization.The shop_id_list and user_id_list are in a one-to-one order, which means that the first user_id in user_id_list corresponds to the first shop_id in shop_id_list.Note: All APIs under Livestream module require user_id (not shop_id) as Common Request Parameter. |
| access_token | string | Returned when the API call is successful.A dynamic token that can be used multiple times and expires after 4 hours. |
| refresh_token | string | Returned when the API call is successful.Use refresh_token to get a new access_token. Valid for each shop_id and user_id respectively, for 30 days. |
| expire_in | timestamp | Returned when the API call is successful.The validity period of the access_token, in seconds. |
注意：所有直播相关的Open API，公共请求参数均为user_id，因此，授权完成后：
- 对于卖家主播，请妥善保管shop_id及其user_id信息；
- 对于Affiliate主播，授权完成后，请妥善保管user_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 | The partner_id obtained from the App. This partner_id is put into the query. |
| timestamp | timestamp | True | Timestamp, valid for 5 minutes. |
| sign | string | True | The signature obtained by sign base string (order: partner_id, api_path, timestamp) HMAC-SHA256 hashing with partner_key. |
业务请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| refresh_token | string | True | Use refresh_token to get a new access_token. Each refresh_token is valid for 30 days, and can only be used once by each user_id. |
| partner_id | int64 | True | The partner_id obtained from the App. This partner_id is inserted into the body. |
| user_id | int64 | True | Shopee's unique identifier for a user. |
响应参数：
| Name | Type | Description |
|---|---|---|
| error | string | Error code for API requests; always returned.When the API call is successful, the error code returned is empty. |
| message | string | Provides Detailed error information for API requests; always returned.When the API call is successful, the error message returned is empty. |
| request_id | string | ID of API requests; always returned. Used to diagnose problems. |
| partner_id | int64 | Returned when the API call is successful.The partner_id you used for this refresh. |
| user_id | int64 | Returned when the API call is successful.The user_id for this refresh. |
| access_token | string | Returned when the API call is successful.New access_token. A dynamic token that can be used multiple times and expires after 4 hours. |
| refresh_token | string | Returned when the API call is successful.New refresh_token. Use refresh_token to get a new access_token. Valid for each shop_id and user_id respectively, for 30 days. |
| expire_in | timestamp | Returned when the API call is successful.The validity period of the access_token, in seconds. |
§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.test-stable.shopee.com/cancel_auth
- https://open.test-stable.shopee.cn/cancel_auth
- https://open.test-stable.shopee.com.br/cancel_auth
取消授权链接样例：
- 生产环境：https://open.shopee.com/cancel_auth?partner_id=10090&auth_type=seller&redirect_uri=https://open.shopee.com&response_type=code
- 沙箱测试环境：https://open.test-stable.shopee.com/cancel_auth?partner_id=1000016&auth_type=seller&redirect_uri=https://open.test-stable.shopee.com&response_type=code
开发者生成取消授权链接后，将链接分享给卖家主播/Affiliate主播，卖家主播/Affiliate主播登录账号进入取消授权页面，即可取消授权。
§12 3.2.2 通过Livestream后台
3.2.2 通过Livestream后台
卖家主播/Affiliate主播也可以访问Livestream PC后台的Live Partner Management页面，查看其账号授权给了哪些Livestream类型的应用及其授权截止日期，并且可以在该页面直接取消和应用的授权关系。
注意：对于卖家主播而言，仍然可以访问Seller Center的Partner Platform页面，查看其账号授权的所有应用 (包括但不限于Livestream类型的应用)，并且在该页面取消授权。
§13 3.3 接口鉴权
3.3 接口鉴权
直播相关接口均为User类型，与Shop类型接口鉴权的区别在于公共参数需要user_id，同时sign计算的base string有区别。
下面是关于公共参数的说明：
| Name | Description |
|---|---|
| partner_id | Partner ID is assigned upon registration is successful. Required for all requests. |
| timestamp | This is to indicate the timestamp of the request. Required for all requests. Expires in 5 minutes. |
| access_token | The token for API access, using to identify your permission to the api. Valid for multiple use and expires in 4 hours. |
| user_id | Shopee's unique identifier for a user. |
| sign | Signature generated by (depends on different APIs) partner_id, api path, timestamp, access_token, user_id and partner_key via HMAC-SHA256 hashing algorithm. |
§14 4. 接口目录及其能力
以下是目前开放的直播相关接口分类及其功能概述：
| 接口分类 | 接口名称 | 功能概述 |
|---|---|---|
| 直播间管理 | v2.livestream.upload_image | 上传直播间封面图片，获取图片URL |
| v2.livestream.create_session | 创建直播间 (设置封面、标题、描述、类型) | |
| v2.livestream.update_session | 更新直播间基础信息 (封面、标题、描述、类型) | |
| v2.livestream.start_session | 开始直播 | |
| v2.livestream.end_session | 结束直播 | |
| v2.livestream.get_session_detail | 获取直播间详情信息 (包括封面、标题、描述、类型、创建时间、更新时间、推流地址) | |
| 商品管理 | v2.livestream.add_item_list | 添加商品至直播间购物袋 |
| v2.livestream.delete_item_list | 从购物袋中移除商品 | |
| v2.livestream.update_item_list | 调整购物袋中的商品顺序 | |
| v2.livestream.get_item_count | 获取购物袋商品数量及上限 | |
| v2.livestream.get_item_list | 获取购物袋商品列表 | |
| v2.livestream.update_show_item | 设置某商品为展示商品 | |
| v2.livestream.delete_show_item | 取消展示商品 | |
| v2.livestream.get_show_item | 获取当前展示商品 | |
| v2.livestream.get_like_item_list | 获取“My Likes”商品列表 (即：卖家主播/Affiliate主播收藏的商品列表) | |
| v2.livestream.get_recent_item_list | 获取“Recently”商品列表 (即：卖家主播/Affiliate主播上一次直播使用过的商品列表) | |
| 商品组管理 | v2.livestream.get_item_set_list | 获取商品组列表 |
| v2.livestream.get_item_set_item_list | 获取某商品组下的商品列表 | |
| v2.livestream.apply_item_set | 将某商品组批量加入购物袋 | |
| 实时数据获取 | v2.livestream.get_session_metric | 获取直播间互动数据 (观看、点赞、评论等) |
| v2.livestream.get_session_item_metric | 获取商品维度的点击/加购数据 | |
| 评论与互动管理 | v2.livestream.get_latest_comment_list | 获取一段时间内的直播评论列表 |
| v2.livestream.post_comment | 主播身份发布评论 | |
| v2.livestream.ban_user_comment | 禁言指定用户 | |
| v2.livestream.unban_user_comment | 解除禁言用户 |
§15 5. 接口调用流程
以下为典型直播操作的接口调用顺序建议：
Step 1：上传直播间封面 → v2.livestream.upload_image
Step 2：创建直播间 → v2.livestream.create_session
Step 3：添加直播商品 → v2.livestream.add_item_list (通过item_id添加指定商品到购物袋) / v2.livestream.apply_item_set (将商品组内的商品全部添加到购物袋)
Step 4：获取推流地址 → v2.livestream.get_session_detail
Step 5：主播推流启动 → 使用OBS推流工具进行直播推流
Step 6：正式开播 → v2.livestream.start_session
Step 7：动态展示商品 → v2.livestream.update_show_item / v2.livestream.delete_show_item
Step 8：获取实时互动数据 → v2.livestream.get_session_metric / v2.livestream.get_session_item_metric
Step 9：获取与处理评论 → v2.livestream.get_latest_comment_list / v2.livestream.post_comment
Step 10：结束直播 → v2.livestream.end_session
注意：
1）对于Affiliate主播，可以通过以下三种方式向直播间添加商品：
- My Likes：调用v2.livestream.get_like_item_list，获取My Likes的商品列表，从中选择需要添加至直播间的商品，再通过v2.livestream.add_item_list，批量将商品添加至直播间
- Recently：调用v2.livestream.get_recent_item_list，获取Recently的商品列表，从中选择需要添加至直播间的商品，再通过v2.livestream.add_item_list，批量将商品添加至直播间
- Product Set：调用v2.livestream.get_item_set_list，获取所有已创建的商品组列表，再通过v2.livestream.get_item_set_item_list，获取商品组下的商品列表，最后调用v2.livestream.apply_item_set，将商品组内的商品全部添加到购物袋
2）对于卖家主播，除了上述三种方式外，还可以通过以下方式向直播间添加商品：
- My Shop：调用v2.product.get_item_list，获取店铺的商品列表，从中选择需要添加至直播间的商品，再通过v2.livestream.add_item_list，批量将商品添加至直播间