Tích hợp Shopee Open Platform API: Xác thực, ký và token

Shopee Open Platform API hoạt động như thế nào (v2)

Tích hợp Shopee Open Platform API là một tích hợp REST có ký xác thực. Máy chủ của bạn đăng ký một ứng dụng, mỗi người bán cấp quyền cho ứng dụng đó thông qua một URL chuyển hướng theo kiểu OAuth, sau đó mọi request đều chứa partner ID, timestamp và chữ ký HMAC-SHA256, cùng access token có thời hạn ngắn cho các API cấp shop. Đồng bộ sản phẩm, nhập đơn hàng và cập nhật tồn kho đều dựa trên những thành phần này.

Shopee đã lên lịch ngừng hoàn toàn API v1 sau ngày 26 tháng 12 năm 2022, vì vậy mọi tích hợp mới đều nên hướng đến v2. Người mới thường mất nhiều thời gian vì hệ thống thuật ngữ, nên dưới đây là bản đồ tổng quan:

Đăng ký ứng dụng: danh mục quyết định mọi thứ

Shopee chấp nhận hai loại nhà phát triển: Third-Party Partners (công ty xây dựng phần mềm cho nhiều người bán) và Registered Business Sellers (người bán tích hợp shop của chính mình). Sau khi hồ sơ được duyệt, bạn tạo ứng dụng trong console. Đây là bước khiến nhiều đội ngũ mất hàng tuần: danh mục được chọn khi tạo ứng dụng sẽ quyết định mọi API và quyền mà ứng dụng có thể sử dụng.

Thông báo FAQ dành cho nhà phát triển của Shopee nói rất rõ điều này. Đội ngũ Open Platform không bật từng API riêng lẻ, không thể bổ sung quyền cho ứng dụng đã tồn tại, và nếu cần các khả năng khác nhau, bạn có thể phải tạo ứng dụng mới dưới một danh mục khác.

• Chọn danh mục dựa trên danh sách endpoint, không dựa trên tên gọi. Hãy liệt kê các endpoint sản phẩm, đơn hàng, logistics và thanh toán cần dùng, rồi xác nhận tất cả đều thuộc cùng một danh mục trước khi tạo ứng dụng.
• Đừng mặc định hứa hẹn tính năng nhắn tin với người mua. Việc đăng ký ứng dụng Customer Service (Chat API) từ bên thứ ba độc lập và các nền tảng Third-party Partner đã đóng từ 18 tháng 11 năm 2024. Hãy xác nhận quyền truy cập trước khi đưa tính năng hộp thư hoặc chatbot vào phạm vi công việc cho khách hàng.
• Lỗi permission denied thường có nghĩa là sai danh mục, endpoint đã ngừng hỗ trợ hoặc có thay đổi được công bố, chứ không phải lỗi chữ ký.

Quy trình cấp quyền từng bước

Mọi loại ứng dụng, bất kể danh mục nào, đều bắt đầu bằng một URL cấp quyền được tạo từ URL cấp quyền cố định của Shopee cùng các tham số bắt buộc. Toàn bộ đặc tả nằm trong hướng dẫn Authorization and Authentication của Shopee; trên thực tế, quy trình diễn ra như sau:

1. Tạo liên kết có chữ ký. Gọi /api/v2/shop/auth_partner với partner_id, timestamp, sign và URL redirect của bạn.
2. Người bán phê duyệt. Người bán đăng nhập trên trang của Shopee và cấp quyền truy cập. Họ chọn thời hạn cấp quyền: 7, 30, 90, 180 hoặc 365 ngày, hoặc một ngày tùy chỉnh trong vòng 365 ngày.
3. Shopee chuyển hướng trở lại URL redirect của bạn với code và shop_id trong query string.
4. Đổi mã tại /api/v2/auth/token/get để lấy access_token và refresh_token.
5. Gọi các API cấp shop và làm mới token tại /api/v2/auth/access_token/get trước khi access token hết hạn.

Có hai dòng thường xuyên bị hiểu nhầm. Việc làm mới token không bao giờ đưa người bán quay lại Shopee, vì thao tác này chỉ sử dụng refresh token. Ngoài ra, thời hạn cấp quyền của người bán là một đồng hồ riêng, không phụ thuộc vào token: người bán chọn 7 ngày sẽ bị ngắt kết nối sau một tuần, ngay cả khi tác vụ làm mới token của bạn hoạt động hoàn hảo. Hãy lưu thời hạn đó và nhắc người bán kết nối lại trước khi hết hạn.

Cách ký request Shopee API (HMAC-SHA256)

Chữ ký là mã băm dạng hex của HMAC-SHA256 trên một chuỗi cơ sở, được tạo bằng partner key của bạn. Thành phần trong chuỗi cơ sở phụ thuộc vào loại API:

Kết quả được gửi dưới dạng query parameter sign cùng với partner_id và timestamp; các request cấp shop cũng chứa access_token và shop_id. api_path chỉ là phần đường dẫn, chẳng hạn /api/v2/shop/get_shop_info, không bao gồm host và query string. Module Python dưới đây bao quát toàn bộ quy trình kết nối lần đầu:

import hashlib
import hmac
import time
from urllib.parse import urlencode

import requests

HOST = 'https://partner.test-stable.shopeemobile.com'  # sandbox; production is https://partner.shopeemobile.com
PARTNER_ID = 1000000          # from the console, must match the environment
PARTNER_KEY = 'your-partner-key'


def sign(path, ts, access_token='', entity_id=''):
    # public API: partner_id + path + timestamp
    # shop API: ... + access_token + shop_id (merchant API: merchant_id)
    base = f'{PARTNER_ID}{path}{ts}{access_token}{entity_id}'
    return hmac.new(PARTNER_KEY.encode(), base.encode(), hashlib.sha256).hexdigest()


def auth_url(redirect):
    path = '/api/v2/shop/auth_partner'
    ts = int(time.time())
    query = urlencode({'partner_id': PARTNER_ID, 'timestamp': ts,
                       'sign': sign(path, ts), 'redirect': redirect})
    return f'{HOST}{path}?{query}'


def public_post(path, body):
    ts = int(time.time())
    params = {'partner_id': PARTNER_ID, 'timestamp': ts, 'sign': sign(path, ts)}
    body = dict(body, partner_id=PARTNER_ID)
    return requests.post(HOST + path, params=params, json=body, timeout=15).json()


def get_token(code, shop_id):
    return public_post('/api/v2/auth/token/get', {'code': code, 'shop_id': shop_id})


def refresh_token(refresh_tok, shop_id):
    return public_post('/api/v2/auth/access_token/get',
                       {'refresh_token': refresh_tok, 'shop_id': shop_id})


def shop_get(path, access_token, shop_id, **extra):
    ts = int(time.time())
    params = {'partner_id': PARTNER_ID, 'timestamp': ts, 'access_token': access_token,
              'shop_id': shop_id, 'sign': sign(path, ts, access_token, shop_id)}
    params.update(extra)
    return requests.get(HOST + path, params=params, timeout=15).json()


# info = shop_get('/api/v2/shop/get_shop_info', access_token, shop_id)

Trước tiên hãy chạy mã trên host sandbox, chỉ thay sang host production, partner ID và key production sau khi mọi thứ hoạt động. Ba nguyên nhân sau chiếm phần lớn lỗi chữ ký:

• Không khớp môi trường. Key, partner_id và host phải cùng thuộc một môi trường (sandbox hoặc production). Dùng key production với host sandbox sẽ luôn thất bại.
• Timestamp khác nhau. Timestamp trong chuỗi cơ sở phải giống chính xác giá trị được gửi trong URL. Hãy tính một lần cho mỗi request.
• Đồng hồ máy chủ bị lệch. Shopee chỉ chấp nhận timestamp có chữ ký trong vài phút, nên máy chủ bị sai giờ có thể khiến lỗi chữ ký xảy ra lúc được lúc không. Hãy duy trì NTP.

Lưu trữ và làm mới token mà không làm gián đoạn đồng bộ

Lưu một bản ghi token cho từng shop_id và từng merchant_id, không lưu theo từng ứng dụng. Bản ghi cần có access token, refresh token, thời hạn của cả hai token và thời hạn cấp quyền của người bán. Hãy chủ động làm mới trước thời điểm 4 giờ khá lâu, thay vì chờ request thất bại giữa quá trình đồng bộ.

Vấn đề khó nhận ra là tình trạng đồng thời. Nếu hai worker cùng làm mới một shop, worker hoàn thành sau có thể ghi đè cặp token hợp lệ bằng dữ liệu cũ. Hãy xem refresh token là token luân phiên: tạo khóa theo từng shop, gọi thao tác làm mới và ghi lại cả hai token được trả về trong cùng một transaction, ghi đè dữ liệu cũ. Tất cả worker khác chỉ đọc từ cơ sở dữ liệu và không tự làm mới token.

Lớp quản lý token này không hào nhoáng nhưng là phần mọi connector marketplace đều cần, và quy mô sẽ tăng theo từng kênh bạn bổ sung. Các đội ngũ đồng bộ Shopee cùng Amazon, eBay hoặc TikTok Shop thường nhận thấy thuê xây dựng và duy trì tích hợp marketplace sẽ tiết kiệm hơn so với tự quản lý một mô hình xác thực riêng cho từng nền tảng.

Sandbox và production: test-stable cho bạn biết và không cho bạn biết điều gì

Host sandbox là partner.test-stable.shopeemobile.com; production là partner.shopeemobile.com. Shopee mô tả sandbox là môi trường có đầy đủ chức năng nhưng không phải bản sao hoàn chỉnh của production, vì vậy bạn có thể gặp hành vi, giới hạn và tình trạng không ổn định khác nhau.

• Dùng sandbox để kiểm tra chữ ký, quy trình cấp quyền, làm mới token và cấu trúc payload.
• Không dùng sandbox để đánh giá thông lượng, các trạng thái đơn hàng đặc biệt hoặc hành vi logistics.
• Việc tạo đơn thử nghiệm có thể thất bại với các lỗi như error_sandbox_order_checkout_cart_item, invalid product hoặc Failed to get info. Shopee khuyên tạo sản phẩm mới, thử danh mục khác và lặp lại quy trình trước khi cho rằng mã của bạn bị lỗi.
• Nếu gửi yêu cầu hỗ trợ, hãy chạy các bài kiểm tra cô lập trước và đính kèm video quay toàn màn hình, tệp HAR cùng request và response đầy đủ.

Tại sao dữ liệu người mua bị che (IP whitelist)

Nếu response đơn hàng trả về thông tin người mua đã bị che, vấn đề nằm ở phần cài đặt ứng dụng chứ không phải yêu cầu hỗ trợ. Quyền truy cập dữ liệu nhạy cảm phụ thuộc vào cấu hình bảo mật của ứng dụng, bao gồm IP whitelist, và Shopee cho biết không có cách mở khóa thủ công dữ liệu đã bị che. Bạn phải tự cấu hình whitelist trong console; nhân viên Shopee không thể làm thay.

Hãy kiểm tra lần lượt hai điều. Trước tiên, whitelist đã được thiết lập và bật cho đúng các IP outbound mà máy chủ sử dụng hay chưa. Điều này đặc biệt quan trọng nếu bạn triển khai sau NAT gateway hoặc trên hạ tầng autoscaling có địa chỉ thay đổi. Tiếp theo, kiểm tra trạng thái đơn hàng: một số trạng thái không cung cấp dữ liệu người mua qua API, vì vậy các trường bị che trên một đơn hàng mới tạo và chưa thanh toán chưa chắc là vấn đề do whitelist.

Partner Key hết hạn và cách đổi khóa an toàn

Partner Key có hiệu lực 180 ngày kể từ khi tạo và không tự gia hạn. Khi hết hạn, nền tảng đánh dấu khóa là không hợp lệ và chặn các API request sử dụng khóa đó. Với một tích hợp đang chạy, điều này có thể khiến tất cả người bán mất kết nối cùng lúc. Hãy đặt lịch nhắc trước ngày thứ 180 và xem việc đổi khóa như một lần phát hành có kế hoạch.

• Khóa mới có hiệu lực ngay sau khi đặt lại.
• Bạn có thể giữ khóa cũ hoạt động tối đa 72 giờ sau khi đặt lại, tạo khoảng thời gian để triển khai secret mới trên các máy chủ.
• Đặt lại khóa không làm mất hiệu lực quyền cấp của người bán, vì vậy không người bán nào phải kết nối lại.
• Khóa được quản lý bên trong ứng dụng, tại App List trong console. Shopee không thể tạo khóa thay thế cho bạn.

Hãy đọc key từ secret store lúc runtime thay vì nhúng vào image, để việc đổi khóa chỉ là thay đổi cấu hình chứ không cần redeploy.

Push Mechanism và polling cho đơn hàng, tồn kho

Shopee có tài liệu về Push Mechanism, một webhook thông báo đến callback URL đã đăng ký cho ứng dụng khi xảy ra các sự kiện như thay đổi trạng thái đơn hàng. Đây là công cụ phù hợp cho yêu cầu độ trễ thấp, nhưng không nên là công cụ duy nhất.

Hãy thiết kế theo mô hình push kết hợp đối soát. Xác minh chữ ký push theo tài liệu Push Mechanism, phản hồi xác nhận nhanh và đưa sự kiện vào queue thay vì xử lý trực tiếp. Sau đó chạy tác vụ định kỳ truy vấn đơn hàng theo khoảng thời gian cập nhật và so sánh với cơ sở dữ liệu. Push có thể đến muộn, đến hai lần hoặc không đến, còn bước đối soát là yếu tố biến một luồng dữ liệu chỉ mang tính cố gắng tốt nhất thành hệ thống đáng tin cậy. Hãy bảo đảm mọi handler có tính idempotent dựa trên mã đơn hàng để push lặp lại không gây hại.

Các lỗi Shopee API thường gặp và điều cần kiểm tra trước tiên

Tự xây dựng hay bàn giao cho đơn vị khác

Phần Shopee có thể quản lý được với một shop và một lập trình viên: ký request chính xác, lưu token theo từng shop, làm mới token dưới cơ chế khóa, đối soát push và đổi key đúng lịch. Chi phí thực sự xuất hiện ở khâu bảo trì, khi giới hạn danh mục ngăn cản một tính năng, key hết hạn vào cuối tuần hoặc bạn bổ sung marketplace thứ hai với các quy tắc riêng.

Nếu muốn xác định phạm vi công việc thay vì tự gánh toàn bộ, hãy yêu cầu báo giá miễn phí với danh sách marketplace và tính năng cần triển khai. Chi phí được tính theo phạm vi, và bạn sẽ nhận được phản hồi mà không phải cam kết.