Xây dựng danh mục Tài khoản Verified của bạn theo phương thức lập trình, trực tiếp từ hệ thống của riêng bạn.
Catalog API là một trong ba cách để xây dựng danh mục Tài khoản Verified của bạn, và đây là lựa chọn dành cho các nhà vận chuyển có nguồn lực phát triển và một hệ thống đã lưu giữ dữ liệu sản phẩm của họ—ERP, WMS, PIM hoặc nền tảng vận chuyển. Hệ thống đó vẫn là nguồn dữ liệu gốc và ghi sản phẩm trực tiếp vào Zonos, thay vì đồng bộ từ tích hợp kênh hoặc tải lên tệp CSV. Nếu bạn bán hàng qua một kênh được hỗ trợ, hoặc bạn không muốn viết mã, hai lựa chọn đó sẽ xây dựng cùng một danh mục với ít công sức hơn.
Các mục được tạo qua API được xử lý hoàn toàn giống như các mục từ bất kỳ nguồn nào khác—khi một mục đã nằm trong danh mục của bạn, Zonos không quan tâm nó được đưa vào bằng cách nào. Mỗi mục sẽ được phân loại hải quan nếu bạn chưa cung cấp mã HS, được sàng lọc theo các yêu cầu của Cơ quan Chính phủ Đối tác (PGA) Hoa Kỳ, và được dùng để tính thuế nhập khẩu và thuế cho các lô hàng có chứa mục đó.
Có một phần của quy trình này nằm ngoài API. Khi sàng lọc PGA đánh dấu một mục là Needs attention, bảng câu hỏi tuân thủ đằng sau cảnh báo đó phải được trả lời và xác nhận trong Dashboard—không có API cho việc này, và Zonos điền trước những gì có thể nên phần lớn công việc chỉ là xem xét và xác nhận. Người xây dựng tích hợp này thường không phải là người xử lý các cảnh báo đó, vì vậy hãy lên kế hoạch để một người trong tổ chức của bạn xử lý chúng trong Dashboard sau khi danh mục của bạn được tải lên. Các mục bị đánh dấu không bị chặn vận chuyển, nhưng việc xử lý chúng trước khi vận chuyển là điều giúp lô hàng không bị giữ lại tại biên giới Hoa Kỳ.
Tạo một mục danh mục cho mỗi sản phẩm bạn vận chuyển.
Đảm bảo mỗi mục mang một định danh mà hãng vận chuyển bưu chính của bạn sẽ chuyển tiếp.
Khi dữ liệu lô hàng của bạn đến Zonos, mỗi dòng sẽ được khớp trở lại với mục danh mục của bạn và dữ liệu sản phẩm của mục đó được áp dụng vào phép tính.
Tạo các mục danh mục
catalogItemCreate chấp nhận một danh sách, vì vậy bạn có thể gửi nhiều sản phẩm trong một yêu cầu duy nhất.
Nếu bạn gửi một sản phẩm có SKU hoặc Product ID đã tồn tại, Zonos sẽ cập nhật sản phẩm đó thay vì thêm một sản phẩm thứ hai. Việc thử lại và chạy lặp lại đều an toàn.
Mặt trái là hai sản phẩm khác nhau dùng chung một SKU hoặc Product ID sẽ bị hợp nhất thành một. Hãy kiểm tra dữ liệu của bạn để tìm các mục trùng lặp trước khi tải hàng loạt.
Định danh duy nhất của bạn cho sản phẩm. *Mỗi sản phẩm cần có SKU hoặc Product ID, hoặc cả hai.
productId
Có*
Định danh của nền tảng của bạn cho sản phẩm. *Mỗi sản phẩm cần có SKU hoặc Product ID, hoặc cả hai.
manufacturerProductId
Chỉ EU
Định danh sản phẩm của nhà sản xuất không theo chuẩn (NS-PID). Bắt buộc đối với lô hàng B2C đến EU có giá trị từ 150 EUR trở xuống.
gtin
Chỉ EU
Định danh sản phẩm của nhà sản xuất theo chuẩn (S-PID), chỉ gồm chữ số. Bắt buộc đối với lô hàng B2C đến EU có giá trị từ 150 EUR trở xuống, nếu sản phẩm có mã vạch.
name
Có
Tên sản phẩm.
customsDescription
Khuyến nghị
Sản phẩm là gì, bằng ngôn ngữ đơn giản, dùng cho tờ khai hải quan. Hãy dùng “Cotton t-shirt”, không phải “Summer Vibes Tee”.
countryOfOrigin
Khuyến nghị
Mã ISO gồm 2 chữ cái của nơi sản xuất sản phẩm. Cần thiết để tính thuế nhập khẩu chính xác.
measurements
Khuyến nghị
Trọng lượng và kích thước, dùng để tính cước và khai báo hải quan.
hsCode
Không
Mã HS 6 chữ số chung toàn cầu. Nếu bạn bỏ trống, Zonos sẽ phân loại sản phẩm dựa trên tên và mô tả của sản phẩm.
amount
Không
Giá sản phẩm dưới dạng số.
currencyCode
Không
Mã ISO gồm 3 chữ cái của đơn vị tiền tệ của giá. Bắt buộc khi bạn cung cấp amount.
itemType
Không
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE hoặc PARTIAL_ITEM. Giúp các mục không phải hàng hóa vật lý không bị khai báo là hàng hóa thương mại.
provinceOfOrigin
Không
Bang hoặc tỉnh nơi sản phẩm có xuất xứ. Một số quốc gia đích yêu cầu trường này.
productComposition
Không
Danh sách {material, percentage}. Hàng dệt may không thể được phân loại vượt quá 6 chữ số nếu thiếu trường này.
catalogItemUrl
Không
Liên kết đến trang sản phẩm trên trang web của bạn. Giúp cải thiện độ chính xác của việc phân loại.
imageUrl
Không
URL có thể truy cập công khai của hình ảnh sản phẩm. Giúp cải thiện độ chính xác của việc phân loại.
Thêm định danh sản phẩm EU (PID)
Nếu bạn vận chuyển đến EU bằng Tài khoản Verified của mình, kể từ ngày 1 tháng 11 năm 2026, EU yêu cầu định danh sản phẩm (PID) trên các lô hàng từ doanh nghiệp đến người tiêu dùng (B2C) có giá trị từ 150 EUR trở xuống. Hãy lưu các định danh này trên các mục danh mục của bạn. Với hầu hết Tài khoản Verified, bưu chính của bạn gửi dữ liệu lô hàng cho Zonos, và Zonos khớp từng mặt hàng trong lô hàng với danh mục của bạn rồi áp dụng các định danh bạn đã lưu, vì vậy bạn không cần gửi thêm gì vào thời điểm vận chuyển.
Định danh↕
Ý nghĩa↕
Trường API↕
Bắt buộc?↕
Định danh sản phẩm của người bán (M-PID)
SKU hoặc mã mặt hàng của bạn
sku
Luôn luôn
Định danh sản phẩm của nhà sản xuất không theo chuẩn (NS-PID)
Số model hoặc mã linh kiện của nhà sản xuất. Nếu bạn tự sản xuất sản phẩm, hãy dùng số model hoặc mã linh kiện của chính bạn.
manufacturerProductId
Luôn luôn
Định danh sản phẩm của nhà sản xuất theo chuẩn (S-PID)
Mã vạch (UPC, EAN hoặc ISBN)
gtin
Chỉ khi sản phẩm có mã vạch
Gửi các định danh cùng với catalogItemCreate cho sản phẩm mới. Đối với các sản phẩm đã có trong danh mục, hãy gửi chúng bằng catalogItemUpdate, vốn nhận cùng các trường. Hãy khớp sku của từng mặt hàng với SKU bạn dùng ở mọi nơi khác để Zonos có thể liên kết hai bên.
Gửi gtin chỉ gồm chữ số, không có dấu gạch ngang hoặc khoảng trắng. Các giá trị UPC, EAN, JAN và ISBN 13 chữ số đều được nhập vào cùng một trường này. Nếu bạn có ISBN 10 chữ số, hãy gửi phiên bản 13 chữ số thay thế.
Nếu sản phẩm không có mã vạch, hãy bỏ qua gtin thay vì gửi chuỗi rỗng, dùng lại SKU của bạn hoặc điền văn bản giữ chỗ như N/A.
Zonos liên kết mỗi dòng lô hàng trở lại một mục danh mục bằng các định danh của bạn, theo thứ tự sau: Product ID, sau đó là SKU, rồi đến tên. Hãy giữ cho bất kỳ định danh nào bạn sử dụng luôn chính xác và nhất quán giữa danh mục của bạn và dữ liệu bạn gửi cho hãng vận chuyển.
Các lô hàng bưu chính còn có thêm một ràng buộc. Zonos nhận được một tập trường giới hạn từ các hãng vận chuyển bưu chính, và trên nhiều tuyến, mô tả hải quan là trường duy nhất mang thông tin cụ thể về sản phẩm. Một mô tả giống hệt nhau trên toàn bộ danh mục của bạn tự nó không thể nhận diện được bất cứ thứ gì.
Cách định dạng định danh trong dữ liệu lô hàng bạn gửi cho hãng vận chuyển phụ thuộc vào bưu chính của bạn, vì mỗi bưu chính khớp lô hàng với danh mục của bạn theo cách khác nhau. Hãy truy cập tất cả bưu chính và chọn bưu chính của bạn. Trang của bưu chính đó cho biết cách việc khớp hoạt động và chính xác những gì cần gửi.
Việc đặt customsDescription của mục thành cùng chuỗi mà bạn gửi cho hãng vận chuyển là không bắt buộc, nhưng điều này giúp hai bên có thể so sánh trực tiếp khi một dòng không khớp và bạn cần tìm ra nguyên nhân.
Việc khớp thường thất bại khi:
Định danh mà bưu chính của bạn dùng để khớp bị thiếu trong dữ liệu lô hàng.
Định danh không khớp chính xác với bất kỳ mục nào trong danh mục của bạn.
Định danh bị cắt ngắn do giới hạn ký tự của hãng vận chuyển.
Định dạng thay đổi giữa các lô hàng.
Hành vi này vẫn đang được hoàn thiện và có thể thay đổi trước khi ra mắt.
Cập nhật các mục danh mục
catalogItemUpdate nhận cùng kiểu đầu vào như khi tạo. Chỉ gửi những trường bạn muốn thay đổi.
Lưu ý: Các trường bị bỏ qua sẽ được giữ nguyên, giúp việc cập nhật một phần trở nên an toàn. Gửi null không xóa giá trị mà sẽ bị bỏ qua. Bạn có thể ghi đè một giá trị bằng một giá trị khác, nhưng không thể làm trống giá trị đó thông qua API. Hãy liên hệ với đại diện Zonos của bạn nếu bạn cần xóa một trường.
Đọc lại các mục của bạn
Truy vấn catalogItem chấp nhận id, productId hoặc sku. Hãy dùng truy vấn này để xác nhận dữ liệu mà Zonos đang lưu giữ cho một sản phẩm.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Xóa các mục danh mục
catalogItemDelete nhận ID mục danh mục của Zonos, không phải SKU hoặc Product ID của bạn. Hãy xác định ID bằng truy vấn catalogItem trước.
Catalog API
Catalog API
Xây dựng danh mục Tài khoản Verified của bạn theo phương thức lập trình, trực tiếp từ hệ thống của riêng bạn.
Catalog API là một trong ba cách để xây dựng danh mục Tài khoản Verified của bạn, và đây là lựa chọn dành cho các nhà vận chuyển có nguồn lực phát triển và một hệ thống đã lưu giữ dữ liệu sản phẩm của họ—ERP, WMS, PIM hoặc nền tảng vận chuyển. Hệ thống đó vẫn là nguồn dữ liệu gốc và ghi sản phẩm trực tiếp vào Zonos, thay vì đồng bộ từ tích hợp kênh hoặc tải lên tệp CSV. Nếu bạn bán hàng qua một kênh được hỗ trợ, hoặc bạn không muốn viết mã, hai lựa chọn đó sẽ xây dựng cùng một danh mục với ít công sức hơn.
Các mục được tạo qua API được xử lý hoàn toàn giống như các mục từ bất kỳ nguồn nào khác—khi một mục đã nằm trong danh mục của bạn, Zonos không quan tâm nó được đưa vào bằng cách nào. Mỗi mục sẽ được phân loại hải quan nếu bạn chưa cung cấp mã HS, được sàng lọc theo các yêu cầu của Cơ quan Chính phủ Đối tác (PGA) Hoa Kỳ, và được dùng để tính thuế nhập khẩu và thuế cho các lô hàng có chứa mục đó.
Có một phần của quy trình này nằm ngoài API. Khi sàng lọc PGA đánh dấu một mục là Needs attention, bảng câu hỏi tuân thủ đằng sau cảnh báo đó phải được trả lời và xác nhận trong Dashboard—không có API cho việc này, và Zonos điền trước những gì có thể nên phần lớn công việc chỉ là xem xét và xác nhận. Người xây dựng tích hợp này thường không phải là người xử lý các cảnh báo đó, vì vậy hãy lên kế hoạch để một người trong tổ chức của bạn xử lý chúng trong Dashboard sau khi danh mục của bạn được tải lên. Các mục bị đánh dấu không bị chặn vận chuyển, nhưng việc xử lý chúng trước khi vận chuyển là điều giúp lô hàng không bị giữ lại tại biên giới Hoa Kỳ.
Cách thức hoạt động
Tạo một mục danh mục cho mỗi sản phẩm bạn vận chuyển.
Đảm bảo mỗi mục mang một định danh mà hãng vận chuyển bưu chính của bạn sẽ chuyển tiếp.
Khi dữ liệu lô hàng của bạn đến Zonos, mỗi dòng sẽ được khớp trở lại với mục danh mục của bạn và dữ liệu sản phẩm của mục đó được áp dụng vào phép tính.
Tạo các mục danh mục
catalogItemCreatechấp nhận một danh sách, vì vậy bạn có thể gửi nhiều sản phẩm trong một yêu cầu duy nhất.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Gửi cùng một sản phẩm hai lần
Nếu bạn gửi một sản phẩm có SKU hoặc Product ID đã tồn tại, Zonos sẽ cập nhật sản phẩm đó thay vì thêm một sản phẩm thứ hai. Việc thử lại và chạy lặp lại đều an toàn.
Mặt trái là hai sản phẩm khác nhau dùng chung một SKU hoặc Product ID sẽ bị hợp nhất thành một. Hãy kiểm tra dữ liệu của bạn để tìm các mục trùng lặp trước khi tải hàng loạt.
Các trường
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEhoặcPARTIAL_ITEM. Giúp các mục không phải hàng hóa vật lý không bị khai báo là hàng hóa thương mại.provinceOfOriginproductComposition{material, percentage}. Hàng dệt may không thể được phân loại vượt quá 6 chữ số nếu thiếu trường này.catalogItemUrlimageUrlThêm định danh sản phẩm EU (PID)
Nếu bạn vận chuyển đến EU bằng Tài khoản Verified của mình, kể từ ngày 1 tháng 11 năm 2026, EU yêu cầu định danh sản phẩm (PID) trên các lô hàng từ doanh nghiệp đến người tiêu dùng (B2C) có giá trị từ 150 EUR trở xuống. Hãy lưu các định danh này trên các mục danh mục của bạn. Với hầu hết Tài khoản Verified, bưu chính của bạn gửi dữ liệu lô hàng cho Zonos, và Zonos khớp từng mặt hàng trong lô hàng với danh mục của bạn rồi áp dụng các định danh bạn đã lưu, vì vậy bạn không cần gửi thêm gì vào thời điểm vận chuyển.
skumanufacturerProductIdgtinGửi các định danh cùng với
catalogItemCreatecho sản phẩm mới. Đối với các sản phẩm đã có trong danh mục, hãy gửi chúng bằngcatalogItemUpdate, vốn nhận cùng các trường. Hãy khớpskucủa từng mặt hàng với SKU bạn dùng ở mọi nơi khác để Zonos có thể liên kết hai bên.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}Gửi
gtinchỉ gồm chữ số, không có dấu gạch ngang hoặc khoảng trắng. Các giá trị UPC, EAN, JAN và ISBN 13 chữ số đều được nhập vào cùng một trường này. Nếu bạn có ISBN 10 chữ số, hãy gửi phiên bản 13 chữ số thay thế.Nếu sản phẩm không có mã vạch, hãy bỏ qua
gtinthay vì gửi chuỗi rỗng, dùng lại SKU của bạn hoặc điền văn bản giữ chỗ nhưN/A.Nếu bạn tự gọi Landed Cost API, bạn cũng có thể đưa các định danh này vào yêu cầu landed cost của mình. Hầu hết Tài khoản Verified không làm vậy, vì bưu chính mới là bên gửi dữ liệu lô hàng cho Zonos.
Để biết quy định yêu cầu những gì, hãy xem hướng dẫn về định danh sản phẩm EU.
Giúp các mục của bạn có thể được khớp
Zonos liên kết mỗi dòng lô hàng trở lại một mục danh mục bằng các định danh của bạn, theo thứ tự sau: Product ID, sau đó là SKU, rồi đến tên. Hãy giữ cho bất kỳ định danh nào bạn sử dụng luôn chính xác và nhất quán giữa danh mục của bạn và dữ liệu bạn gửi cho hãng vận chuyển.
Các lô hàng bưu chính còn có thêm một ràng buộc. Zonos nhận được một tập trường giới hạn từ các hãng vận chuyển bưu chính, và trên nhiều tuyến, mô tả hải quan là trường duy nhất mang thông tin cụ thể về sản phẩm. Một mô tả giống hệt nhau trên toàn bộ danh mục của bạn tự nó không thể nhận diện được bất cứ thứ gì.
Cách định dạng định danh trong dữ liệu lô hàng bạn gửi cho hãng vận chuyển phụ thuộc vào bưu chính của bạn, vì mỗi bưu chính khớp lô hàng với danh mục của bạn theo cách khác nhau. Hãy truy cập tất cả bưu chính và chọn bưu chính của bạn. Trang của bưu chính đó cho biết cách việc khớp hoạt động và chính xác những gì cần gửi.
Việc đặt
customsDescriptioncủa mục thành cùng chuỗi mà bạn gửi cho hãng vận chuyển là không bắt buộc, nhưng điều này giúp hai bên có thể so sánh trực tiếp khi một dòng không khớp và bạn cần tìm ra nguyên nhân.Việc khớp thường thất bại khi:
Cập nhật các mục danh mục
catalogItemUpdatenhận cùng kiểu đầu vào như khi tạo. Chỉ gửi những trường bạn muốn thay đổi.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Đọc lại các mục của bạn
Truy vấn
catalogItemchấp nhậnid,productIdhoặcsku. Hãy dùng truy vấn này để xác nhận dữ liệu mà Zonos đang lưu giữ cho một sản phẩm.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Xóa các mục danh mục
catalogItemDeletenhận ID mục danh mục của Zonos, không phải SKU hoặc Product ID của bạn. Hãy xác định ID bằng truy vấncatalogItemtrước.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Liên quan
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Trang này có hữu ích không?