DOCS
Trang chủGiải pháp bưu chính chiều đi Công cụ cho những người gửi hàng Verified Accounts 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 

  1. Tạo một mục danh mục cho mỗi sản phẩm bạn vận chuyển.

  2. Đả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.

  3. 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.

1mutation CatalogItemCreate($input: [CatalogItemInput!]!) {
2 catalogItemCreate(input: $input) {
3 id
4 itemKey
5 name
6 productId
7 sku
8 hsCode
9 customsDescription
10 countryOfOrigin
11 }
12}

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

Trường↕Bắt buộc↕Mô tả↕
skuCó*Đị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.
productIdCó*Đị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.
nameCóTên sản phẩm.
customsDescriptionKhuyế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”.
countryOfOriginKhuyế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.
measurementsKhuyến nghịTrọng lượng và kích thước, dùng để tính cước và khai báo hải quan.
hsCodeKhôngMã 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.
amountKhôngGiá sản phẩm dưới dạng số.
currencyCodeKhôngMã 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.
itemTypeKhôngPHYSICAL_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.
provinceOfOriginKhôngBang 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.
productCompositionKhôngDanh 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.
catalogItemUrlKhôngLiê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.
imageUrlKhôngURL 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.

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ì.

Hãy thêm Product ID hoặc SKU của bạn vào cuối mô tả hải quan mà bạn gửi cho hãng vận chuyển.

Men's bifold wallet, cowhide leather - 123456

Định danh được thêm vào phải khớp chính xác với productId hoặc sku trên mục danh mục tương ứng.

Các trường mô tả khá ngắn. Ví dụ, các bản gửi cho Canada Post chỉ cho phép khoảng 49 ký tự, vì vậy hãy rút ngắn phần mô tả nếu định danh của bạn dài. Định danh quan trọng hơn phần diễn giả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 bị thiếu trong mô tả.
  • Định danh không tương ứng với bất kỳ productId hoặc sku 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.

1mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {
2 catalogItemUpdate(input: $input) {
3 id
4 itemKey
5 hsCode
6 customsDescription
7 }
8}

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.

1query CatalogItem($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.

1mutation CatalogItemDelete($input: [ID!]!) {
2 catalogItemDelete(input: $input)
3}

Liên quan 

  • Tích hợp kênh — Tự động đồng bộ danh mục của bạn từ một kênh bán hàng được hỗ trợ.
  • Nhập CSV — Tải lên các mục danh mục bằng bảng tính thay vì viết mã.
  • Kiểm tra PGA — Sàng lọc các mục danh mục của bạn theo các yêu cầu của cơ quan liên bang Mỹ (PGA).
  • Cách Catalog hoạt động — Zonos làm gì với dữ liệu sản phẩm của bạn.
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

CatalogItemInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemUpdate

Trang này có hữu ích không?

Nhận hỗ trợ·Tài liệu pháp lý·© 2026 Zonos
Trên trang này:
  • Catalog API
  • Cách thức hoạt động
  • Tạo các mục danh mục
  • Giúp các mục của bạn có thể được khớp
  • Cập nhật các mục danh mục
  • Đọc lại các mục của bạn
  • Xóa các mục danh mục
  • Liên quan