FBT Inbound API — Hướng Dẫn Tổng Quan
FBT Inbound API — Hướng Dẫn Tổng Quan
Tài liệu tham khảo hợp nhất — Bắt đầu, Khái niệm chính, Sơ đồ quy trình và Hướng dẫn tích hợp cho người bán đối với FBT Inbound và các API tạo hàng hóa (Goods Creation).
1. Tổng quan
Bộ FBT Inbound API cho phép người bán và đối tác logistics tạo, quản lý và theo dõi các lô hàng nhập (inbound shipment) vào kho Fulfillment by TikTok (FBT) theo phương thức lập trình.
Khả năng API mới
FBT đang ra mắt 2 nhóm API mới bên cạnh các API hiện có (vốn đã hỗ trợ tìm kiếm tồn kho, tìm kiếm inbound và bản ghi tồn kho).
① Create Inbound
Quy trình đầu cuối để gửi tồn kho vào kho FBT:
- Tạo kế hoạch inbound & lựa chọn phân bổ (placement selection)
- Xác nhận phương thức vận chuyển & xem lại các yêu cầu
- Đóng gói & gửi hàng — gửi manifest theo thùng (carton) hoặc theo đơn vị (unit)
- Lấy nhãn vận chuyển & cập nhật mã theo dõi của hãng vận chuyển
- Quản lý & hủy đơn inbound khi cần
→ Được đề cập trong Carton Splitting & Unit Splitting
② Create & Match Goods
Quản lý danh mục hàng hóa FBT và liên kết các SKU của TikTok Shop:
- Kiểm tra yêu cầu về hazmat & hạn sử dụng cho từng SKU
- Tạo bản ghi hàng hóa FBT và liên kết với SKU của Shop
- Cập nhật thông tin hàng hóa (kích thước, mã vạch, hazmat)
- Quản lý liên kết SKU-hàng hóa (bind / unbind)
→ Được đề cập trong Goods Management
Hai quy trình Inbound được hỗ trợ
Carton Splitting
- Tồn kho được đóng gói sẵn vào các thùng trước khi tạo inbound và gửi hàng
- Mỗi thùng chứa một hoặc nhiều SKU
- TikTok phân bổ kho cho từng thùng
Unit Splitting
- Tồn kho không được đóng gói tại thời điểm tạo inbound, thông tin đóng gói được chia sẻ sau ở bước gửi hàng (ship)
- Linh hoạt hơn cho việc đóng gói theo luồng
Auth Scope yêu cầu: seller.fbt.inbound — tất cả endpoint trong cả hai quy trình đều yêu cầu scope này trên seller access token.
2. Khái niệm chính
Thuật ngữ cốt lõi cho việc tích hợp FBT API.
Merchant
Một Merchant đại diện cho một thực thể chào bán sản phẩm hoặc dịch vụ trên TikTok Shop với hình thức fulfillment FBT. Mỗi merchant có một FBT Merchant ID duy nhất, bắt buộc phải có trước khi thực hiện bất kỳ lệnh gọi API nào.
Lấy Merchant ID của bạn: Merchant ID được cấp trong quá trình onboarding FBT. Sử dụng Get FBT Merchant Onboarded Regions để xác minh người bán đã đăng ký và truy xuất các khu vực đang hoạt động của họ trước khi gọi bất kỳ API inbound nào.
Goods
FBT Goods là một bản ghi duy nhất do FBT cấp để theo dõi và quản lý tồn kho riêng của từng người bán trong hệ thống Fulfilled by TikTok.
Goods phải được liên kết với một TikTok product ID trước khi merchant có thể tạo lô hàng inbound, quản lý tồn kho hoặc xử lý đơn hàng. Nếu goods bị hủy liên kết khỏi các SKU, tồn kho tương ứng sẽ không còn khả dụng để bán trên TikTok Shop.
Thuật ngữ chính
| Full Name | Who Assigns It | Used In |
|---|---|---|
| TikTok Shop Product /SKU ID | TikTok Shop (từ danh mục sản phẩm của bạn) | CreateGoods, GetHazmatInfo, UpdateSkuRelation |
| FBT Goods ID | Hệ thống FBT — trả về khi CreateGoods thành công | UpdateGoods, UpdateSkuRelation, Inbound APIs |
| Goods Lifecycle |
- Kiểm tra yêu cầu — gọi Get Hazmat & Expiration Info để xác định nhu cầu xử lý đặc biệt
- Tạo & liên kết — gọi Create Goods với
CREATE_AND_BINDđể tạo bản ghi hàng hóa FBT và liên kết với một SKU của TikTok Shop - Tạo inbound — sau khi đã liên kết, sử dụng Inbound APIs để gửi tồn kho
- Quản lý liên kết — sử dụng Update Goods SKU Relation để thêm hoặc xóa liên kết SKU bất cứ lúc nào
Mẹo: Một bản ghi FBT Goods duy nhất có thể được liên kết với nhiều SKU của TikTok Shop (1:N) khi merchant bật channel inventory — hữu ích khi bán cùng một sản phẩm vật lý trên nhiều shop hoặc khu vực.
FBT Warehouse
Các kho FBT được đăng ký tự động sau khi onboarding. Có hai loại kho, mỗi loại có vai trò riêng:
| Warehouse Type | Accepts Inbound | Fulfills Orders | Notes |
|---|---|---|---|
| HUB | ✅ Yes | ❌ No | Chỉ xử lý & phân loại inbound — tồn kho được chuyển đến một FC trước khi có thể bán được. Tính phí phân bổ tại hub, tham khảo merchant academy của FBT để biết chi tiết phí |
| FC (Fulfillment Center) | ✅ Yes | ✅ Yes | Tiếp nhận tồn kho; dùng để xử lý đơn hàng. Merchant không thể chọn thủ công, việc phân bổ của FBT sẽ quyết định FC. |
Sử dụng Get FBT Warehouse List để truy xuất tất cả ID kho, tên, địa chỉ và loại kho. warehouse_id được trả về là bắt buộc khi tạo kế hoạch inbound. |
3. Xác thực (Authentication)
Mọi yêu cầu API phải bao gồm các header sau:
| Header | Value | Notes |
|---|---|---|
content-type | application/json | Bắt buộc trên mọi yêu cầu |
x-tts-access-token | Seller access token của bạn | Lấy qua TikTok Shop OAuth (user_type = 0). Token sẽ hết hạn — hãy xây dựng logic refresh vào pipeline của bạn |
| Example |
HTTPWord Wrap
POST /fbt/202602/create_update_inbound_plan?shop_id=123456 HTTP/1.1
content-type: application/json
x-tts-access-token: eyJhbGciOiJSUzI1NiIsInR5cCI6...
Hết hạn token: Access token sẽ hết hạn. Luôn kiểm tra thời gian hết hạn và refresh bằng refresh token trước khi thực hiện lệnh gọi API trong các pipeline tự động.
4. Trước Khi Bắt Đầu — Danh sách kiểm tra
Xác nhận tất cả những điều sau đây trước khi thực hiện lệnh gọi API đầu tiên của bạn:
- Bạn có một FBT Merchant ID hợp lệ (được cấp trong quá trình onboarding FBT). Xác minh bằng Get FBT Merchant Onboarded Regions
- Hàng hóa TikTok Shop của bạn đã được tạo và liên kết với FBT qua các Goods Management API hoặc cổng người bán FBT
- Bạn có một seller access token với OAuth scope
seller.fbt.inbound - Bạn đã quyết định giữa Carton Splitting (thùng đóng gói sẵn) và Unit Splitting (đơn vị rời)
- Bạn đã quyết định giữa Single_Hub (Single Shipment) và D2FC (Multiple Shipments) tới FBT
5. Create & Match Goods — Tổng quan API
Trước khi gửi tồn kho đến FBT, người bán phải có bản ghi FBT Goods được tạo và liên kết với các SKU của TikTok Shop. Các API này thường nên được gọi trước khi tạo kế hoạch inbound.
Trình tự thiết lập Goods được khuyến nghị
| # | API | Method | Purpose | Key Output |
|---|---|---|---|---|
| 1 | Get Hazmat & Expiration Info | POST | Kiểm tra xem các SKU có phân loại hazmat hoặc quy tắc hạn sử dụng/shelf-life trước khi tạo goods hay không. Tối đa 50 SKU mỗi lần gọi. | Cờ hazmat, quy tắc shelf-life |
| 2 | Create Goods | POST | Tạo bản ghi hàng hóa FBT và liên kết với SKU của TikTok Shop (CREATE_AND_BIND). Bao gồm các trường hazmat/shelf-life nếu được đánh dấu ở bước 1. | tts_goods_id |
| 3 | Update Goods | POST | Chỉnh sửa một bản ghi hàng hóa hiện có — tên, kích thước, mã vạch, xử lý hoàn trả, thông tin hazmat/shelf-life. | Xác nhận cập nhật |
| 4 | Update Goods SKU Relation | POST | Quản lý liên kết giữa FBT goods và các SKU của Shop. Dùng BIND để thêm hoặc UN_BIND để xóa. | Xác nhận thao tác |
Các tham số Goods chính
| Parameter | Where Used | Description |
|---|---|---|
tt_sku_id | GetHazmat, CreateGoods | TikTok Shop SKU ID — định danh chính từ danh mục sản phẩm của người bán |
tts_goods_id | UpdateGoods, UpdateSkuRelation | FBT Goods ID — được cấp khi CreateGoods thành công. Lưu lại giá trị này |
create_goods_type | CreateGoods | CREATE_AND_BIND — tạo bản ghi hàng hóa FBT và liên kết với SKU trong một lệnh gọi |
operation_type | UpdateSkuRelation | BIND để liên kết một SKU, UN_BIND để xóa liên kết |
Cờ xử lý đặc biệt
Một số sản phẩm yêu cầu thêm các trường dữ liệu khi tạo goods:
- Hazmat (
is_hazmat = true): Phải cung cấphazmat_infovớihazmat_type(BATTERY,MAGNETIZED,FLAMMABLE_LIQUID,AEROSOLS) và các chi tiết theo từng loại - Sản phẩm pin: Yêu cầu loại pin (
LITHIUM_ION,LITHIUM_METAL,OTHER), dung lượng, loại đóng gói (STANDALONE/IN_EQUIPMENT/WITH_EQUIPMENT), và mã UN. Lưu ý SDS cho
Vui lòng tham khảo bảng dưới đây để biết quy tắc ánh xạ thông tin hazmat
| Hazmat type | Class | How batteries are packed | Battery type | Flammable liquid type | Un code |
|---|---|---|---|---|---|
| Battery | 9 | Standalone | Lithion Ion | UN 3480 | |
| Battery | 9 | Standalone | Lithion metal | UN3090 | |
| Battery | 9 | Standalone | Other | Other | |
| Battery | 9 | In equipment | Lithion Ion | UN 3481 | |
| Battery | 9 | In equipment | Lithion metal | UN3091 | |
| Battery | 9 | In equipment | Other | Other | |
| Battery | 9 | With equipment | Lithion Ion | UN 3481 | |
| Battery | 9 | With equipment | Lithion metal | UN3091 | |
| Battery | 9 | With equipment | Other | Other | |
| Magnetized material | 9 | UN2807 | |||
| Flammable liquids | 3 | Paints | UN1263 | ||
| Flammable liquids | 3 | Perfumery products | UN1266 | ||
| Flammable liquids | 3 | Alcohols | UN3065 | ||
| Flammable liquids | 3 | Other | Other | ||
| Aerosols | 2 | UN1950 | |||
| Aerosols | 2 | Other |
- Shelf-Life (
is_expiration_management = true): Phải cung cấpshelf_life_attribute_infobao gồm số ngày cutoff inbound, số ngày cảnh báo hết hạn, số ngày cutoff bán hàng và phương thức xử lý cho các đơn vị hết hạn
6. Chọn Quy Trình Inbound Của Bạn
| Criteria | Carton Splitting | Unit Splitting |
|---|---|---|
| Khi nào sử dụng | Bạn biết kích thước & nội dung thùng trước khi gửi hàng | Bạn chưa đóng gói thùng tại thời điểm tạo đơn inbound, hoặc các thùng được đóng gói động bởi kho của bạn |
| inbound_type value | CARTON_SPLITTING | UNIT_SPLITTING |
| Carton data in payload | Bắt buộc — tại thời điểm tạo kế hoạch; | Không bắt buộc, phải cung cấp sau ở bước Ship IBR |
7. Create Inbound — Trình tự gọi API
Thực hiện theo 9 bước theo thứ tự sau. Mỗi bước có thể tạo ra các ID cần thiết cho bước tiếp theo. Cả hai quy trình (Carton / Unit) đều chia sẻ cùng trình tự này — khác biệt duy nhất là ở các trường request/response.
| # | API | Method | Purpose | Key Output | Comments |
|---|---|---|---|---|---|
| 1 | Create / Update Inbound Plan | POST | Tạo kế hoạch inbound mới hoặc cập nhật một bản nháp hiện có. Chỉ định các SKU, số lượng và kho đích. | inbound_plan_id | |
| 2 | List Available Inbound Methods | GET | Truy xuất các phương thức Inbound khả dụng với khoảng thời gian dự kiến cho kế hoạch (Single Hub, D2FC). Đối với hub, nó cũng bao gồm ước tính phí phân bổ. | ETA cho phương thức Inbound khả dụng | Bước này cho bạn biết về tính khả dụng của các phương thức inbound. FBT Inbound method |
| 3 | Get Inbound Method Detail | POST | Lấy chi tiết cho từng phương thức inbound và ETA, bao gồm placement option id và warehouse id. Đối với hub, nó cũng bao gồm ước tính phí phân bổ. | placement_option_id Nếu bạn muốn đến một hub cụ thể, vui lòng sử dụng đúng placement option id tương ứng với hub đó. | Thao tác polling bất đồng bộ: Endpoint này có thể mất tới 3-5 giây để trả về thành công. Chúng tôi khuyến nghị polling mỗi 3-5 giây cho đến khi tác vụ phân bổ thành công |
| 4 | Confirm Inbound Method | POST | Chọn và xác nhận phương thức inbound ưu tiên và tùy chọn phân bổ. Bao gồm placement_option_id được trả về từ Bước 3. | inbound_order_ids đã xác nhận Đối với single hub, bạn sẽ nhận được 1 order id Đối với D2FC bạn sẽ thấy một danh sách các order id | |
| 5 | Ship Inbound Order | POST | Gửi chi tiết lô hàng cuối cùng: manifest theo thùng/đơn vị, nội dung thùng nếu là unit split | trạng thái inbound_order_id chuyển thành "shipped" | Đây là bước bắt buộc để nhận tồn kho. Các đơn inbound chưa được gửi hàng sẽ dẫn đến NCI |
| 6 | Print Label | POST | Tạo nhãn vận chuyển có thể in (theo thùng / theo lô hàng). | Label PDF / URL | Thao tác polling bất đồng bộ: Endpoint này có thể mất tới 30 giây để trả về thành công. Chúng tôi khuyến nghị polling mỗi 3-5 giây cho đến khi task_status thành công và URL được trả về |
| 7 | Update Tracking | POST | Đẩy mã theo dõi của hãng vận chuyển sau khi nhãn bưu kiện nhỏ khả dụng cho từng thùng. | ||
| 8 | Get Inbound Order | GET | Truy xuất chi tiết đơn hàng | Trạng thái & chi tiết đơn hàng | |
| 9 | Cancel Inbound Order | POST | Hủy một đơn hàng (chỉ trước khi kho nhận được lô hàng). Lưu ý việc hủy D2FC IBR có thể phát sinh phí nếu một phần kế hoạch đã được nhận và phần còn lại chưa được nhận. | Xác nhận hủy | |
| Key Field Reference |
plan_id — Tạo mới và Cập nhật
| Scenario | plan_id in request body |
|---|---|
| Tạo kế hoạch inbound mới | Bỏ qua — hệ thống tạo và trả về một inbound_plan_id mới |
| Cập nhật một kế hoạch nháp hiện có | Bắt buộc — bao gồm inbound_plan_id được trả về từ lệnh gọi tạo mới ban đầu |
Timestamp— Định dạng
Tất cả các trường timestamp bên trong tham số yêu cầu phải là một Unix timestamp tính theo giây (UTC):
JSONWord Wrap
{
"cartons": [
{
"items": [
{
"tts_goods_id": "9988776655",
"quantity": 10,
"expiration_timestamp": "1780000000"
}
]
}
]
}
Sử dụng giây (UTC), không phải mili giây.
8. Xử lý lỗi
Mã lỗi HTTP
- 400 Bad Request — Xác thực tất cả các trường bắt buộc và kiểu dữ liệu trước khi gửi
- 401 Unauthorized — Token hết hạn hoặc thiếu. Refresh và thử lại
- 409 Conflict — Kế hoạch/đơn hàng trùng lặp. Kiểm tra
idempotency_keyhoặc các bản ghi hiện có - 429 Rate Limited — Triển khai exponential backoff với jitter. Giới hạn mặc định: 10 req/sec mỗi shop
- 5xx Server Error — Thử lại với backoff (tối đa 3 lần thử lại). Ghi log
request_idtừ response header để escalation
Vấn đề thường gặp & Cách khắc phục
Khung giờ ETA không khả dụng. ETA giúp FBT lập kế hoạch năng lực nhập kho. **** Trong giờ cao điểm, một số phương thức inbound hoặc địa điểm có thể không khả dụng, vui lòng chọn một ETA khác
- Truy xuất các ETA khả dụng từ Get Inbound Method Detail (Bước 3) và chọn từ danh sách đó
Lỗi "Internal Error" chung khi Create Inbound Plan: Hãy thử các bước sau
- Xác minh rằng goods của bạn đã được liên kết với các SKU của TikTok Shop (goods chưa liên kết không thể nhập kho)
- Nếu vẫn tiếp diễn, escalate kèm theo toàn bộ request payload và
request_idtừ response header
Độ trễ Print Label API Việc in nhãn chạy bất đồng bộ sau lệnh gọi print label API.
9. Các FBT API & Webhook khác
| # | Type | API / Webhook | Description |
|---|---|---|---|
| 1 | API | Get FBT Warehouse List | Truy xuất tất cả thông tin kho FBT bao gồm tên và địa chỉ |
| 2 | API | Search Goods Info | Truy xuất thông tin hàng hóa bao gồm kích thước và trọng lượng đã được kho xác minh |
| 3 | API | Search FBT Inventory | Truy xuất chi tiết tồn kho — có thể bán, đã đặt trước, không thể bán và đang vận chuyển ở cấp độ kho |
| 4 | API | Search FBT Inventory Record | Truy xuất các bản ghi thay đổi tồn kho, có thể lọc theo kho và khoảng thời gian |
| 5 | API | Get Inbound Orders | Truy xuất chi tiết đơn inbound bao gồm chi tiết inbound theo kế hoạch/thực tế và trạng thái |
| 6 | Webhook | Merchant Onboard | Được kích hoạt khi một người bán onboard vào FBT |
| 7 | Webhook | Goods Match | Được kích hoạt khi một SKU của TikTok Shop được liên kết hoặc hủy liên kết với FBT goods |
| 8 | Webhook | FBT Inventory Update | Được kích hoạt khi tồn kho FBT được cập nhật |
| 9 | Webhook | FBT Inbound Status Change | Được kích hoạt khi trạng thái đơn inbound FBT được cập nhật |
10. Danh sách kiểm tra Testing & Go-Live
Go-Live
- Đã triển khai logic refresh token
- Lựa chọn ETA: Truy xuất ETA khả dụng bằng cách gọi List Inbound method
- Tạo nhãn: gọi Print Label sau độ trễ bất đồng bộ ngắn sau print label
- Xử lý lỗi: ghi log
request_idtừ response cho tất cả lỗi 5xx - Đã xác nhận việc liên kết goods cho tất cả các SKU trong kế hoạch inbound của bạn
- Đã xác nhận kho đang hoạt động cho merchant của bạn
- Chuyển sang production với
shop_idvà thông tin xác thực thật chỉ sau khi đã được phê duyệt trên sandbox
11. Câu hỏi thường gặp (FAQs)
Giá trị Inbound Method
Q: D2FC và ONE_HUB có nghĩa là gì trong response của ListAvailableInboundMethod?
- D2FC: Direct to Fulfillment Center — lô hàng của bạn đi thẳng đến FC cuối cùng xử lý đơn hàng của khách
- ONE_HUB: Lô hàng của bạn được gửi trước đến một hub/điểm hợp nhất để phân loại, sau đó được chuyển tiếp đến FCĐây là hai giá trị tiêu chuẩn; các giá trị bổ sung theo từng khu vực có thể khả dụng tùy thuộc vào vị trí kho.
**Q: Tôi có thể cập nhật mã theo dõi sau khi đã gửi không? **Có — sử dụng Update Tracking API để đẩy mã theo dõi của hãng vận chuyển mới hoặc đã sửa bất cứ lúc nào sau khi bàn giao cho hãng vận chuyển.
Nội dung này có hữu ích không?Hữu ích
Không hữu ích
PreviousNext