Tích hợp API người bán Temu: Xác thực, đơn hàng, webhook

API người bán Temu thực sự là gì?

Tích hợp API người bán Temu nghĩa là xây dựng một ứng dụng trên Temu Open Platform, để người bán ủy quyền cho ứng dụng, sau đó gọi các endpoint của Temu thay mặt người bán đó. Tài liệu Partner Platform của Temu mô tả đây là nơi phát triển dành cho đối tác và quản lý ứng dụng, với ERP và hệ thống quản lý kho là hai nhóm ứng dụng chính: phần mềm giúp người bán quản lý sản phẩm, đơn hàng và tồn kho trên Temu cùng các kênh khác.

Ba điểm sau sẽ định hình mọi quyết định thiết kế tiếp theo:

• Mọi request đều là POST. Temu đã loại bỏ các phương thức request khác, vì vậy mỗi lần gọi đều là một POST có chữ ký đến cùng một router URL; endpoint cần gọi được chỉ định bằng giá trị type trong body, chẳng hạn bg.order.list.v2.get.
• Quyền truy cập gắn với từng người bán. Nếu chưa được người bán cho phép, ứng dụng hoàn toàn không thể gọi các API quản lý cửa hàng.
• API được phiên bản hóa bằng tên method. Banner tài liệu thông báo Add Products API V3.0, các API truy vấn đơn hàng và giao hàng đã chuyển sang V2, còn danh mục tham chiếu bao gồm cả method bg.* và temu.*. Bạn cần cố định tên method đang dùng và kiểm tra lại khi Temu công bố thay đổi.

Tài liệu tham chiếu nhóm các method thành sản phẩm, đơn hàng, vận chuyển, hậu mãi, khuyến mãi, tuân thủ, quảng cáo và kho hợp tác. Hướng dẫn này bao quát toàn bộ quy trình mà mọi tích hợp cần thực hiện: truy cập, ủy quyền, chọn host, ký request, giới hạn tốc độ, đơn hàng, sản phẩm và webhook.

Ai có thể được cấp quyền: ứng dụng tự phát triển hay ứng dụng đối tác?

Có hai hướng lựa chọn, và phương án phù hợp phụ thuộc vào những cửa hàng bạn muốn kết nối.

Điểm khác biệt thực tế nằm ở nơi lưu giữ thông tin xác thực. Với ứng dụng tự phát triển, người bán tạo ứng dụng, chọn quyền và nhận access token trực tiếp trong Seller Center. Với ứng dụng đối tác, bạn giữ app key và secret, còn mỗi cửa hàng của khách hàng cung cấp token riêng. Trường hợp thứ hai tạo ra bài toán quản lý secrets cho môi trường multi-tenant, và vấn đề này sẽ xuất hiện trở lại ở phần giới hạn tốc độ.

Cơ chế ủy quyền API người bán Temu hoạt động thế nào?

Hướng dẫn ủy quyền người bán của Temu nêu rõ phải có sự cho phép của người bán trước khi các API trên open platform hoạt động, đồng thời định nghĩa hai cách để thực hiện:

1. Ủy quyền thủ công. Người bán ủy quyền cho ứng dụng ngay trong Seller Center và chọn các quyền muốn cấp. Việc này xác định phạm vi API mà ứng dụng được phép truy cập. Sau đó access token được hiển thị cho người bán để họ gửi cho bạn.
2. Ủy quyền qua callback. Vẫn là bước đồng ý tương tự, nhưng Temu chuyển trình duyệt của người bán về callback URL của bạn kèm authorization code. Redirect không chứa token; bạn phải dùng method bg.open.accesstoken.create để đổi code lấy token.

Với quy trình callback, bạn đưa người bán đến Seller Center của đúng site, kèm app key, redirect URI và giá trị state. Với cửa hàng tại Hoa Kỳ, cấu trúc URL được tài liệu hóa là https://seller.temu.com/open-platform/client-manage/authorization?appKey=YOUR_KEY&redirect_uri=YOUR_CALLBACK&state=YOUR_STATE. Người bán xuyên biên giới và người bán nội địa đăng nhập vào các backend khác nhau để ủy quyền, vì vậy liên kết phải trỏ đến đúng backend.

Cần xây dựng những gì xung quanh quy trình này?

• Dùng state làm khóa tenant. Đặt vào đó một giá trị có chữ ký và chỉ dùng một lần, ánh xạ authorization code trả về với đúng khách hàng và cửa hàng. Hãy xác nhận trong sandbox rằng state được gửi lại trong redirect trước khi phụ thuộc vào cơ chế này.
• Lưu token cùng với host. Quyền ủy quyền gắn với Seller Center của từng site, vì vậy bản ghi cửa hàng nên lưu token, khu vực và host cùng nhau.
• Coi lỗi quyền truy cập là một sự kiện cần ủy quyền lại. Vì phạm vi quyền được chọn tại thời điểm đồng ý, một ứng dụng sau này cần thêm quyền giao hàng cho đơn hàng bên cạnh quyền sản phẩm sẽ phải yêu cầu người bán cấp lại quyền. Hãy xây dựng luồng “kết nối lại cửa hàng” ngay từ đầu.

Gọi host API Temu nào cho từng khu vực?

Temu công bố ba host production, tất cả đều sử dụng path /openapi/router. Quy tắc trong hướng dẫn endpoint là cửa hàng Hoa Kỳ dùng host US, còn cửa hàng EU dùng host EU.

Đừng hardcode một host duy nhất. Hãy xác định host từ bản ghi cửa hàng và lưu mapping trong configuration để khi có site mới, bạn không cần triển khai lại ứng dụng. Payload sản phẩm cũng khác nhau theo site và đơn vị tiền tệ, vì vậy listing được tạo cho một site không mặc nhiên hợp lệ trên site khác.

Cách ký một request API Temu

Mọi lần gọi API đều phải có chữ ký; request có chữ ký không hợp lệ sẽ bị từ chối. Phương thức được tài liệu hóa là dùng MD5 trên một chuỗi xác định theo quy tắc sau:

1. Tập hợp mọi parameter của request: các parameter dùng chung (type, app_key, access_token, data_type, timestamp) cùng các trường riêng của method. Tất cả đều nằm ở cấp cao nhất của JSON body.
2. Sắp xếp tên parameter theo thứ tự ASCII tăng dần.
3. Nối tên và giá trị của từng parameter mà không dùng dấu phân cách. Object và array lồng nhau được đưa vào dưới dạng JSON text.
4. Đặt app_secret ở cả đầu và cuối chuỗi đó.
5. Tính MD5 cho kết quả rồi chuyển chuỗi hex sang chữ hoa. Đây là trường sign, được thêm vào body trước khi gửi.

Dưới đây là một implementation có thể chạy được. Đoạn mã tái tạo chữ ký từ ví dụ thực hành trong hướng dẫn ký của chính Temu (4CCF219942D4180C6DDA3CE36C1B838F cho payload giao hàng được tài liệu hóa). Đây là phép kiểm tra bạn nên chạy trước khi tin cậy bất kỳ signer nào, kể cả signer do bạn tự viết.

import hashlib
import json
import time

import requests

HOSTS = {
    "us": "https://openapi-b-us.temu.com/openapi/router",
    "eu": "https://openapi-b-eu.temu.com/openapi/router",
    "global": "https://openapi-b-global.temu.com/openapi/router",
}


def to_str(value):
    """Serialize one parameter value for the signing string."""
    if isinstance(value, str):
        return value
    if isinstance(value, bool):
        return "true" if value else "false"
    if isinstance(value, (dict, list)):
        return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
    return str(value)


def sign(params, app_secret):
    """Sort by key, join key+value, wrap in app_secret, MD5, uppercase."""
    body = "".join(key + to_str(params[key]) for key in sorted(params))
    raw = app_secret + body + app_secret
    return hashlib.md5(raw.encode("utf-8")).hexdigest().upper()


def call(region, method, app_key, app_secret, access_token=None, **payload):
    params = {
        "type": method,
        "app_key": app_key,
        "data_type": "JSON",
        "timestamp": int(time.time()),
        **payload,
    }
    if access_token:  # absent only when exchanging the auth code for a token
        params["access_token"] = access_token
    params["sign"] = sign(params, app_secret)
    response = requests.post(HOSTS[region], json=params, timeout=30)
    response.raise_for_status()
    return response.json()

Những điểm thường khiến việc ký request thất bại

• Payload lồng nhau. Ví dụ thực hành serialize array lồng nhau ở dạng compact, đồng thời thứ tự key trong chuỗi ký khác với thứ tự trong payload gốc được hiển thị ở bước trước. Đừng mặc định rằng thứ tự không quan trọng. Nếu request với parameter phẳng ký đúng nhưng request có list lồng nhau thất bại, hãy kiểm tra serialization và thứ tự key trước, đồng thời xác minh một request lồng nhau trong sandbox trước khi áp dụng rộng rãi.
• Các kiểu giá trị chưa được ví dụ đề cập. Ví dụ thực hành dùng string, số nguyên và một array lồng nhau. Boolean và số thập phân không được minh họa, vì vậy hãy kiểm thử chúng trong sandbox thay vì dựa vào phỏng đoán.
• Request đổi code không có token. Khi đổi authorization code lấy access token, bạn chưa có token. Hãy ký bằng những parameter đang có; đó là lý do helper bên trên để access_token ở dạng tùy chọn.
• Đơn vị thời gian và định dạng. Ví dụ sử dụng Unix timestamp tính bằng giây. Bạn cũng phải gửi cùng đơn vị này.

Hướng dẫn dành cho nhà phát triển cũng có ví dụ request bằng Python và hướng dẫn Postman, đồng thời nền tảng cung cấp các cửa hàng sandbox để kiểm thử. Hãy chạy mọi endpoint mới trên sandbox trước.

Giới hạn tốc độ API Temu và cách thiết kế phù hợp

Hướng dẫn rate limit cho biết giới hạn ban đầu thường là 20 request mỗi giây trên mỗi app key. Các giới hạn có thể được điều chỉnh linh hoạt; nếu cần lưu lượng cao hơn, Temu yêu cầu liên hệ đội ngũ đối tác qua email và nêu rõ lý do.

Điểm quan trọng nằm ở đơn vị áp dụng: giới hạn gắn với app key, không phải cửa hàng. Nếu xây dựng ứng dụng đối tác, tất cả người bán kết nối với bạn đều dùng chung một ngân sách. Ba mươi cửa hàng cùng chạy đồng bộ toàn bộ danh mục vào đầu giờ sẽ làm nghẽn lẫn nhau.

• Đặt một bộ limiter trước toàn bộ lệnh gọi đến Temu, phân bổ theo app key, thay vì để từng worker tự giới hạn riêng.
• Phân tán lịch chạy. Gán offset riêng cho từng cửa hàng và thêm jitter để các tiến trình đồng bộ không bắt đầu cùng lúc.
• Ưu tiên xử lý theo sự kiện thay vì polling. Các webhook bên dưới giúp bạn không phải gọi danh sách đơn hàng mỗi phút cho từng cửa hàng.
• Retry với backoff và ngưỡng tối đa, đồng thời ghi log riêng các request bị giới hạn để nhận biết áp lực tăng lên trước khi khách hàng phát hiện.

Đồng bộ đơn hàng và giao hàng với API Temu

Quy trình đơn hàng tương ứng với một nhóm method ngắn gọn. Các tên này lấy từ tài liệu tham chiếu hiện tại; Postman workspace công khai của Temu cũng thông báo các API truy vấn đơn hàng và giao hàng đã chuyển sang V2. Vì vậy, hãy kiểm tra tài liệu tham chiếu trước khi cố định tên method (ví dụ trong hướng dẫn ký vẫn dùng tên method giao hàng cũ hơn).

Cần thiết kế có chủ đích cho ba yếu tố sau:

• Định danh. Temu tách đơn hàng cha (parentOrderSn) và đơn hàng (orderSn). Hãy dùng cả hai làm khóa import và bảo đảm tính idempotent để việc gọi lại danh sách không tạo đơn trùng.
• Kiện hàng. Hướng dẫn tích hợp có các ví dụ giao tách kiện, vì vậy một đơn hàng không phải lúc nào cũng tương ứng với một kiện. Hãy lưu kiện hàng thành các bản ghi riêng.
• Dữ liệu cá nhân. Thông tin giao hàng được trả về ở dạng mã hóa và có method giải mã riêng. Chỉ giải mã khi in nhãn, không đưa địa chỉ rõ vào log và xóa dữ liệu khi không còn cần thiết.

Quản lý sản phẩm, tồn kho và giá qua API

Đăng listing là phần nặng nhất của API. Template danh mục, thuộc tính, hình ảnh và dữ liệu tuân thủ đều được đưa vào cùng một lệnh tạo sản phẩm.

• Thiết lập mã SKU bên ngoài trước. Đây là khóa liên kết giữa catalog của bạn và các ID trên Temu. Việc bổ sung sau khi đã có hàng nghìn listing sẽ rất khó khăn.
• Coi việc đăng sản phẩm là bất đồng bộ. Temu có method riêng để kiểm tra trạng thái đăng, vì vậy hãy gửi yêu cầu, sau đó polling trạng thái và hiển thị lý do cho người bán.
• Đừng coi giá chỉ là một trường dữ liệu đơn giản. API có các method đề xuất giá và giá gợi ý bên cạnh việc thay đổi giá trực tiếp. Hãy đọc hướng dẫn quản lý giá trước khi viết logic repricing.
• Giữ đồng bộ tồn kho đơn giản và nhanh. Bán vượt tồn là lỗi tốn kém, vì vậy hãy gửi thay đổi tồn kho ngay khi phát sinh và thực hiện đối soát theo lịch.

Webhook Temu: Có những sự kiện nào và sử dụng ra sao?

Temu tài liệu hóa bốn loại sự kiện. Payload khá nhỏ, chỉ gồm định danh và trạng thái chứ không chứa toàn bộ đơn hàng.

• Sự kiện là tín hiệu kích hoạt, không phải dữ liệu đầy đủ. Khi nhận được sự kiện, hãy ghi vào queue và phản hồi nhanh, sau đó gọi method chi tiết đơn hàng để lấy dữ liệu chính xác.
• Lưu ý đơn vị thời gian. Sự kiện đơn hàng dùng giây, còn sự kiện hậu mãi dùng mili giây. Chuẩn hóa cả hai về cùng một đơn vị ngay khi tiếp nhận sẽ tránh lỗi sắp xếp.
• Lấy lại địa chỉ khi có sự kiện thay đổi địa chỉ trước khi in nhãn giao hàng.
• Duy trì cơ chế đối soát. Webhook có thể bị bỏ lỡ khi endpoint ngừng hoạt động, vì vậy một lệnh gọi danh sách theo lịch để phát hiện khoảng trống là biện pháp dự phòng đáng giá.

Tích hợp trực tiếp với Temu hay dùng lớp đa kênh?

Bạn có thể gọi trực tiếp API Temu hoặc kết nối thông qua một lớp trung gian cung cấp API hợp nhất cho nhiều sàn. Không có lựa chọn nào luôn phù hợp trong mọi trường hợp.

Điểm đánh đổi nằm ở các abstraction phẳng. Một schema chung cho nhiều sàn che khuất chính những hành vi làm mỗi sàn trở nên khác biệt; điều này thể hiện rõ nhất ở luồng hậu mãi, tuân thủ và quản lý giá của Temu.

Nếu muốn giao việc xây dựng Temu cho một đội ngũ đã triển khai tích hợp marketplace cho listing, tồn kho, đơn hàng và tracking, dịch vụ tích hợp marketplace của Netalith hỗ trợ Temu cùng Amazon, eBay, Walmart, Etsy, Shein và Shopee.

Checklist triển khai tích hợp Temu trên production

Nếu muốn có thêm một góc nhìn trước khi đầu tư thời gian phát triển, hãy yêu cầu báo giá miễn phí từ Netalith và mô tả những kênh cùng quy trình bạn cần kết nối.