Nâng cấp lên API phiên bản 202309

Hướng dẫn này dành cho các nhà phát triển hiện tại để tìm hiểu về những thay đổi trong và nâng cấp lên phiên bản 202309 (v202309). Trước khi đọc hướng dẫn, chúng tôi giả định rằng bạn đã tìm hiểu và phát triển app với TikTok Shop Open APIs.

Lợi ích của v202309

Bản phát hành TikTok Shop Open API 202309 (v202309) bao gồm toàn bộ chức năng đã có trước đó từ các phiên bản API trước tháng 9 năm 2023, cùng với những cải tiến sau:

• API mới - đáp ứng nhu cầu kinh doanh của nhà phát triển và người bán
• Thông số kỹ thuật đã được cập nhật để tuân thủ chặt chẽ hơn các nguyên tắc thiết kế RESTful
• Tài liệu mới - Tất cả API sẽ có tài liệu rõ ràng và được duy trì liên tục

Tài liệu mới

Chúng tôi đã phát hành tài liệu mới cho API v202309:

• API reference cung cấp thông tin đầy đủ, cập nhật về tất cả tài nguyên và endpoint của v202309.
• Developer Guide và Partner Guide đã được thiết kế lại và chỉnh sửa để dễ sử dụng, toàn diện và dễ hiểu hơn. Chúng bao gồm các hướng dẫn sử dụng API thiết yếu, giải pháp tích hợp và quy trình tạo/xuất bản app.

Ngừng hỗ trợ các phiên bản API cũ

Các phiên bản API cũ (trước tháng 9 năm 2023) sẽ không còn được hỗ trợ hoặc duy trì kể từ ngày 30 tháng 6 năm 2024 và sẽ ngừng hoạt động vào ngày 31 tháng 12 năm 2024.

App mới nên sử dụng độc quyền v202309 và không dùng các phiên bản cũ.

Sau ngày 31 tháng 12 năm 2024, tất cả yêu cầu đến các phiên bản API cũ sẽ thất bại.

Tóm tắt các thay đổi

Tính năng mới và cải tiến

Products

API name	Changes
Create Product	* Các thẻ HTML mới khả dụng trong mô tả sản phẩm: <strong>, <b>, <em>, <i>, <br>, <u>

• Các thẻ mới này khả dụng trong mô tả sản phẩm ở tất cả các phiên bản của endpoint Create Product. | | Partial Edit Product | * Endpoint API mới để chỉnh sửa một phần tài nguyên sản phẩm thay vì yêu cầu toàn bộ đối tượng sản phẩm. | | Get Brand | * Thuộc tính mới brand_status được thêm vào component brand_list, dùng để cho biết người bán có thể sử dụng thương hiệu này để đăng sản phẩm trong danh mục đã chọn hay không. | | Get Categories, Get Attributes, Get Global Categories | * locale mới được thêm vào tham số yêu cầu. Thông tin danh mục hoặc thuộc tính sản phẩm sẽ được trả về bằng ngôn ngữ tương ứng dựa trên locale được chỉ định. | | Get Product List | * Tham số yêu cầu seller_skus hỗ trợ nhập nhiều seller SKU, làm điều kiện lọc dùng để tìm kiếm sản phẩm. Tham số này cho phép bạn tìm kiếm tất cả sản phẩm chứa các Seller SKU này. | | Get Product Detail | * Thuộc tính mới suggestions được thêm vào component qc_reasons. Khi trạng thái sản phẩm là failed, thuộc tính suggestions sẽ chứa lý do cụ thể khiến việc kiểm duyệt thất bại. | | Product Audit Update | * Nhiều loại tin nhắn hơn được gửi từ webhook này. Ví dụ: xóa sản phẩm và vô hiệu hóa sản phẩm.
• Tên của webhook được đổi thành "Product Status Update" |

Orders

API name	Changes
Get Order List	* Các thuộc tính chi tiết đơn hàng được trả về từ API.
	* Dữ liệu của đơn hàng mẫu được trả về từ API. Thuộc tính mới is_sample_order được thêm vào phản hồi, cho biết đơn hàng có phải là đơn hàng mẫu hay không.
Get Order Detail	* Thuộc tính district_info_list được lồng trong component recipient_address.
	* Dữ liệu của đơn hàng mẫu được trả về từ API. Thuộc tính mới is_sample_order được thêm vào phản hồi, cho biết đơn hàng có phải là đơn hàng mẫu hay không. Đơn hàng mẫu có thể được truy xuất và xác định từ tất cả các phiên bản của API Get Order Detail.
	* Đối với người bán nội địa tại thị trường US và UK, thuộc tính package_id và package_status sẽ không được trả về trước khi kiện hàng được giao đi

Fulfillment

API name	Changes
Mark Package as Shipped	* Endpoint mới dành cho người bán thực hiện đơn hàng thông qua đơn vị vận chuyển do họ tự chọn/ưa thích. API này cho phép người bán tải thông tin kiện hàng hợp lệ, đơn hàng/mục dòng đơn hàng, lên TikTok Shop.

• Endpoint mới này hỗ trợ chia tách giao hàng ở cấp độ mục hàng | | Get Eligible Shipping Service | * Đối với tùy chọn vận chuyển "shipped via platform", sử dụng order_id và order_line_item_id để truy vấn danh sách dịch vụ vận chuyển khả dụng. | | Create Packages | * Đối với tùy chọn vận chuyển "shipped via platform", sử dụng order_id và order_line_item_id để mua nhãn và giao đơn hàng.
• Mới hỗ trợ chia tách giao hàng ở cấp độ mục hàng với endpoint này. |

Return, refund, cancellation

Vì các giải pháp và chính sách hậu mãi liên quan đến trả hàng, hoàn tiền và hủy đơn khác nhau giữa các thị trường, nên tính khả dụng của một số tính năng API cũng khác nhau theo thị trường. Nhà phát triển nên hiểu rõ các giải pháp và chính sách cụ thể tại thị trường mục tiêu của mình trước khi sử dụng các API tương ứng.

Tìm hiểu thêm về cách sử dụng các API trên tại Cancel/Return/Refund API Overview

API name	Changes
Search Cancellation	Endpoint API mới để truy xuất một hoặc nhiều lệnh hủy đơn hàng.
Cancel Order	Endpoint API mới để hủy một đơn hàng thay mặt cho người bán.
Hiện tại, endpoint mới này hỗ trợ hủy ở cấp độ mục hàng cho người bán nội địa và xuyên biên giới tại thị trường US.
Approve Cancellation	Endpoint API mới để chấp thuận yêu cầu hủy đơn hàng của người mua.
Reject Cancellation	Endpoint API mới để từ chối yêu cầu hủy đơn hàng của người mua.
Search Returns	Endpoint API mới để truy xuất một hoặc nhiều lượt trả hàng.
Create Return	Endpoint API mới để khởi tạo yêu cầu trả hàng thay mặt cho người mua.
Approve Return	Endpoint API mới để chấp thuận yêu cầu trả hàng của người mua.
Reject Return	Endpoint API mới để từ chối yêu cầu trả hàng hoặc hoàn tiền của người mua.
Get Return Records	Endpoint API mới để truy vấn danh sách các bước xử lý của bản ghi trả hàng hoặc hủy đơn hàng.
Calculate Refund	Endpoint API mới để kiểm tra số tiền có thể hoàn của đơn hàng.
Get Aftersale Eligibility	Endpoint API mới để kiểm tra giải pháp hậu mãi đủ điều kiện cho một đơn hàng. Chẳng hạn như liệu người bán có thể khởi tạo hoàn tiền, trả hàng hoặc hủy một đơn hàng cụ thể hay không.
Get Reject Reasons	Endpoint API mới để lấy lý do từ chối đủ điều kiện cho việc hủy hoặc trả hàng. Người bán bắt buộc phải đưa ra lý do khi từ chối yêu cầu hủy, hoàn tiền và trả hàng.
Cancellation Status Change Webhook	Loại webhook mới để lấy trạng thái hủy đơn hàng.
Return Status Change Webhook	Loại webhook mới để lấy trạng thái trả hàng/hoàn tiền của đơn hàng.

Finance

API name	Changes
Get Order Statement Transactions	Endpoint API mới để truy xuất danh sách giao dịch liên kết với một đơn hàng được chỉ định bằng order ID. Nó cũng trả về chi tiết giao dịch ở cấp độ SKU.
Get Statements	Endpoint API mới để lấy danh sách bản ghi sao kê trong khoảng thời gian được chỉ định, được quyết toán theo ngày. Bạn có thể lọc các bản sao kê dựa trên trạng thái thanh toán.
Get Statement Transactions	Endpoint API mới để lấy danh sách giao dịch dựa trên statement_id. Chúng tôi sẽ trả về danh sách đơn hàng. Nếu bạn cần chi tiết giao dịch ở cấp độ SKU, hãy truyền order_id vào Get Order Statement Transactions.
Get Payments	Endpoint API mới để lấy danh sách thanh toán dựa trên khoảng thời gian, bao gồm trạng thái thanh toán hiện tại. Sử dụng danh sách này để đối soát các khoản thanh toán với tài khoản ngân hàng của Người bán.
Get Withdrawals	Endpoint API mới để lấy danh sách bản ghi rút tiền (khi Người bán rút tiền từ TikTok Shop) dựa trên khoảng thời gian được chỉ định.

Thực hiện yêu cầu

Để thực hiện yêu cầu đến các endpoint API 202309, hãy sử dụng URI với cấu trúc mới. Chỉ định tên phiên bản (ví dụ 202309) trong đường dẫn thay vì làm tham số truy vấn. Phiên bản mới cũng giới thiệu định danh tài nguyên làm tham số đường dẫn.

Ví dụ, https://open-api.tiktokglobalshop.com/fulfillment/202309/orders/576619223164029995/packages

URI cho mỗi endpoint phiên bản 202309 được chỉ định trong API reference. Hãy kiểm tra API reference để biết chính xác URI của các endpoint.

Kiểu dữ liệu liệt kê (Enumerate)

Chúng tôi đã cải thiện khái niệm chung về trạng thái để mang tính mô tả hơn. Trước đây, trạng thái đơn hàng được ánh xạ sang các mã, đòi hỏi nhà phát triển phải diễn giải. Chúng tôi đã loại bỏ các mã dựa trên int này, và phát triển các trạng thái ENUM dựa trên string, chẳng hạn như "UNPAID" và "AWAITING_SHIPMENT" để đơn giản hóa quy trình phát triển.

Ví dụ:

• v202305 của API Get Order Detail, giá trị thuộc tính order_status có kiểu int: 100 nghĩa là UNPAID, 111 nghĩa là AWAITING_SHIPMENT
• v202309 của API Get Order Detail, giá trị thuộc tính order_status có kiểu string. UNPAID và AWAITING_SHIPMENT được trả về từ API.

Phân trang

Để chuẩn hóa biểu diễn và đảm bảo hiệu năng, chúng tôi đã giới thiệu phân trang dựa trên token vào thiết kế API. API v202309 chỉ hỗ trợ phân trang bằng các tham số page_size và page_token. Tham số offset không còn được hỗ trợ.

Ủy quyền

Chúng tôi đã ngừng sử dụng access_token trong query và hiện yêu cầu truyền nó trong HTTP header x-tts-access-token để tăng cường bảo mật.

Chữ ký (Signature)

v202309 của API mở rộng bảo vệ chữ ký vượt ra ngoài chỉ tham số đường dẫn và tham số truy vấn. Chữ ký giờ đây cũng sẽ bao gồm thân yêu cầu (request body) cho các API POST. Để tạo chữ ký cho các API v202309, nhà phát triển cần sử dụng phương pháp mới.

Content type

Các API v202309 hiện chỉ hỗ trợ application/json cho các yêu cầu không phải nhị phân. Yêu cầu nhị phân nên sử dụng multipart/form-data để đảm bảo hiệu quả và tuân thủ tiêu chuẩn.

Tài liệu được cải thiện

Các trang API reference giờ đây bao gồm các phần Errorcode được điền đầy đủ ở cuối trang với các mã lỗi mới nhất và mô tả lỗi tương ứng cho từng endpoint.

Ánh xạ API từ phiên bản cũ sang v202309

Với cấu trúc URI yêu cầu mới và các thay đổi về cách đặt tên API trong v202309, nhiều endpoint API cũ đã được thay thế hoặc ngừng hoạt động trong v202309.

Sử dụng các bảng dưới đây để hiểu cách các API cũ ánh xạ sang các endpoint v202309 mới:

Seller (API cũ gọi là Seller hoặc Shop)

Legacy APIs	API v202309
Get Authorized Shop	Get Authorized Shops
Get Active Shop List	Get Active Shops
Check Global Product Mode	Get Seller Permissions

Event (API cũ gọi là Shop)

Legacy APIs	API v202309
Create Webhook	Update Shop Webhook
Get Webhooks	Get Shop Webhooks
Cancel Webhook	Delete Shop Webhook

Product

Legacy APIs	API v202309
Get Brands	Get Brands
Create Brand	Create CustomBrands
Get Attributes	Get Attributes
Get Category Rule	Get Category Rules
Get Categories	Get Categories
Upload File	Upload Product File
Category Recommended	Recommend Category
Upload Image	Upload Product Image
Create Product	Create Product
Edit Product	Edit Product
Update Price	Update Price
Update Stock	Update Inventory
Deactivate Product	Deactivate Products
Activate Product	Activate Product
Delete Product	Delete Products
Recover Deleted Product	Recover Products
Get Product List	Search Products
Create Draft Product	Không nâng cấp ở phiên bản này. Có thể tiếp tục sử dụng phiên bản cũ. Nếu có cập nhật, chúng sẽ được cung cấp ở phiên bản tương lai.
Get Product Stock	Inventory Search
Pre-check for Operating Product	Check Listing Prerequisites
Get Product Detail	Get Product
Get Global Product Detail	Get Global Product
Không tồn tại trước đây	Partial Edit Product

Order

Legacy APIs	API v202309
Get Order List	Get Order List
Get Order Detail	Get Order Detail

Fulfillment

Legacy APIs	API v202309
Search Package	Search Package
Get Package Detail	Get Package Detail
Get Package Shipping Document	Get Package Shipping Document
Get Package Pickup Config	Get Package Handover Time Slots
Get Package Shipping Info	Get Tracking
Update Package Shipping Info	Update Package Shipping Info
Update Package Delivery Status	Update Package Delivery Status
Verify Order Split	Get Order Split Attributes
Confirm Order Split	Split Orders
Search Pre Combine Pkg	Search Combinable Packages
Confirm Precombine Package	Combine Package
Remove Package Order	Uncombine Packages
Ship Package	Sử dụng Mark Package As Shipped hoặc Ship Package tùy thuộc vào vị trí cửa hàng của bạn
Batch Ship Packages	Batch Ship Packages
Fulfillment Upload Image	Fulfillment Upload Delivery Image
Fulfillment Upload File	Fulfillment Upload Delivery File
Get Shipping Service	Get Eligible Shipping Service
Create Label	Create Packages

Logistics

Legacy APIs	API v202309
Get Subscribed Delivery Options	Get Warehouse Delivery Options
Get Warehouse List	Get Warehouse List
Get Shipping Provider	Get Shipping Providers
Get Shipping Document	Không nâng cấp ở phiên bản này.
Khuyến nghị sử dụng Get Package Shipping Document
Get Shipping Info	Get Tracking
Update Shipping Info	Update Shipping Info

Returns, Refunds, Cancellations (API cũ gọi là Reverse)

Legacy APIs (Reverse)	Returns, Refunds, and Cancellations API v202309
Cancel Order	Cancel Order
Get Reverse Order List	Search Cancellation
Search Returns
Confirm Reverse Request	Approve Return
Approve Cancellation
Reject Reverse Request	Reject Return
Reject Cancellation
Get Reject Reason List	Get Reject Reasons
Không tồn tại trước đây	Get Aftersale Eligibility
Không tồn tại trước đây	Create Return
Không tồn tại trước đây	Get Return Records
Không tồn tại trước đây	Calculate Refund

Finance

Legacy APIs	API v202309
Get Settlements	Get Statements
Get Statement Transactions
Get Transactions	Get Withdrawals
Get Order Settlements	Get Order Statement Transactions
Không tồn tại trước đây	Get Payments

Global Product

Legacy APIs	API v202309
Get Global Categories	Get Global Categories
Get Global Category Rule	Get Global Category Rules
Get Global Attributes	Get Global Attributes
Edit Global Product	Edit Global Product
Create Global Product	Create Global Product
Publish Global Product	Publish Global Product
Delete Global Product	Delete Global Products
Update Global Product Price	Không nâng cấp ở phiên bản này.
Khuyến nghị sử dụng Update Price để chỉnh sửa giá sản phẩm đã đăng ở các cửa hàng nội địa, và sử dụng Edit Product để chỉnh sửa giá sản phẩm Global.
Get Global Product List	Search Global Products

Promotion

Legacy APIs	API v202309
Add Promotion	Create Activity
Update Basic Information	Update Activity
Add/Update Discount Item	Update Activity Product
Remove Promotion Item	Remove Activity Product
Deactivate Promotion	Deactivate Activity
Get Promotion List	Search Activities
Get Promotion Details	Get Activity Detail

Supply chain

Legacy APIs	API v202309
Package fulfillment data sync	Confirm Package Shipment

Webhook

Legacy APIs	API v202309
Type 1: Order Status Update	Order Status Update
Type 2: Reverse Status Update	Cancellation Status Change và Return Status Change
Type 3: Recipient Address Update	Recipient Address Update
Type 4: Package Update	Package Update
Type 5: Product Audit Update	Product Status Update
Type 6: Seller Deauthorization	Seller Deauthorization
Type 7: Auth Expire	Upcoming Authorization Expiration