Thông báo Push Mechanism

Đăng ký Shopee Open Platform Push Mechanism giúp bạn nhận thông báo ngay lập tức khi một sự kiện cụ thể xảy ra. Điều này cho phép bạn nhận cập nhật kịp thời mà không cần phải định kỳ polling API endpoint.

⚠️ Lưu ý: Push Mechanism trên Shopee Open Platform Console tương đương với cái thường được gọi là webhooks.

Dưới đây là tổng quan về cách Push Mechanism hoạt động trên Shopee Open Platform:

Bạn đăng ký một loại push cụ thể cho ứng dụng của mình và xác định một callback URL.
Sự kiện cụ thể, chẳng hạn như cập nhật trạng thái đơn hàng, xảy ra.
Shopee gửi yêu cầu HTTP POST đến callback URL đã xác định.
Bạn nhận thông báo qua callback URL đã xác định.

⚠️ Lưu ý: Push Mechanism (webhooks) trên Shopee Open Platform chỉ thông báo cho bạn rằng dữ liệu cho sự kiện cụ thể đã thay đổi. Để lấy thông tin cập nhật hơn, hãy gọi API tương ứng. Bạn được khuyến khích sử dụng cả hai để nâng cao hiệu quả tích hợp của hệ thống.

Tìm hiểu về thông báo Push Mechanism

Có 5 danh mục webhooks (Push) khả dụng trên Shopee Open Platform:

Shopee - Webhooks cho ủy quyền cửa hàng và các cập nhật Shopee quan trọng.
Order - Webhooks cho cập nhật trạng thái đơn hàng và số theo dõi.
Marketing - Webhooks để theo dõi các hoạt động khuyến mãi của sản phẩm.
Product - Webhooks cho thông tin sản phẩm, vi phạm và cập nhật quy trình đăng ký thương hiệu.
Chat - Webhook cho cập nhật tin nhắn từ người mua.

Đọc thêm về các thông báo Push này bên dưới, được sắp xếp theo mức độ phổ biến.

Shopee Push

Push ủy quyền cửa hàng (Code:1)

Nhận thông báo với danh sách shop ID và merchant ID áp dụng khi người bán ủy quyền ứng dụng của bạn truy cập dữ liệu (các) cửa hàng của họ.

Push hủy ủy quyền cửa hàng (Code:2)

Nhận thông báo với danh sách shop ID và merchant ID áp dụng khi người bán thu hồi ủy quyền ứng dụng của bạn truy cập dữ liệu (các) cửa hàng của họ.

⚠️ Lưu ý

Người bán có thể thu hồi ủy quyền qua ứng dụng của bạn hoặc Seller Centre.
2 webhook ủy quyền nêu trên rất quan trọng để lấy danh sách shop ID và merchant ID áp dụng khi ủy quyền cho nhiều cửa hàng bị thu hồi qua tài khoản chính. Nếu không có 2 webhook này, địa chỉ callback chỉ trả về ID tài khoản chính.
Push hết hạn ủy quyền Open API (Code:12)

Nhận thông báo trước 7 ngày với danh sách shop ID và merchant ID có ủy quyền sắp hết hạn. Sau đó bạn có thể liên hệ (các) người bán để ủy quyền lại ứng dụng của bạn. Điều này sẽ giúp ngăn ngừa gián đoạn dịch vụ do ủy quyền hết hạn.

⚠️ Lưu ý: Ủy quyền của người bán cho ứng dụng của bạn để truy cập dữ liệu cửa hàng chỉ có hiệu lực trong 1 năm. Sau khi ủy quyền hết hạn, người bán cần ủy quyền lại.

Cập nhật Shopee (Code:5)

Nhận các cập nhật Shopee quan trọng mới nhất một cách nhanh chóng.

Order Push

Push cập nhật trạng thái đơn hàng (Code:3)

Nhận thông báo ngay lập tức về tất cả cập nhật trạng thái đơn hàng. Bao gồm các hủy đơn hàng xảy ra trước khi giao hàng, để bạn có thể thực hiện các bước cần thiết kịp thời.

Push số theo dõi đơn hàng (Code:4)

Nhận thông báo ngay lập tức khi số theo dõi đơn hàng được cập nhật để bạn có thể giao hàng nhanh chóng và tránh phải truy vấn API v2.logistics.get_tracking_number nhiều lần.

Điều này có thể hữu ích khi các đối tác logistics mất thời gian để cập nhật số theo dõi có thể cần thiết trên tài liệu giao hàng.

Push trạng thái tài liệu giao hàng (Code:15)

Nhận thông báo ngay lập tức khi trạng thái tài liệu giao hàng là "READY" hoặc "FAILED", để bạn không cần gọi API v2.logistics.get_shipping_document_result nhiều lần để lấy trạng thái tài liệu giao hàng.

Marketing Push

Push thông tin khuyến mãi sản phẩm (Code:7)

Nhận cập nhật về tồn kho sản phẩm khi bị ảnh hưởng bởi việc tham gia chiến dịch hoặc sự kiện khuyến mãi. Bạn cũng sẽ được thông báo khi tồn kho sản phẩm không còn bị ảnh hưởng vì chiến dịch hoặc sự kiện khuyến mãi đã kết thúc hoặc sản phẩm không còn tham gia.

Push cập nhật khuyến mãi (Code:9)

Nhận cập nhật về các hoạt động khuyến mãi, bao gồm khi sản phẩm được thêm vào/xóa khỏi sự kiện khuyến mãi hoặc khi có cập nhật về thời gian bắt đầu/kết thúc khuyến mãi.

Product Push

Push thay đổi tồn kho đặt trước (Code:8)

Nhận cập nhật về lượng tồn kho sản phẩm đặt trước đã được sử dụng cho mỗi sự kiện khuyến mãi, giúp người bán quản lý các thay đổi về hàng tồn kho.

⚠️ Lưu ý: Tồn kho (sản phẩm) đặt trước là lượng sản phẩm được đặt trước đặc biệt cho một sự kiện khuyến mãi như flash sale.

Push tải lên video (Code:11)

Nhận cập nhật về video sản phẩm đã được chuyển mã thành công. Đây là webhook hữu ích nếu bạn muốn thêm hoặc cập nhật danh sách sản phẩm có video vì bạn chỉ có thể làm điều đó với các tệp video đã được chuyển mã thành công.

Khi bạn đã thực hiện lời gọi API cho v2.media_space.complete_video_upload, hãy chờ Push tải lên video này để biết việc chuyển mã có thành công không. Nếu chuyển mã thành công, bạn có thể tiếp tục thêm hoặc cập nhật danh sách sản phẩm với video_upload_id.

Push sản phẩm bị cấm (Code:6)

Nhận cập nhật nhanh về các sản phẩm bị Shopee cấm để tìm hiểu lý do vi phạm.

Push kết quả đăng ký thương hiệu (Code:13)

Nhận cập nhật về kết quả của các đơn đăng ký thương hiệu, bao gồm được phê duyệt, bị từ chối hoặc được gộp với thương hiệu hiện có.

⚠️ Lưu ý: Người bán có thể đăng ký thương hiệu qua (i) API v2.product.register_brand hoặc (ii) Seller Center để Shopee xem xét. Khi thiết lập danh sách sản phẩm, người bán có thể chọn thương hiệu được công nhận chính thức.

Chat Push

Webchat Push (Code:10)：Thông báo thông tin chat

Nhận thông báo ngay lập tức khi các cửa hàng bạn hỗ trợ nhận tin nhắn từ người mua.

Đăng ký thông báo Push Mechanism

Đăng nhập vào Shopee Open Platform Console và truy cập trang Push Mechanism. Chọn ứng dụng liên quan > chọn Thiết lập Push.

Điền callback URL của bạn > chọn Xác minh.

⚠️ Lưu ý: Để xác minh tính hợp lệ của callback URL đã xác định, Shopee sẽ gửi yêu cầu HTTP POST đến callback URL. Nếu thất bại, bạn có thể xem lý do trong biểu ngữ đỏ xuất hiện trên trang Thiết lập Push.

Sau khi xác minh callback URL thành công, chọn các Push (webhooks) liên quan mà bạn muốn nhận thông báo.

⚠️ Lưu ý: Bạn có thể quản lý cài đặt Push qua Shopee Open Platform Console hoặc qua API v2.push.set_push_config.

Tính khả dụng của thông báo Push (webhooks) phụ thuộc vào loại ứng dụng của bạn; tham khảo bảng bên dưới để biết chi tiết:

Loại ứng dụng	Thông báo Push khả dụng
Original	Tất cả thông báo Push ngoại trừ Push kết quả đăng ký thương hiệu (Code:13)
Hệ thống ERP	Tất cả thông báo Push ngoại trừ Webchat Push (Code:10)
Hệ thống nội bộ người bán	Tất cả thông báo Push
Quản lý sản phẩm	Shopee Push - Push ủy quyền cửa hàng (Code:1) - Push hủy ủy quyền cửa hàng (Code:2) - Push hết hạn ủy quyền Open API (Code:12) - Cập nhật Shopee (Code:5) Product Push - Push thay đổi tồn kho đặt trước (Code:8) - Push tải lên video (Code:11) - Push sản phẩm bị cấm (Code:6) - Push kết quả đăng ký thương hiệu (Code:13) Marketing Push - Push thông tin khuyến mãi sản phẩm (Code:7) - Push cập nhật khuyến mãi (Code:9)
Quản lý đơn hàng	Shopee Push - Push ủy quyền cửa hàng (Code:1) - Push hủy ủy quyền cửa hàng (Code:2) - Push hết hạn ủy quyền Open API (Code:12) - Cập nhật Shopee (Code:5) Order Push - Push trạng thái đơn hàng (Code:3) - Push số theo dõi đơn hàng (Code:4) - Push trạng thái tài liệu giao hàng (Code:15)
Kế toán và tài chính	Shopee Push - Push ủy quyền cửa hàng (Code:1) - Push hủy ủy quyền cửa hàng (Code:2) - Push hết hạn ủy quyền Open API (Code:12) - Cập nhật Shopee (Code:5)
Marketing	Shopee Push - Push ủy quyền cửa hàng (Code:1) - Push hủy ủy quyền cửa hàng (Code:2) - Push hết hạn ủy quyền Open API (Code:12) - Cập nhật Shopee (Code:5) Product Push - Push thay đổi tồn kho đặt trước (Code:8) - Push sản phẩm bị cấm (Code:6) Marketing Push - Push thông tin khuyến mãi sản phẩm (Code:7) - Push cập nhật khuyến mãi (Code:9)
Dịch vụ khách hàng	Shopee Push - Push ủy quyền cửa hàng (Code:1) - Push hủy ủy quyền cửa hàng (Code:2) - Push hết hạn ủy quyền Open API (Code:12) - Cập nhật Shopee (Code:5) Chat Push - Webchat Push (Code:10)

(Tùy chọn) Đối với nhà phát triển có hệ thống chỉ cho phép truy cập từ các địa chỉ IP trong danh sách trắng, sử dụng API v2.public.get_shopee_ip_ranges để lấy địa chỉ IP Open API của Shopee.

Nếu bạn đang kiểm thử, hãy thực hiện lời gọi API trong môi trường sandbox.
Nếu bạn đã sử dụng môi trường thực, hãy thực hiện lời gọi API trong môi trường thực.

Xác thực Push

Để ngăn chặn các cuộc tấn công mạng, chúng tôi đã cung cấp chữ ký xác thực cho mỗi yêu cầu Push, có thể tìm thấy trong trường Authorization của header yêu cầu HTTP. Với điều này, bạn có thể xác định thông tin xác thực của Shopee.

Bước này về mặt kỹ thuật là tùy chọn, nhưng chúng tôi khuyến nghị mạnh mẽ các nhà phát triển sử dụng các bước sau để xác nhận yêu cầu nhằm tạo chữ ký xác thực, đảm bảo nó khớp với chữ ký xác thực được tạo từ yêu cầu Push. Cách bạn có thể tạo chữ ký:

Sử dụng URL, |, response.content làm chuỗi cơ sở chữ ký. Ví dụ:

'http://www.example.com/example/uri|\{"shop\_id": 123, "code": 1, "success": 1, "extra": "shop_id 123 is authorized successfully", "data": {"more_info": "more info"}, "timestamp": 1470198856}'

Lưu ý rằng phương thức json.loads(response.content) không được khuyến nghị

Lấy partner key của bạn từ chi tiết ứng dụng trên Shopee Open Platform Console
Sử dụng chuỗi cơ sở chữ ký và partner key để tạo chữ ký với thuật toán băm HMAC-SHA256. Đầu ra của hàm chữ ký HMAC là chuỗi nhị phân. Điều này yêu cầu mã hóa hex để tạo chuỗi chữ ký.

Demo code

Python:

Python

import hmac

def verify_push_msg(url, request_body, partner_key, authorization):

    base_string = url + '|' + request_body

    cal_auth = hmac.new(partner_key, base_string, hashlib.sha256).hexdigest()

    if cal_auth != authorization:

        return False

    else:

        return True

Go:

package verify

import (

    "crypto/hmac"

    "crypto/sha256"

    "encoding/hex"

    "fmt"

)

func VerifyPushMsg(url, requestBody, partnerKey, authorization string) (result bool) {

    baseStr := url + "|" + requestBody

    h := hmac.New(sha256.New, []byte(partnerKey))

    h.Write([]byte(baseStr))

    calAuth := fmt.Sprintf("%x", h.Sum(nil))

    if authorization != calAuth {

        return false

    }

    return true

}

Java:

Java

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Hex;

import java.io.UnsupportedEncodingException;

import java.security.NoSuchAlgorithmException;

public static Boolean verfiyPushMsg(String url, String requestBody, String partnerKey, String authorization)

        throws NoSuchAlgorithmException, UnsupportedEncodingException, java.security.InvalidKeyException {

    String baseStr = url + "|" + requestBody;

    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");

    SecretKeySpec secret_key = new SecretKeySpec(partnerKey.getBytes("UTF-8"), "HmacSHA256");

    sha256_HMAC.init(secret_key);

    String result = Hex.encodeHexString(sha256_HMAC.doFinal(baseStr.getBytes("UTF-8")));

    return result.equals(authorization);

}

Kích hoạt thông báo Push Mechanism

Lưu ý rằng sau khi đăng ký thông báo Push Mechanism và tạo chữ ký xác thực, bạn cũng phải đảm bảo rằng App Partner ID được thiết lập cho mỗi thông báo Push đã được ủy quyền bởi (các) cửa hàng. Nếu chưa, hãy hoàn tất ủy quyền cửa hàng trước.

Nếu ủy quyền cửa hàng đã hoàn tất, bạn sẽ được thông báo qua Push Mechanism khi các sự kiện liên quan xảy ra.

Tìm hiểu thêm về các sự kiện có thể kích hoạt thông báo Push Mechanism. Lưu ý đảm bảo callback URL của bạn cung cấp phản hồi cho các yêu cầu của chúng tôi.

Chặn thông báo từ các cửa hàng cụ thể

Nếu bạn không muốn nhận thông báo cho một số cửa hàng nhất định, bạn có thể thực hiện bằng các phương pháp sau:

Sử dụng trường blocked_shop_id của API v2.push.set_push_config (Chặn tối đa 500 cửa hàng).
Điền danh sách Shop ID trên trang Push Mechanism trên Shopee Open Platform Console. (Chặn tối đa 500 cửa hàng).

Logic thử lại Push Mechanism

Để tránh nhận thông báo lặp lại từ Push Mechanism, hãy thiết lập callback URL của bạn để phản hồi theo các yêu cầu phản hồi HTTP sau:

Bao gồm mã trạng thái 2xx.
Bao gồm body rỗng.

⚠️ Lưu ý: Tất cả Push (webhooks) hỗ trợ số lượng thông báo tối đa và khoảng thời gian khác nhau cho các thông báo lặp lại. Xem phần tiếp theo Logic cảnh báo/vô hiệu hóa Push Mechanism cho các ứng dụng có tỷ lệ thành công thấp khi phản hồi thông báo.

Xem tài liệu Push Mechanism để biết chi tiết cụ thể.

Logic cảnh báo/vô hiệu hóa Push Mechanism

Shopee Open Platform có logic cảnh báo/vô hiệu hóa dành cho các ứng dụng có tỷ lệ thành công thấp khi phản hồi thông báo Push Mechanism. Đối với các ứng dụng như vậy, chúng tôi sẽ thực hiện hành động phù hợp. Email cảnh báo sẽ được gửi đến bạn hoặc chúng tôi cũng có thể vô hiệu hóa đăng ký thông báo Push Mechanism của bạn.

⚠️ Lưu ý: Tỷ lệ thành công được tính bằng cách so sánh các mục Push thành công với các mục Push thất bại. Push thất bại được định nghĩa là Shopee Open Platform không nhận được phản hồi HTTP với mã trạng thái 2xx và body rỗng trong thời gian timeout.

Xem tài liệu Push Mechanism để biết chi tiết cụ thể.

Dưới đây là chi tiết về các hành động cảnh báo và vô hiệu hóa Push Mechanism:

Email cảnh báo
Bạn sẽ nhận được email cảnh báo mỗi 30 phút nếu:
Đã có hơn 600 thông báo Push Mechanism được gửi đến bạn trong 6 giờ qua VÀ
Tỷ lệ thành công Push tổng thể của bạn dưới 70%.
Email cảnh báo sẽ không được gửi sau khi tỷ lệ thành công của bạn trở lại trên 70%.
Vô hiệu hóa đăng ký thông báo Push Mechanism
Đăng ký thông báo Push Mechanism của bạn sẽ bị vô hiệu hóa và bạn sẽ nhận được email thông báo nếu:
Đã có hơn 600 thông báo Push Mechanism được gửi đến bạn trong 6 giờ qua VÀ
Tỷ lệ thành công Push tổng thể của bạn dưới 30%.
Bạn nên kiểm tra callback URL và đảm bảo bạn đã sẵn sàng nhận thông báo Push Mechanism bình thường trước khi đăng ký lại.

⚠️ Lưu ý

Sau khi đăng ký lại, đây là một số điểm quan trọng cần lưu ý:
Bạn sẽ không nhận được các thông báo Push Mechanism bị bỏ lỡ trong thời gian đăng ký của bạn bị vô hiệu hóa.
Việc tính toán tỷ lệ thành công của thông báo Push Mechanism sẽ được khởi động lại dựa trên các bản ghi từ đăng ký mới của bạn.

Bạn có thể xem tỷ lệ thành công và trạng thái Push Mechanism hiện tại qua trang Shopee Open Platform Console.

Tìm hiểu về thông báo Push Mechanism

Shopee Push​

Order Push​

Marketing Push​

Product Push​

Chat Push​