(68) Inventory changed
Có gì thay đổi?
TikTok Shop đang ra mắt webhook Inventory changed mới để đẩy các sự kiện thời gian thực cho những thay đổi về số lượng tồn kho của SKU. Trước đây, các nhà phát triển phải gián tiếp suy ra các thay đổi tồn kho bằng cách đăng ký nhiều thông điệp webhook (ví dụ: tạo đơn hàng, chiến dịch marketing), điều này phức tạp và dễ phát sinh lỗi. Webhook Inventory changed mới chuẩn hóa các thông báo thay đổi tồn kho. Dù nguyên nhân là do tạo đơn hàng mới, hủy đơn hàng, điều chỉnh thủ công của người bán, gọi API, hay khóa/giải phóng tồn kho từ các chiến dịch marketing hoặc hợp tác với nhà sáng tạo, hệ thống sẽ đẩy các thông điệp thời gian thực với cấu trúc thống nhất qua webhook này. Điều này giúp các nhà phát triển và nhà cung cấp dịch vụ đồng bộ tồn kho sản phẩm chính xác và hiệu quả hơn, tránh các vấn đề bán quá số lượng hoặc hết hàng do thông tin tồn kho bị trễ hoặc không nhất quán, đồng thời đơn giản hóa logic quản lý tồn kho.
Những thị trường nào bị ảnh hưởng?
Thay đổi này áp dụng cho tất cả các thị trường.
Ai bị ảnh hưởng?
Thay đổi này áp dụng cho tất cả các nhà phát triển đã tích hợp với các API của TikTok Shop.
Phiên bản nào được áp dụng?
Đây là một sự kiện đẩy webhook mới và không liên quan đến việc thay đổi phiên bản API. Các thông điệp sẽ được đẩy đến webhook URL được cấu hình trong ứng dụng của nhà phát triển.
Cần thực hiện hành động gì?
Rất khuyến khích tích hợp webhook này vào ứng dụng của bạn để các nhà bán hàng của bạn có thể hưởng lợi từ việc đồng bộ tồn kho hai chiều theo thời gian thực hơn. Sau khi triển khai, bạn có thể theo dõi các thay đổi tồn kho trên nền tảng TikTok Shop một cách đáng tin cậy hơn. Mô tả chi tiết về giao thức và các trường của webhook này có thể được tìm thấy trong phần chi tiết kỹ thuật bên dưới.
Chi tiết kỹ thuật
Điều kiện kích hoạt
Webhook Inventory changed sẽ được kích hoạt khi bất kỳ sự kiện nào sau đây gây ra thay đổi về số lượng tồn kho của SKU:
order_created: Đơn hàng được đặt thành công, tồn kho được cam kết.order_canceled: Đơn hàng bị hủy bởi người dùng hoặc người bán, tồn kho đã cam kết được giải phóng trở lại tồn kho khả dụng.order_shipped: Đơn hàng đã được giao, tồn kho đã cam kết bị trừ đi.manual_adjustment: Người bán điều chỉnh thủ công tồn kho trong Seller Center.api_sync: Nhà phát triển cập nhật tồn kho thông qua các OpenAPI liên quan đến tồn kho.campaign_lock: Người bán đăng ký tham gia các chiến dịch marketing của nền tảng, một phần tồn kho bị khóa.campaign_unlock: Chiến dịch marketing kết thúc hoặc người bán rút lui, tồn kho bị khóa được giải phóng.creator_lock: Người bán thiết lập hợp tác với một nhà sáng tạo, phân bổ tồn kho độc quyền.creator_unlock: Hợp tác với nhà sáng tạo kết thúc, tồn kho bị khóa được giải phóng.system_auto_replenish: Hệ thống tự động bổ sung tồn kho (ví dụ: đơn hàng thất bại do lỗi ngoại lệ).
Cấu trúc Payload
Payload cho mỗi lần đẩy cập nhật tồn kho bao gồm thông tin sự kiện chung, ảnh chụp nhanh tồn kho sau thay đổi, và các chi tiết thay đổi cụ thể.
| Field Name | Type | Required | Mô tả |
|---|---|---|---|
| event_id | String | Yes | Định danh duy nhất cho sự kiện, có thể được dùng cho tính idempotency ở cấp độ sự kiện. |
| occurred_at | String | Yes | Thời điểm sự kiện xảy ra (UTC+0), theo định dạng ISO 8601. |
| seller_id | int64 | Yes | Seller ID. |
| product_id | int64 | Yes | Product ID. |
| sku_id | int64 | Yes | SKU ID nơi xảy ra thay đổi tồn kho. |
| quantity_snapshot_after_change (Object): Ảnh chụp nhanh tồn kho SKU sau thay đổi | |||
| total_quantity | Integer | Yes | Tổng tồn kho trong kho. Bằng total_available_quantity + total_committed_quantity. |
| total_available_quantity | Integer | Yes | Tồn kho khả dụng trong kho. Tổng tồn kho thực tế có trong kho và sẵn sàng để bán. |
| total_committed_quantity | Integer | Yes | Tồn kho đã cam kết cho đơn hàng. Tồn kho đã được người dùng đặt nhưng chưa được giao. |
| in_shop_quantity | Integer | Yes | Tồn kho khả dụng trong shop. Tồn kho khả dụng hiện không bị khóa bởi bất kỳ đơn hàng, chiến dịch, hoặc nhà sáng tạo nào. Bằng total_available_quantity - (campaign_locked_quantity + creator_locked_quantity). |
| campaign_locked_quantity | Integer | Yes | Tồn kho bị khóa bởi các chiến dịch marketing. |
| creator_locked_quantity | Integer | Yes | Tồn kho bị khóa bởi các hợp tác với nhà sáng tạo. |
| change_detail (List): Danh sách các chi tiết thay đổi tồn kho. Trong hầu hết các trường hợp, danh sách này chỉ chứa một object. | |||
| idempotency_key | String | Yes | Định danh duy nhất cho một thao tác thay đổi đơn lẻ, có thể được dùng cho tính idempotency ở cấp độ chi tiết. |
| trigger_source | String | Yes | Lý do thay đổi tồn kho, tương ứng với Trigger Condition Code ở trên. |
| occurred_at | String | Yes | Thời điểm sự kiện thay đổi cụ thể xảy ra (UTC+0). Có thể được dùng để đảm bảo xử lý theo thứ tự. |
| total_quantity_delta | Integer | Yes | Lượng thay đổi của tổng tồn kho trong kho. |
| available_quantity_delta | Integer | Yes | Lượng thay đổi của tồn kho khả dụng trong kho. |
| committed_quantity_delta | Integer | Yes | Lượng thay đổi của tồn kho đã cam kết cho đơn hàng. |
| in_shop_quantity_delta | Integer | Yes | Lượng thay đổi của tồn kho khả dụng trong shop. |
| campaign_locked_quantity_delta | Integer | Yes | Lượng thay đổi của tồn kho bị khóa bởi chiến dịch marketing. |
| creator_locked_quantity_delta | Integer | Yes | Lượng thay đổi của tồn kho bị khóa bởi hợp tác với nhà sáng tạo. |
| Lưu ý: Đối với tất cả các trường delta, số dương thể hiện sự tăng lên, và số âm thể hiện sự giảm xuống. |
Ví dụ Payload Sau đây là một ví dụ về Webhook payload khi một người bán tăng tồn kho của một SKU lên 4 đơn vị một cách thủ công thông qua Seller Center: JSONWord Wrap{ "event_id": "d7813cae-9997-4d24-a583-7d85801250f1", "occurred_at": "2026-04-02T09:28:34.979101552Z", "seller_id": "7498123456789012345", "product_id": "1891234567890123456", "sku_id": "1729507467923261408", "quantity_snapshot_after_change": { "total_quantity": 7, "total_available_quantity": 7, "total_committed_quantity": 0, "in_shop_quantity": 7, "campaign_locked_quantity": 0, "creator_locked_quantity": 0 }, "change_detail": [ { "idempotency_key": "d7813cae-9997-4d24-a583-7d85801250f1", "trigger_source": "manual_adjustment", "occurred_at": "2026-04-02T09:28:34.979101552Z", "total_quantity_delta": 4, "available_quantity_delta": 4, "committed_quantity_delta": 0, "in_shop_quantity_delta": 4, "campaign_locked_quantity_delta": 0, "creator_locked_quantity_delta": 0 } ] }