Chuyển tới nội dung chính

Gọi API

⚠️ Lưu ý: Hướng dẫn này chỉ áp dụng cho việc gọi API với Shopee Open API v2.0.

Tên miền API

Có 3 tên miền khả dụng:

Chọn tên miền phù hợp dựa trên vị trí máy chủ bạn đang dùng để truy cập Open API.

Phương thức yêu cầu API

Hiện tại, Open API chỉ cung cấp hai phương thức yêu cầu: GET và POST.

Giao thức API

HTTP/JSON cho hầu hết các API. HTTP/FORM cho một số API nhất định, ví dụ như API tải lên tệp.

Tham số yêu cầu API

Trong tài liệu API, bạn sẽ thấy hai loại tham số yêu cầu:

  1. Tham số chung
  2. Tham số yêu cầu

Đối với API kiểu GET, hai tham số này có thể tồn tại đồng thời, hoặc chỉ có tham số chung.

Đối với API kiểu POST, hai tham số này sẽ tồn tại đồng thời.

Bảng dưới đây mô tả các tham số chung:

Tham sốMô tả
partner_idTất cả các lần gọi API đều yêu cầu partner ID. Bạn có thể lấy partner ID bằng cách tạo ứng dụng trên trang danh sách ứng dụng trong Shopee Open Platform Console. Test partner ID chỉ có thể dùng trong môi trường kiểm thử, và Live partner ID chỉ có thể dùng trong môi trường thực.
timestampTất cả các lần gọi API đều yêu cầu timestamp. Ví dụ về timestamp: 1610000000. Mỗi yêu cầu API cần được gửi trong vòng 5 phút từ thời điểm timestamp.
signTất cả các lần gọi API đều yêu cầu chữ ký được tạo bằng thuật toán SHA256. Các loại API khác nhau có phương pháp tạo chữ ký khác nhau. Để biết thêm chi tiết, hãy tham khảo phần Tính toán chữ ký trong bài viết này.
access_tokenAccess token là bắt buộc để lấy và chỉnh sửa các API liên quan đến dữ liệu người bán. Mỗi access token có hiệu lực trong 4 giờ và có thể được tái sử dụng trong thời gian hiệu lực. Access token cần được làm mới định kỳ. Tham khảo bài viết Ủy quyền và xác thực để tìm hiểu thêm về cách lấy và làm mới access token.
shop_idID nhận dạng duy nhất của một cửa hàng Shopee, có thể lấy được sau khi cửa hàng đã cấp ủy quyền. Tham khảo bài viết Ủy quyền và xác thực để biết cách lấy shop ID.
merchant_idID nhận dạng duy nhất của một merchant Shopee, có thể lấy được sau khi cửa hàng đã cấp ủy quyền. Open API chỉ hỗ trợ người bán xuyên biên giới sử dụng merchant ID. Tham khảo bài viết Ủy quyền và xác thực để biết cách lấy merchant ID.

Các loại Open API

Trong tài liệu API, có 3 loại API do các tham số chung khác nhau. Các tham số chung của 3 loại này như sau:

  • Shop API: partner_id, timestamp, sign, access_token, shop_id
  • Merchant API: partner_id, timestamp, sign, access_token, merchant_id
  • Public API: partner_id, timestamp, sign

⚠️ Lưu ý: Các mục màu đỏ được đánh dấu để chỉ ra rằng chúng khác với Public API.

Public API không yêu cầu access token, trong khi cả Shop và Merchant API đều có.

Điều này có nghĩa là Shop và Merchant API chỉ có thể được gọi sau khi cửa hàng đã cấp ủy quyền.

Hiện tại, chỉ các merchant xuyên biên giới của Shopee mới cần sử dụng Merchant API. Người bán trong nước không cần sử dụng.

Tính toán chữ ký

Bước 1: Tạo chuỗi cơ sở (base string):

Các loại API khác nhau có các thành phần khác nhau trong chuỗi cơ sở. Ghép nối đường dẫn API (không bao gồm host) và các tham số chung sau đây thành một chuỗi duy nhất. Bạn phải tuân thủ nghiêm ngặt thứ tự (chuỗi cơ sở) như hiển thị bên dưới:

*Ví dụ đường dẫn API: /api/v2/auth/token/get

Shop API: partner_id, api path, timestamp, access_token, shop_id

*Ví dụ：

partner_id: 2001887

API path: /api/v2/shop/get_shop_info

timestamp: 1655714431

access_token: 59777174636562737266615546704c6d

shop id: 14701711

Base string=2001887/api/v2/shop/get_shop_info165571443159777174636562737266615546704c6d14701711

Merchant API: partner_id, api path, timestamp, access_token, merchant_id

*Ví dụ:

partner_id: 2001887

API path: /api/v2/global_product/get_category

timestamp: 1655714431

access_token: 09777174636962737266615546704c6d

merchant_id: 1000000

Base string=2001887/api/v2/global_product/get_category165571443109777174636962737266615546704c6d1000000

Public API: partner_id, api path, timestamp

*Ví dụ:

partner_id:2001887

API path: /api/v2/public/get_shops_by_partner

timestamp:1655714431

Base string=2001887/api/v2/public/get_shops_by_partner1655714431

Bước 2: Tính chữ ký bằng thuật toán HMAC-SHA256

Tính chữ ký bằng cách sử dụng thuật toán băm HMAC-SHA256 trên chuỗi cơ sở và partner Key (lấy từ trang chi tiết ứng dụng trong Shopee Open Platform Console). Đầu ra của hàm băm là một chuỗi được mã hóa hex.

*Ví dụ：

sign=56f31d01aeda9d08bf456b37f6f6640ef8614b4d6ad49baafe30b39a061f0e26

Tìm hiểu lý do bạn có thể gặp lỗi "Wrong sign" và cách giải quyết.

Mã nguồn mẫu:

Python

#!/usr/bin/envpython

# encoding:utf-8

import hmac 

import time

import requests

import hashlib

timest=int(time.time())

host="https://partner.shopeemobile.com 

access_token = "random string"

partner id =80001

partner key = "test....."

#### call shop level api 

shop id =209920

base string ="%s%s%s%s%s"%(partner id, path timest access token, shop id) 

sign = hmac.new( partner key,base string,hashlib.sha256)hexdigest() 

path ="/api/v2/example/shop level/get"

url = host + path + "?partner_id=%s&shop_id=%s&timestamp=%s&access_token=%s&sign=%s"%(partner_id, shop_id, timest, access_token, sign) 

headers={"Content-Type":"application/ison"? 

resp=requests.post(urlheaders=headers)

#### call merchant level api 

merchant id =1234567

base string ="%s%s%s%s%s"%(partner id, path timest, access token, merchant id) 

sign =hmac.new( partner key,base string,hashlib.sha256).hexdigest() 

path ="/api/v2/example/merchant_level/get"

url = host+ path +"?partner id=%s&merchant id=%s&timestamp=%s&access token=%s&sign=%s"%(partnerid, merchant id, timest, access token, sign) 

headers ={"Content-Type":"application/ison"? resp =requests.eet(urlheaders=headers)

#### call public api

base string ="%s%s%5%s"%(partner idpathtimestaccess token)

sign= hmac.new( partner keybase stringhashlib.sha256)hexdigest() 

path ="/api/v2/auth merchant/access token/get"

url = host+path+"?partner id=%s&timestamp=%s&sign=%s%(partner idtimest, sign)

body ={"partner id":partner id, "merchant id": merchant id,"refresh token":"testingtoken") 

headers =["Content-Type":"application/ison"?

resp =requests.post(url,json=bodyheaders=headers)

Mẫu yêu cầu API

Đối với yêu cầu API kiểu GET, bạn cần đặt cả tham số chung và tham số yêu cầu vào URL.

Ví dụ: V2.product.get_category

URL yêu cầu API:

https://partner.shopeemobile.com/api/v2/product/get\_category?partner\_id=851249&timestamp=1654673582&shop\_id=1001094&access\_token=367a0a8eb9d1837cbf7c43b587a0faa4&sign=a40fc50a08c382eeee08e2eb00deb8464c6fdcbe4f1c271e033cdbca3ded4d5b&language=zh-hans

*Đối với API endpoint này, partner_id、timestamp、access_token、shop_id và sign là các tham số chung. Trong khi đó, language là tham số yêu cầu.

Đối với yêu cầu API kiểu POST, bạn cần đặt tham số chung vào URL yêu cầu và tham số yêu cầu vào body yêu cầu.

Ví dụ: v2.shop.update_profile

URL yêu cầu API:

https://partner.shopeemobile.com/api/v2/shop/update\_profile?partner\_id=851249&timestamp=1654673582&shop\_id=1001094&access\_token=367a0a8eb9d1837cbf7c43b587a0faa4&sign=80cbce8da907d5a1237711409920fc16908a9f9e01b1254ff9cc44aaf0836122

Body yêu cầu:

{

"shop_logo": "https://cf.shopee.sg/file/8424390be4677b0b3c37ce6499ce261a",

"description": "TTest",

"shop_name": "123"

}

*Đối với API endpoint này, partner_id、timestamp、access_token、shop_id、và sign là các tham số chung. Trong khi đó, shop_logo、description và shop_name là các tham số yêu cầu.

Tham số phản hồi API

Tham sốLuôn trả về?Mô tả
request idCóMỗi yêu cầu API có một request ID duy nhất. Khi gặp sự cố API, vui lòng cung cấp ID này cùng thông tin API tương ứng để nhận phản hồi nhanh hơn.
errorCóMã lỗi. Khi yêu cầu thành công, tham số error sẽ trả về rỗng. Nếu yêu cầu thất bại, mã lỗi tương ứng sẽ được phản ánh trong trường này.
messageKhôngThông báo lỗi. Khi yêu cầu thành công, message sẽ trả về rỗng. Nếu yêu cầu thất bại, trường này sẽ chứa thông tin chi tiết về lỗi.
warningKhôngNếu lần gọi API thành công nhưng một số dữ liệu không được trả về hoặc một số yêu cầu theo lô thất bại, thông tin sẽ được phản ánh trong trường này.
responseKhôngKhi yêu cầu thành công, dữ liệu tương ứng sẽ được phản ánh trong trường này.

Chức năng API

Module APIMô tả chức năng
ProductBạn có thể lấy các thông tin sau: - Cây danh mục liên quan đến sản phẩm - Thông tin thuộc tính và thương hiệu - Dữ liệu sản phẩm cửa hàng - Thông tin khuyến mãi sản phẩm - Đẩy sản phẩm và danh sách sản phẩm được đẩy - Đánh giá sản phẩm và danh sách đánh giá - Danh mục và thuộc tính được đề xuất cho sản phẩm - Thương hiệu sản phẩm đã đăng ký Thực hiện các hành động sau: - Tạo, xóa và cập nhật thông tin sản phẩm.
ShopBạn có thể lấy các thông tin sau: - Tên cửa hàng - Thị trường cửa hàng đang hoạt động - Loại cửa hàng Thực hiện các hành động sau: - Cập nhật thông tin cửa hàng
Merchant*Module này chỉ dành cho người bán xuyên biên giới. Lấy thông tin merchant (tên/thị trường/tiền tệ) và danh sách tất cả các cửa hàng thuộc merchant đã cấp ủy quyền.
GlobalProduct*Module này chỉ dành cho người bán xuyên biên giới. Lấy các thông tin sau: - Cây danh mục liên quan - Thông tin thuộc tính và thương hiệu - Dữ liệu sản phẩm toàn cầu - Danh sách sản phẩm chỉ có thể đăng bán tại một số thị trường - Danh sách sản phẩm đã có sản phẩm toàn cầu được xuất bản - Danh sách sản phẩm đã được đăng bán tại các thị trường cụ thể - Global product ID tương ứng với sản phẩm tại thị trường cụ thể - Danh mục và thuộc tính được đề xuất của sản phẩm toàn cầu Thực hiện các hành động sau: - Tạo, xóa và cập nhật sản phẩm toàn cầu. - Bật/Tắt đồng bộ thông tin sản phẩm toàn cầu. - Xuất bản sản phẩm toàn cầu
MediaSpaceTải lên video và hình ảnh
OrderLấy các thông tin sau: - Danh sách đơn hàng cửa hàng - Danh sách và chi tiết đơn hàng - Danh sách đơn hàng hóa đơn cần tải lên - Thông tin hóa đơn Thực hiện các hành động sau: - Quản lý đơn hàng bằng cách tách và hủy - Hoàn tác tách đơn hàng - Xử lý yêu cầu hủy đơn hàng của người bán - Thêm ghi chú đơn hàng - Tải lên và tải xuống hóa đơn để lấy thông tin hóa đơn
LogisticsLấy các thông tin sau: - Danh sách kênh vận chuyển cửa hàng - Thông số vận chuyển - Số theo dõi đơn hàng và thông tin theo dõi - Định dạng tài liệu vận chuyển và tài liệu vận chuyển - Danh sách địa chỉ cửa hàng Thực hiện các hành động sau: - Giao hàng đơn lẻ/hàng loạt - Cập nhật cờ địa chỉ cửa hàng - Bật/Tắt kênh cửa hàng - Xóa địa chỉ cửa hàng
FirstMile*Module này chỉ dành cho người bán xuyên biên giới. Lấy các thông tin sau: - Đơn hàng First Mile chưa liên kết - Số theo dõi và chi tiết First Mile - Chi tiết đơn hàng First Mile - Tài liệu vận chuyển First Mile - Chi tiết kênh FirstMile
ReturnsLấy các thông tin sau: - Danh sách yêu cầu trả hàng và hoàn tiền - Chi tiết yêu cầu trả hàng và hoàn tiền - Nhận phương án trả hàng và hoàn tiền Thực hiện các hành động sau: - Xác nhận hoàn tiền - Gửi tranh chấp - Thương lượng hoàn tiền - Tải lên bằng chứng hình ảnh cho tranh chấp
PaymentLấy các thông tin sau: - Thu nhập đơn hàng - Dữ liệu thanh toán - Dữ liệu ví - Danh sách đơn hàng đã hoàn thành - Cài đặt trả góp cửa hàng - Danh sách sản phẩm đã thiết lập thanh toán trả góp
DiscountTạo, xem, cập nhật và xóa Khuyến mãi Giảm giá
Bundle DealTạo, xem, cập nhật và xóa Combo sản phẩm
Add-On DealTạo, xem, cập nhật và xóa Ưu đãi thêm sản phẩm
VoucherTạo, xem, cập nhật và xóa Voucher
Follow PrizeTạo, xem, cập nhật và xóa Phần thưởng theo dõi
TopPicksTạo, xem, cập nhật và xóa Lựa chọn hàng đầu
ShopCategoryTạo, xem, cập nhật và xóa Danh mục cửa hàng
AccountHealthLấy dữ liệu hiệu suất cửa hàng và các điểm vi phạm
PublicThực hiện các hành động sau: - Lấy danh sách cửa hàng đã cấp ủy quyền - Lấy danh sách merchant đã cấp ủy quyền - Gửi lại mã và nâng cấp mã để lấy token - Lấy và làm mới token
PushLấy và cập nhật cài đặt Push Mechanism
Chat*Module này chỉ mở cho người dùng trong danh sách trắng. Để đăng ký tham gia danh sách trắng, bạn có thể tham khảo Câu hỏi thường gặp này. Lấy các thông tin sau: - Danh sách chat - Chi tiết chat - Thông tin chat - Lấy cài đặt Make Offer Thực hiện các hành động sau: - Xóa chat - Đánh dấu chat chưa đọc - Ghim và bỏ ghim chat - Tải lên hình ảnh vào chat - Gửi tin nhắn chat thủ công và tự động - Bật/Tắt cài đặt Make Offer

Sự cố với API

Nếu bạn gặp sự cố trong quá trình tích hợp API, bạn có thể tham khảo trang Câu hỏi thường gặp để được trợ giúp. Nếu vấn đề vẫn tiếp tục, bạn có thể gửi ticket.