Hướng dẫn tích hợp API Livestream
1. Giới thiệu về Shopee Livestream
Shopee Livestream là công cụ marketing theo thời gian thực do nền tảng cung cấp, cho phép streamer giới thiệu và quảng bá sản phẩm qua video trực tiếp trong khi tương tác với khán giả. Trong quá trình phát sóng, người xem có thể tương tác với streamer, đặt câu hỏi về sản phẩm và đặt hàng ngay lập tức. Shopee Livestream hỗ trợ nhiều vai trò như streamer người bán và streamer đối tác liên kết, phù hợp với nhiều tình huống kinh doanh khác nhau.
Shopee Open Platform cung cấp bộ Open API liên quan đến livestream, bao gồm quản lý phiên livestream, quản lý sản phẩm, tương tác bình luận và truy xuất dữ liệu thời gian thực. Nhà phát triển có thể tận dụng các khả năng API này để xây dựng hệ thống quản lý livestream cho streamer.
2. Quản lý ứng dụng
- Thị trường được hỗ trợ: Hiện tại, Livestream OpenAPI có sẵn cho Đài Loan (TW), Indonesia (ID), Thái Lan (TH), Philippines (PH), Malaysia (MY), Singapore (SG), Việt Nam (VN).
- Vai trò được hỗ trợ: Hỗ trợ hai loại vai trò — Streamer người bán và Streamer đối tác liên kết.
- Loại ứng dụng: Chỉ các ứng dụng Quản lý Livestream mới đủ điều kiện truy cập Livestream OpenAPI. Vui lòng tạo loại ứng dụng Quản lý Livestream trong Console trước khi tích hợp.
3. Ủy quyền & Xác thực
3.1 Ủy quyền
3.1.1 Tạo liên kết ủy quyền
Đối với ứng dụng Quản lý Livestream, nhà phát triển cần tạo liên kết ủy quyền, bao gồm URL Ủy quyền cố định và Tham số bắt buộc:
URL Ủy quyền cố định:
-
Môi trường Live：
-
Môi trường Sandbox：
Tham số bắt buộc：
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| partner_id | int64 | Có | partner_id của ứng dụng, được cấp bởi Shopee Open Platform. |
| auth_type | string | Có | Loại vai trò cần ủy quyền, các giá trị liệt kê như sau:- seller: Nếu cần ủy quyền người bán với shop của họ, chọn "seller";- user: Nếu cần ủy quyền streamer đối tác liên kết, chọn "user". |
| redirect_uri | string | Có | URL dùng để nhận mã sau khi người bán hoàn tất ủy quyền. Tên miền của redirect_uri phải nhất quán với tên miền được khai báo khi tạo và phát hành ứng dụng trên Shopee Open Platform. |
| response_type | string | Có | Loại ủy quyền, với giá trị là "code". |
| state | string | Không | Chuỗi ngẫu nhiên không thể đoán được để bảo vệ chống tấn công cross-site request forgery. |
Lưu ý：Nếu vai trò được ủy quyền là streamer người bán, đặt auth_type thành "seller". Nếu vai trò được ủy quyền là streamer đối tác liên kết, đặt auth_type thành "user".
Ví dụ liên kết ủy quyền：
-
Môi trường Live：https://open.shopee.com/auth?partner\_id=10090&auth\_type=seller&redirect\_uri=https://open.shopee.com&response\_type=code
-
Môi trường Sandbox：https://open.test-stable.shopee.com/auth?partner\_id=1000016&auth\_type=seller&redirect\_uri=https://open.test-stable.shopee.com&response\_type=code
3.1.2 Đăng nhập để ủy quyền
Nhà phát triển cần chia sẻ liên kết ủy quyền với streamer người bán hoặc streamer đối tác liên kết. Sau khi đăng nhập, họ sẽ được chuyển đến trang ủy quyền để tiếp tục.
3.1.3 Lấy mã ủy quyền
Sau khi ủy quyền thành công, Shopee sẽ trả về mã ủy quyền đến URL callback (redirect_uri). Nhà phát triển có thể lấy và sử dụng mã này để lấy access_token lần đầu tiên.
| Tên | Kiểu | Mô tả |
|---|---|---|
| code | string | Mã này được dùng để lấy access_token và refresh_token. Chỉ có hiệu lực một lần và hết hạn sau 10 phút. |
3.1.4 Lấy access_token
access_token là token động. Nhà phát triển phải bao gồm access_token khi gọi các API không công khai.
Sau khi ủy quyền thành công, sử dụng mã ủy quyền từ URL callback để gọi API v2.public.get_access_token để lấy access_token và refresh_token.
Tham số yêu cầu chung：
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| partner_id | int64 | Có | partner_id lấy từ App. partner_id này được đặt vào query. |
| timestamp | timestamp | Có | Timestamp, có hiệu lực 5 phút. |
| sign | string | Có | Chữ ký thu được bằng cách băm chuỗi ký hiệu (thứ tự: partner_id, api_path, timestamp) với partner_key qua thuật toán HMAC-SHA256. |
Tham số yêu cầu nghiệp vụ：
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| code | string | Có | Mã trong URL chuyển hướng sau khi ủy quyền. Chỉ có hiệu lực một lần và hết hạn sau 10 phút. |
Tham số phản hồi：
| Tên | Kiểu | Mô tả |
|---|---|---|
| error | string | Mã lỗi cho yêu cầu API; luôn được trả về. Khi gọi API thành công, mã lỗi trả về là rỗng. |
| message | string | Cung cấp thông tin lỗi chi tiết cho yêu cầu API; luôn được trả về. Khi gọi API thành công, thông báo lỗi trả về là rỗng. |
| request_id | string | ID của yêu cầu API; luôn được trả về. Dùng để chẩn đoán vấn đề. |
| shop_id_list | int64[] | Nếu vai trò được ủy quyền là người bán, trả về tất cả shop_id trong lần ủy quyền này. Nếu vai trò được ủy quyền là streamer đối tác liên kết, trả về rỗng. |
| user_id_list | int64[] | Nếu vai trò được ủy quyền là người bán, trả về tất cả user_id tương ứng với shop_id trong lần ủy quyền này. shop_id_list và user_id_list theo thứ tự một-một, nghĩa là user_id đầu tiên trong user_id_list tương ứng với shop_id đầu tiên trong shop_id_list. Lưu ý: Tất cả API trong module Livestream yêu cầu user_id (không phải shop_id) làm Tham số Yêu cầu Chung. |
| access_token | string | Được trả về khi gọi API thành công. Token động có thể sử dụng nhiều lần và hết hạn sau 4 giờ. |
| refresh_token | string | Được trả về khi gọi API thành công. Sử dụng refresh_token để lấy access_token mới. Có hiệu lực cho mỗi shop_id và user_id tương ứng, trong 30 ngày. |
| expire_in | timestamp | Được trả về khi gọi API thành công. Thời hạn hiệu lực của access_token, tính bằng giây. |
Lưu ý: Tất cả Open API liên quan đến livestream yêu cầu user_id làm tham số yêu cầu chung. Do đó, sau khi ủy quyền thành công:
- Đối với streamer người bán, vui lòng lưu trữ an toàn cả shop_id và user_id tương ứng.
- Đối với streamer đối tác liên kết, vui lòng lưu trữ an toàn user_id.
3.1.5 Làm mới access_token
Mỗi access_token có hiệu lực 4 giờ và có thể sử dụng nhiều lần trong khoảng thời gian đó. Nhà phát triển cần làm mới access_token trước khi hết hạn bằng cách gọi API v2.public.refresh_access_token sử dụng refresh_token. refresh_token được dùng cụ thể để làm mới access_token, và mỗi refresh_token có hiệu lực 30 ngày. Sau lần gọi, một cặp access_token và refresh_token mới sẽ được trả về. Hãy đảm bảo sử dụng refresh_token mới cho yêu cầu làm mới tiếp theo.
Tham số yêu cầu chung：
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| partner_id | int64 | Có | partner_id lấy từ App. partner_id này được đặt vào query. |
| timestamp | timestamp | Có | Timestamp, có hiệu lực 5 phút. |
| sign | string | Có | Chữ ký thu được bằng cách băm chuỗi ký hiệu (thứ tự: partner_id, api_path, timestamp) với partner_key qua thuật toán HMAC-SHA256. |
Tham số yêu cầu nghiệp vụ：
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| refresh_token | string | Có | Sử dụng refresh_token để lấy access_token mới. Mỗi refresh_token có hiệu lực 30 ngày và chỉ có thể sử dụng một lần cho mỗi user_id. |
| partner_id | int64 | Có | partner_id lấy từ App. partner_id này được chèn vào body. |
| user_id | int64 | Có | Mã định danh duy nhất của Shopee cho một người dùng. |
Tham số phản hồi：
| Tên | Kiểu | Mô tả |
|---|---|---|
| error | string | Mã lỗi cho yêu cầu API; luôn được trả về. Khi gọi API thành công, mã lỗi trả về là rỗng. |
| message | string | Cung cấp thông tin lỗi chi tiết cho yêu cầu API; luôn được trả về. Khi gọi API thành công, thông báo lỗi trả về là rỗng. |
| request_id | string | ID của yêu cầu API; luôn được trả về. Dùng để chẩn đoán vấn đề. |
| partner_id | int64 | Được trả về khi gọi API thành công. partner_id bạn đã dùng cho lần làm mới này. |
| user_id | int64 | Được trả về khi gọi API thành công. user_id cho lần làm mới này. |
| access_token | string | Được trả về khi gọi API thành công. access_token mới. Token động có thể sử dụng nhiều lần và hết hạn sau 4 giờ. |
| refresh_token | string | Được trả về khi gọi API thành công. refresh_token mới. Sử dụng refresh_token để lấy access_token mới. Có hiệu lực cho mỗi shop_id và user_id tương ứng, trong 30 ngày. |
| expire_in | timestamp | Được trả về khi gọi API thành công. Thời hạn hiệu lực của access_token, tính bằng giây. |
3.2 Hủy ủy quyền
3.2.1 Qua liên kết hủy ủy quyền
Tạo liên kết hủy ủy quyền tương tự như ủy quyền, nhưng với URL Hủy ủy quyền cố định khác:
URL Hủy ủy quyền cố định:
-
Môi trường Live：
-
Môi trường Sandbox：
Ví dụ liên kết hủy ủy quyền：
-
Môi trường Live：https://open.shopee.com/cancel\_auth?partner\_id=10090&auth\_type=seller&redirect\_uri=https://open.shopee.com&response\_type=code
-
Môi trường Sandbox：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
Sau khi tạo liên kết hủy ủy quyền, nhà phát triển nên chia sẻ nó với streamer người bán hoặc streamer đối tác liên kết. Sau khi họ đăng nhập vào tài khoản và truy cập trang hủy ủy quyền, họ có thể tiến hành hủy ủy quyền.
3.2.2 Qua Livestream PC Backend
Streamer người bán và streamer đối tác liên kết cũng có thể truy cập trang Quản lý đối tác live trong Livestream PC Backend để xem ứng dụng loại Livestream nào mà tài khoản của họ đã ủy quyền và ngày hết hạn tương ứng. Họ cũng có thể hủy liên kết bất kỳ ủy quyền nào trực tiếp trên trang đó.
Lưu ý: Streamer người bán cũng có thể truy cập trang Nền tảng đối tác trong Seller Center để xem tất cả ứng dụng mà tài khoản của họ đã ủy quyền (bao gồm nhưng không giới hạn ở ứng dụng loại Livestream) và hủy liên kết ủy quyền từ đó.
3.3 Xác thực API
API Livestream là API loại User, nghĩa là:
- Sử dụng user_id trong tham số chung
- Chuỗi ký hiệu khác với API loại Shop (bao gồm user_id và access_token tương ứng)
Tham số yêu cầu chung：
| Tên | Mô tả |
|---|---|
| partner_id | Partner ID được cấp khi đăng ký thành công. Bắt buộc cho tất cả yêu cầu. |
| timestamp | Chỉ ra timestamp của yêu cầu. Bắt buộc cho tất cả yêu cầu. Hết hạn sau 5 phút. |
| access_token | Token để truy cập API, dùng để xác định quyền của bạn đối với API. Có hiệu lực cho nhiều lần sử dụng và hết hạn sau 4 giờ. |
| user_id | Mã định danh duy nhất của Shopee cho một người dùng. |
| sign | Chữ ký được tạo bởi (tùy thuộc vào API khác nhau) partner_id, api path, timestamp, access_token, user_id và partner_key qua thuật toán băm HMAC-SHA256. |
4. Danh mục API & Khả năng
Dưới đây là danh sách các API liên quan đến livestream hiện có và tổng quan chức năng của chúng:
| Danh mục | Tên API | Mô tả API |
|---|---|---|
| Quản lý phiên Livestream | v2.livestream.upload_image | Tải lên hình ảnh làm ảnh bìa livestream và lấy URL hình ảnh. |
| v2.livestream.create_session | Tạo phiên livestream mới, bao gồm ảnh bìa, tiêu đề, mô tả và loại (live thử hoặc live thường). | |
| v2.livestream.update_session | Cập nhật thông tin phiên livestream, bao gồm ảnh bìa, tiêu đề, mô tả và loại (live thử hoặc live thường). | |
| v2.livestream.start_session | Bắt đầu livestream. | |
| v2.livestream.end_session | Kết thúc livestream. | |
| v2.livestream.get_session_detail | Lấy chi tiết phiên livestream (bao gồm ảnh bìa, tiêu đề, mô tả, loại, thời gian tạo, thời gian cập nhật và URL luồng đẩy). | |
| Quản lý sản phẩm | v2.livestream.add_item_list | Thêm sản phẩm vào livestream. |
| v2.livestream.delete_item_list | Xóa sản phẩm khỏi livestream. | |
| v2.livestream.update_item_list | Sắp xếp lại sản phẩm trong livestream. | |
| v2.livestream.get_item_count | Lấy số lượng sản phẩm trong livestream, bao gồm số lượng sản phẩm hiện tại và giới hạn tối đa. | |
| v2.livestream.get_item_list | Lấy danh sách sản phẩm trong livestream, bao gồm item id, số thứ tự sản phẩm, v.v. | |
| v2.livestream.update_show_item | Đặt một sản phẩm làm sản phẩm đang hiển thị. | |
| v2.livestream.delete_show_item | Xóa sản phẩm đang hiển thị. | |
| v2.livestream.get_show_item | Lấy sản phẩm đang hiển thị hiện tại. | |
| v2.livestream.get_like_item_list | Lấy danh sách sản phẩm "Yêu thích" (danh sách sản phẩm được thích bởi streamer người bán hoặc streamer đối tác liên kết). | |
| v2.livestream.get_recent_item_list | Lấy danh sách sản phẩm "Gần đây" (danh sách sản phẩm được streamer người bán hoặc streamer đối tác liên kết sử dụng trong livestream gần nhất). | |
| Quản lý bộ sản phẩm | v2.livestream.get_item_set_list | Lấy danh sách bộ sản phẩm, bao gồm tên bộ sản phẩm, id và số lượng sản phẩm. |
| v2.livestream.get_item_set_item_list | Lấy sản phẩm trong một bộ sản phẩm. | |
| v2.livestream.apply_item_set | Thêm toàn bộ bộ sản phẩm vào livestream. | |
| Truy xuất dữ liệu thời gian thực | v2.livestream.get_session_metric | Lấy dữ liệu chỉ số thời gian thực của phiên livestream, bao gồm số lượt thích, bình luận, chia sẻ, lượt xem, v.v. |
| v2.livestream.get_session_item_metric | Lấy dữ liệu chỉ số thời gian thực của sản phẩm livestream, bao gồm lượt nhấp sản phẩm, thêm vào giỏ hàng, v.v. | |
| Tương tác bình luận | v2.livestream.get_latest_comment_list | Lấy bình luận livestream trong một khoảng thời gian nhất định, bao gồm user id, tên người dùng, comment id, nội dung bình luận và thời gian bình luận. |
| v2.livestream.post_comment | Đăng bình luận trong livestream với tư cách streamer. | |
| v2.livestream.ban_user_comment | Cấm người dùng đăng bình luận. | |
| v2.livestream.unban_user_comment | Bỏ cấm người dùng đăng bình luận. |
5. Luồng gọi API
Dưới đây là trình tự gọi API được khuyến nghị cho một hoạt động livestream thông thường:
Bước 1：Tải lên hình ảnh bìa livestream → v2.livestream.upload_image
Bước 2：Tạo phiên livestream → v2.livestream.create_session
Bước 3：Thêm sản phẩm vào livestream → v2.livestream.add_item_list (Thêm sản phẩm cụ thể vào livestream theo item_id) / v2.livestream.apply_item_set (Thêm tất cả sản phẩm từ một bộ sản phẩm vào livestream)
Bước 4：Lấy URL luồng đẩy → v2.livestream.get_session_detail
Bước 5：Bắt đầu phát sóng qua OBS → Sử dụng phần mềm phát sóng OBS để phát livestream
Bước 6：Chính thức bắt đầu livestream → v2.livestream.start_session
Bước 7：Quản lý sản phẩm hiển thị → v2.livestream.update_show_item / v2.livestream.delete_show_item
Bước 8：Lấy dữ liệu thời gian thực → v2.livestream.get_session_metric / v2.livestream.get_session_item_metric
Bước 9：Lấy và quản lý bình luận → v2.livestream.get_latest_comment_list / v2.livestream.post_comment
Bước 10：Kết thúc livestream → v2.livestream.end_session
Lưu ý：
1）Đối với streamer đối tác liên kết, có ba cách để thêm sản phẩm vào livestream：
- Yêu thích：Gọi v2.livestream.get_like_item_list để lấy danh sách sản phẩm đã thích, chọn sản phẩm mong muốn, sau đó gọi v2.livestream.add_item_list để thêm chúng vào livestream theo lô.
- Gần đây：Gọi v2.livestream.get_recent_item_list để lấy danh sách sản phẩm được sử dụng trong livestream gần nhất, chọn sản phẩm mong muốn, sau đó gọi v2.livestream.add_item_list để thêm chúng vào livestream theo lô.
- Bộ sản phẩm：Gọi v2.livestream.get_item_set_list để lấy tất cả bộ sản phẩm đã tạo, sau đó gọi v2.livestream.get_item_set_item_list để lấy sản phẩm trong một bộ cụ thể, và cuối cùng sử dụng v2.livestream.apply_item_set để thêm tất cả sản phẩm từ bộ đó vào livestream.
2）Đối với streamer người bán, ngoài ba phương pháp trên, họ cũng có thể thêm sản phẩm qua:
- Shop của tôi：Gọi v2.product.get_item_list để lấy danh sách sản phẩm từ shop của họ, chọn sản phẩm mong muốn, sau đó gọi v2.livestream.add_item_list để thêm chúng vào livestream theo lô.