Tích hợp API người bán SHEIN: Xác thực, ký và đồng bộ

API người bán SHEIN bao gồm những gì?

SHEIN cung cấp hệ thống tích hợp dưới tên SHEIN Developer Platform (còn gọi là SHEIN Open Platform). SHEIN mô tả đây là các giải pháp kết nối công nghệ cho quy trình sản phẩm, đơn hàng, đổi trả và thu mua. Trên thực tế, tích hợp API người bán SHEIN có nghĩa là hệ thống của bạn (ERP, công cụ bán hàng đa kênh, WMS hoặc hệ thống quản trị tùy chỉnh) giao tiếp với SHEIN qua HTTPS thay vì nhân viên phải thao tác thủ công trong cổng người bán.

Phạm vi thực tế của lần tích hợp đầu tiên nên tương đối nhỏ. Hầu hết đội ngũ cần ba luồng sau, theo thứ tự này:

API đổi trả và thu mua cũng có sẵn, nhưng hãy để sau khi đơn hàng và tồn kho đã hoạt động đáng tin cậy. Một lưu ý trước khi lập kế hoạch: tài liệu của developer platform là một ứng dụng một trang và có thể thay đổi. Vì vậy, hãy xem mọi đường dẫn endpoint và tên trường trong bài viết này là điểm bắt đầu, đồng thời kiểm tra lại tài liệu SHEIN hiện hành trước khi lập trình.

Cơ chế xác thực API SHEIN

SHEIN không cung cấp cho bạn một API key tĩnh duy nhất. Có hai lớp thông tin xác thực, và nhầm lẫn giữa chúng là lý do phổ biến nhất khiến request đầu tiên thất bại.

Quy trình mà các hệ thống tích hợp triển khai như sau:

1. Người bán mở trang ủy quyền của SHEIN với appid của bạn, redirectUrl được mã hóa Base64 và một giá trị state do bạn tự chọn.
2. Sau khi người bán chấp thuận, SHEIN chuyển hướng về URL của bạn cùng tempToken và state được gửi lại. Token có hiệu lực trong 10 phút.
3. Server của bạn gửi POST {"tempToken": "..."} đến /open-api/auth/get-by-token trên API domain.
4. Response chứa openKeyId, supplierId, supplierSource, appid và secretKey đã được mã hóa.
5. Bạn giải mã secretKey bằng app secret key rồi lưu cặp thông tin này gắn với người bán đó.

Java SDK chính thức của SHEIN cũng phản ánh sự phân tách này: SDK cung cấp chế độ ký APPID (dùng để đổi token qua getToken(tempToken, authInfo)) và chế độ ký OPEN_KEY_ID (dùng cho các API thông thường). SDK cũng liệt kê hai API domain là openapi.sheincorp.com và openapi.sheincorp.cn. Chi tiết về quy trình trao đổi có trên trang chính thức của SHEIN, Trao đổi openKeyId và secretKey, còn SDK được phát hành tại sheinsight/open-sdk-java trên GitHub.

Hệ quả khi thiết kế: tham số state là cách duy nhất để biết khách hàng nào của bạn vừa thực hiện ủy quyền. Hãy tạo giá trị này ở server, liên kết với hồ sơ khách hàng và từ chối mọi callback có state không phải do bạn phát hành. Bỏ qua bước này có thể khiến thông tin xác thực của một người bán bị gắn nhầm vào tài khoản của người bán khác trong các công cụ đa bên thuê.

Cách ký một request API SHEIN

Mỗi request đều chứa chữ ký được tạo từ thông tin xác thực của người bán, đường dẫn request và timestamp tính bằng mili giây. Cơ chế mà các hệ thống tích hợp sử dụng là:

• Chuỗi cần ký: openKeyId&timestamp&path (ví dụ đường dẫn /open-api/auth/get-by-token, không bao gồm domain).
• Khóa HMAC: secretKey nối với một chuỗi ngẫu nhiên gồm 5 ký tự.
• Digest: HMAC-SHA256, mã hóa dạng hex rồi mã hóa Base64.
• Kết quả: chuỗi ngẫu nhiên 5 ký tự được đặt trước giá trị Base64 và gửi trong header x-lt-signature.

Cùng với chữ ký, bạn gửi timestamp mili giây trong x-lt-timestamp, application id trong x-lt-appid, content type dạng JSON và header language. Đây là phiên bản Python có thể chạy được:

import base64, hashlib, hmac, secrets, string, time

def shein_signature(open_key_id: str, secret_key: str, path: str, timestamp_ms: int) -> str:
    alphabet = string.ascii_letters + string.digits
    random_key = ''.join(secrets.choice(alphabet) for _ in range(5))
    to_sign = f'{open_key_id}&{timestamp_ms}&{path}'
    hex_digest = hmac.new(
        (secret_key + random_key).encode(),
        to_sign.encode(),
        hashlib.sha256,
    ).hexdigest()
    return random_key + base64.b64encode(hex_digest.encode()).decode()

ts = int(time.time() * 1000)
sig = shein_signature('YOUR_OPEN_KEY_ID', 'YOUR_SECRET_KEY', '/open-api/auth/get-by-token', ts)

Có hai chi tiết thường gây lỗi. Thứ nhất, Base64 được áp dụng cho chuỗi hex, không phải các byte digest thô. Vì vậy, với ngôn ngữ trả về byte thô theo mặc định (Go, hoặc digest() của Node không có encoding), bạn cần thêm bước chuyển sang hex rõ ràng. Thứ hai, đường dẫn trong chuỗi cần ký phải khớp với đường dẫn thực tế được gọi, không bao gồm query string. Vì vậy, ký request ở một nơi nhưng định tuyến ở nơi khác là nguyên nhân kinh điển gây lỗi không khớp chữ ký.

Hãy kiểm tra tên header chính xác và quy tắc đường dẫn dành cho các request nghiệp vụ (khác với trao đổi token) trong tài liệu SHEIN hiện hành. Nếu viết bằng Java, chức năng ký tích hợp sẵn trong SDK chính thức sẽ loại bỏ cả nhóm lỗi này.

Cách giải mã secretKey của SHEIN

secretKey trả về từ quá trình trao đổi token không thể sử dụng ngay. Khóa này được mã hóa bằng AES-128-CBC và mã hóa Base64, sau đó được giải mã bằng secret key của ứng dụng cùng IV cố định được các bên tích hợp ghi nhận là space-station-de. Dưới đây là phiên bản Python sử dụng PyCryptodome:

import base64
from Crypto.Cipher import AES
from Crypto.Util.Padding import unpad

def decrypt_secret_key(encrypted_b64: str, app_secret: str) -> str:
    key = app_secret.encode()[:16].ljust(16, b'\0')
    cipher = AES.new(key, AES.MODE_CBC, iv=b'space-station-de')
    return unpad(cipher.decrypt(base64.b64decode(encrypted_b64)), 16).decode()

Dòng key mô phỏng cách OpenSSL xử lý AES-128: khóa được cắt hoặc đệm thêm số 0 để đủ 16 byte. Nếu thư viện bạn dùng yêu cầu độ dài khóa chính xác, đây là vị trí thường phát sinh lỗi. Sau khi giải mã, hãy lưu giá trị trong secrets manager hoặc một cột đã mã hóa. Tuyệt đối không ghi giá trị này vào log và không gửi đến trình duyệt.

Thiết kế đồng bộ đơn hàng và tồn kho ổn định khi vận hành

Khiến một request đã ký trả về 200 là phần dễ. Điều quyết định khả năng tích hợp hoạt động bền vững là cách bạn luân chuyển dữ liệu trong nhiều tuần.

Dùng webhook để nhanh và polling để đối soát dữ liệu chuẩn

SHEIN có tài liệu về cơ chế webhook trên developer platform (xem trang Webhook Instruction). Thông báo đẩy giúp giảm độ trễ, nhưng bất kỳ kênh push nào cũng có thể làm mất hoặc trì hoãn sự kiện. Mô hình đáng tin cậy là webhook kích hoạt việc lấy ngay thông tin đơn hàng, kết hợp với một tác vụ polling đối soát theo lịch để truy vấn mọi dữ liệu thay đổi kể từ lần đồng bộ thành công gần nhất. Nếu polling không bao giờ tìm thấy sự kiện mà webhook bỏ sót, bạn có bằng chứng thiết kế đang hoạt động; nếu có, bạn đã phát hiện lỗ hổng trước khi khách hàng nhận ra.

Đảm bảo mọi thao tác ghi đều idempotent

Retry chắc chắn sẽ xảy ra do timeout, triển khai phiên bản mới hoặc webhook được gửi trùng. Trong cơ sở dữ liệu, hãy định danh mỗi đơn bằng mã đơn hàng của SHEIN và đặt ràng buộc duy nhất; đồng thời để thao tác xử lý đơn và cập nhật tồn kho là thao tác gán giá trị thay vì tăng giảm tương đối. Retry thao tác “giảm 1” có thể gây bán vượt tồn, còn retry thao tác “đặt thành 14” thì không gây hại.

Coi cặp token là trạng thái riêng của từng người bán

Lưu openKeyId, secretKey đã giải mã và supplierId theo từng người bán, đồng thời ghi nhận ngày ủy quyền. Nếu người bán thu hồi quyền truy cập, request tiếp theo sẽ thất bại. Hãy hiển thị trạng thái “kết nối lại SHEIN” trong sản phẩm thay vì để quá trình đồng bộ âm thầm bị dừng.

Kiểm soát đồng hồ hệ thống

Chữ ký có timestamp tính bằng mili giây, vì vậy server bị lệch giờ sẽ tạo ra các request trông có vẻ hợp lệ nhưng bị từ chối. Hãy chạy NTP trên mọi máy chủ thực hiện ký request.

Tự xây dựng, dùng SDK hay thuê đội ngũ tích hợp SHEIN?

Phần ký và xác thực có thể hoàn thành trong một cuối tuần. Phần công việc kéo dài về sau (ánh xạ trường giữa danh mục của bạn và thuộc tính ngành hàng của SHEIN, xử lý lỗi, giám sát và hướng dẫn người bán kết nối) mới là thứ tiêu tốn nhiều tuần. Hãy lựa chọn dựa trên số lượng người bán bạn phục vụ và việc SHEIN có phải kênh duy nhất hay không.

Nếu bạn cần kết nối SHEIN cùng Amazon, eBay, Walmart hoặc Etsy trong một hệ thống, đây là trường hợp nên xây dựng mô hình dữ liệu nội bộ dùng chung thay vì viết script riêng cho từng kênh. Netalith triển khai các hệ thống như vậy trong dịch vụ tích hợp marketplace, và các nguyên tắc thiết kế trên vẫn áp dụng bất kể ai là người viết mã.

Checklist trước khi đưa tích hợp API người bán SHEIN vào vận hành

Đối với câu hỏi về quyền truy cập developer platform, SHEIN cung cấp email liên hệ [email protected]. Nếu muốn được tư vấn phạm vi và xây dựng tích hợp, hãy gửi thông tin qua biểu mẫu nhận báo giá miễn phí của Netalith.