Tạo một lô hàng duy nhất

CreateDeclarationShipment kết hợp sáu mutation *Workflow thành một yêu cầu GraphQL duy nhất. Mỗi bước dựa trên dữ liệu mà các bước trước đó cung cấp, và tất cả được gửi cùng nhau để có thể tạo một lô hàng hoàn chỉnh trong một lượt gửi:

partyCreateWorkflow            → mô tả các bên gốc + đích đến
itemCreateWorkflow             → mô tả các mặt hàng
cartonsCreateWorkflow          → mô tả gói vật lý
shipmentRatingCreateWorkflow   → ghi lại báo giá tỷ giá vận chuyển
landedCostCalculateWorkflow    → tính toán thuế nhập khẩu / thuế / lệ phí
shipmentCreateWorkflow         → tạo lô hàng + nhãn

Các mutation Workflow được thiết kế để kết hợp lại: bạn không cần chuyển ID từ bước này sang bước tiếp theo, và bạn không cần gửi một yêu cầu riêng cho mỗi bước. Gửi toàn bộ tài liệu, nhận lại Shipment cuối cùng.

Khi serviceLevel ở bước cuối cùng là một mức dịch vụ Japan Post (japan_post.*), Zonos gọi API Nhãn Japan Post (mã 52) thay mặt bạn bằng cách sử dụng Later Pay Numbers của Tài khoản Được xác minh của bạn, tạo nhãn và số theo dõi, tạo ID Khai báo và liên kết chúng với nhau — tất cả bên trong bước shipmentCreateWorkflow cuối cùng đó.

Vì sao chỉ một mutation? Mỗi bước phụ thuộc vào bước trước (chi phí đã hạ cánh cần các mặt hàng + các bên; nhãn cần mọi thứ). Gói tất cả vào một tài liệu GraphQL duy nhất giữ dữ liệu nhất quán và tránh được năm lượt gửi bổ sung.

Điểm cuối và xác thực 

Các yêu cầu trong chuỗi này đều dùng cùng một điểm cuối. Những gì bạn truyền vào tiêu đề tùy thuộc vào cách thiết lập của bạn — hãy chọn tab phù hợp.

URL:

https://api.zonos.com/graphql

Tiêu đề:

credentialToken: {{YOUR_API_TOKEN}}

Yêu cầu ví dụ 

Một yêu cầu CreateDeclarationShipment hoàn chỉnh mà bạn có thể sao chép và điều chỉnh — mutation, các biến của nó và phản hồi — cho một gói Japan Post duy nhất vận chuyển DDP đến Mỹ. Mỗi đầu vào được trình bày chi tiết trong phần từng bước dưới đây.

Từng bước 

Cột Trạng thái trên mỗi bảng dưới đây dùng các thuật ngữ này:

• Bắt buộc — yêu cầu sẽ thất bại nếu không có nó.
• Bắt buộc để tạo nhãn — tùy chọn trong lược đồ GraphQL, nhưng cần thiết để tạo ra một nhãn Japan Post hợp lệ cho Mỹ.
• Có điều kiện — bắt buộc tùy vào một trường khác (được ghi chú ngay trong bảng).
• Khuyến nghị — tùy chọn, nhưng ảnh hưởng đến độ chính xác của thuế nhập khẩu và thuế.
• Tùy chọn — không cần thiết.

1. partyCreateWorkflow

Tạo các bên liên quan đến lô hàng — tối thiểu là một ORIGIN (nơi lô hàng được gửi đi) và một DESTINATION (người mua / người nhận).

Ví dụ tải trọng:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

Phản hồi trả về các ID Party đã tạo và các trường địa chỉ đã được giải quyết.

2. itemCreateWorkflow

Tạo các mặt hàng cấu thành lô hàng. Đây là các SKU sẽ xuất hiện trên hóa đơn thương mại và ảnh hưởng đến việc tính toán chi phí đã hạ cánh.

Mã HS, quốc gia xuất xứ và số tiền là ba trường ảnh hưởng nhiều nhất đến kết quả thuế nhập khẩu / thuế ở bước 5.

3. cartonsCreateWorkflow

Tạo các gói vật lý — hộp, túi polybag hoặc thư sẽ chứa các mặt hàng.

Mỗi carton trở thành một kiện hàng trên nhãn vận chuyển ở bước 6. Nhiều carton → lô hàng nhiều kiện với một số theo dõi cho mỗi carton.

4. shipmentRatingCreateWorkflow

Ghi lại báo giá tỷ giá mà thương nhân đang tính phí người mua để vận chuyển.

Đây là mức giá mà người mua đã được báo tại lúc thanh toán. Nó được đưa vào tính toán chi phí đã hạ cánh dưới dạng tổng phụ "shipping" để thuế nhập khẩu và thuế được tính dựa trên giá trị CIF chính xác.

5. landedCostCalculateWorkflow

Chạy phần tính toán thuế nhập khẩu, thuế và lệ phí cho quốc gia đích. Sử dụng các mặt hàng, các bên và chi phí vận chuyển từ các bước trước.

Phản hồi bao gồm amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — đây là các số bạn hiển thị cho người mua tại lúc thanh toán và được in trên hóa đơn thương mại.

6. shipmentCreateWorkflow

Bước cuối cùng — tạo thực thể Shipment, tạo ra nhãn vận chuyển và (tùy chọn) hóa đơn thương mại / phiếu đóng gói.

Đối với các Tài khoản Được xác minh Japan Post, đây cũng là nơi Zonos gọi API Nhãn Japan Post (mã 52) thay mặt bạn, chèn Later Pay Numbers của bạn, tạo ID Khai báo và liên kết ID Khai báo với số theo dõi mà Japan Post trả về.

Các trường chính:

Về contentsType, hai giá trị phổ biến nhất đối với lưu lượng Tài khoản Được xác minh là ECOMMERCE_GOODS (bán cho người tiêu dùng, BtoC) và COMMERCIAL_GOODS (bán giữa các doanh nghiệp, BtoB). Các giá trị này thiết lập pkgType mà Zonos gửi trong lệnh gọi nhãn Japan Post, vì vậy lựa chọn này thay đổi những gì được in trên tờ khai hải quan — không chỉ đơn thuần là nhãn.

Đầu vào phụ nonDelivery

Cho Japan Post biết cần làm gì với gói hàng nếu không thể giao được — bị người nhận từ chối, bị chặn ở biên giới, hoặc không thể giao theo địa chỉ đã ghi.

option chỉ nhận đúng bốn giá trị này. Không có giá trị RETURN — dùng RETURN_AFTER_RETENTION hoặc RETURN_IMMEDIATELY để chọn thời điểm gói hàng được trả lại.

API hiển thị riêng biệt cả hai biến thể trả hàng; tùy chọn Return trên Bảng điều khiển bao gồm cả hai.

transportMethod nhận giá trị AIR hoặc MOST_ECONOMICAL, quy định cách một gói hàng bị trả lại được vận chuyển về. Trường này chỉ áp dụng cho hai tùy chọn RETURN_* — Bảng điều khiển chỉ hiển thị trường Return method tương ứng khi Return được chọn.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

Bộ chọn If undeliverable trong hộp thoại Create label trên Bảng điều khiển ghi vào chính trường này, vì vậy một nhãn được tạo trên Bảng điều khiển và một nhãn được tạo qua API sẽ hoạt động giống nhau.

Đầu vào phụ references

Các trường này in trên nhãn vận chuyển và/hoặc hóa đơn thương mại. Dùng chúng để hiển thị số PO, số giấy phép và các ghi chú tự do mà người nhận hoặc cơ quan hải quan cần thấy.

Phản hồi

Các trường đáng chú ý trên Shipment được trả về là:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number là số theo dõi của Japan Post.

Đối tượng label có thể trả về nhãn theo hai cách — yêu cầu bất kỳ cách nào phù hợp với quy trình của bạn (hoặc cả hai):

Chỉ chọn những trường bạn cần. Yêu cầu url giữ cho phản hồi gọn nhẹ; yêu cầu labelImage trả về toàn bộ nhãn ngay trong phản hồi để bạn không cần một lượt gửi thứ hai để lấy tệp. Ví dụ ở trên yêu cầu url.

Mức dịch vụ Japan Post 

Truyền một trong các mã này làm serviceLevelCode trong shipmentRatingCreateWorkflow.

Mã mức dịch vụ dùng dấu chấm, không dùng gạch dưới. Bạn có thể thấy dạng gạch dưới (japan_post_air_parcel) trong thông báo lỗi và các tài liệu tham khảo nội bộ, nhưng đó không phải là đầu vào hợp lệ.

Dịch vụ đường hàng không

Dịch vụ đường biển

Chọn giữa các dịch vụ tương tự

Gói nhỏ so với International Air Packet. Cả hai đều giới hạn ở 2 kg. japan_post.air.packet là dịch vụ gói nhỏ có theo dõi của Japan Post. japan_post.air.small_packet là dịch vụ tương đương nhưng không có theo dõi. Nếu bạn cần theo dõi cho một gói hàng nhẹ, hãy dùng japan_post.air.packet.

Các biến thể có đăng ký. Đối với thư và ấn phẩm, khả năng theo dõi được thêm vào bởi phiên bản có đăng ký (書留) của dịch vụ. japan_post.air.printed_matter và japan_post.air.letter không có sẵn khả năng này khi dùng riêng.

Mã đã ngừng dùng

japan_post.air.epacket_light trước đây là International e-Packet Light. Japan Post đã đổi tên dịch vụ này thành International Air Packet vào ngày 1 tháng 6 năm 2026, và mở rộng dịch vụ này ra tất cả các quốc gia và khu vực. Dịch vụ này không có gì thay đổi.

Mã cũ vẫn còn hoạt động để các tích hợp hiện có tiếp tục vận hành bình thường, nhưng hãy dùng japan_post.air.packet cho công việc mới.

Mã chế độ vận chuyển

japan_post.air, japan_post.surface, japan_post.economy_air và japan_post.custom cũng hoạt động, nhưng chúng xác định một chế độ vận chuyển hoặc một giá trị dự phòng chứ không phải một sản phẩm thư cụ thể. Hãy dùng một trong các mã dịch vụ trên cho các lô hàng thông thường.

Xác thực mã bạn gửi

Một serviceLevelCode không được nhận diện không gây ra lỗi. Yêu cầu trả về HTTP 200 không có mảng errors, serviceLevel trả về null, và phần vận chuyển bị loại khỏi tổng chi phí đã hạ cánh — vì vậy phản hồi trông có vẻ đúng trong khi số tiền lại sai.

Luôn xác nhận rằng shipmentRatingCreateWorkflow.serviceLevel không phải là null trước khi dựa vào các tổng số này.

Để lấy danh sách hiện tại bất kỳ lúc nào:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Truy vấn này nhận ID của hãng vận chuyển. Truyền mã hãng vận chuyển japan_post sẽ trả về danh sách trống mà không có lỗi.

Xử lý lỗi 

• Lỗi xác thực (thiếu trường bắt buộc, mã quốc gia không hợp lệ, v.v.) trả về trong mảng errors chuẩn của GraphQL và hủy phần còn lại của chuỗi.
• Lỗi Japan Post (lỗi tạo nhãn, địa chỉ không hợp lệ, v.v.) xuất hiện dưới dạng lỗi GraphQL trên shipmentCreateWorkflow. Nếu cần thử lại, hãy liên hệ hỗ trợ — cách được khuyến nghị là gửi lại toàn bộ mutation với đầu vào đã được sửa.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Lỗi này nêu tên toàn bộ biến, không phải trường thực sự bị sai. Nó hầu như luôn có nghĩa là một giá trị enum bên trong biến đó không thuộc enum của nó — thường gặp nhất là nonDelivery.option, contentsType hoặc serviceLevel.

Đây không phải là vấn đề về kiểu dữ liệu JSON. Việc thêm hoặc bỏ dấu ngoặc kép cho các giá trị boolean và số sẽ không làm thay đổi kết quả, vì tải trọng chưa từng đi xa đến mức đó — enum đã bị từ chối trước.

Để tìm trường bị sai, hãy kiểm tra từng trường có giá trị enum trong biến đó với các giá trị được chấp nhận của nó:

Danh sách đầy đủ các thành viên enum cho bất kỳ đầu vào nào được liệt kê trên trang kiểu dữ liệu của nó trong tài liệu tham khảo API.

Quyền 

Mỗi bước được bảo mật độc lập. Khóa API của bạn phải giữ quyền ghi cho mỗi thực thể trong chuỗi (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Vai trò thương nhân tiêu chuẩn trên một Tài khoản Được xác minh cấp đầy đủ tất cả các quyền này.

Bước tiếp theo 

• Phân phối theo lô (hợp nhất) — gói các gói hàng của cả ngày vào một phiếu phân phối hoãn thanh toán của Japan Post.