Collect•

Trang chủGiải pháp bưu kiện gửi đi Gửi hàng qua dịch vụ bưu điện Zonos và Japan Post Tài khoản được xác thực Tạo nhãn qua API Tạo một lô hàng duy nhất

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

Quy trình CreateDeclarationShipment GraphQL lấy lô hàng Japan Post từ các đầu vào thô để đến nhãn có thể in được trong một lần giao tiếp.

CreateDeclarationShipment kết hợp sáu *Workflow mutations vào 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ả chúng được gửi cùng nhau để có thể tạo một lô hàng hoàn chỉnh trong một lần giao tiếp:

partyCreateWorkflow            → mô tả các bên gốc + đích đến
itemCreateWorkflow             → mô tả các mặt hàng dò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ế / phí / lệ phí
shipmentCreateWorkflow         → tạo lô hàng + nhãn

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

Khi serviceLevel trên bước cuối cùng là 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 — tất cả bên trong bước shipmentCreateWorkflow cuối cùng đó.

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

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

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

URL:

https://api.zonos.com/graphql

Headers:

Bạn vận chuyển các đơn hàng của riêng bạn theo Tài khoản Được xác minh của riêng bạn. Xác thực với tư cách là chính bạn — không cần khóa tài khoản.

credentialToken: {{YOUR_API_TOKEN}}

Nơi tìm thấy: Bảng điều khiển Zonos → Cài đặt → Tích hợp → phần Khóa tài khoản. Sao chép mã thông báo trên hàng Khóa API; đó là credentialToken của bạn.

Yêu cầu ví dụ

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 duy nhất Japan Post được vận chuyển DDP đến Mỹ. Mỗi đầu vào được chia nhỏ trong phần từng bước bên dưới.

1mutation CreateDeclarationShipment(

2$partyInput: [PartyCreateWorkflowInput!]!

3$itemInput: [ItemCreateWorkflowInput!]!

4$cartonInput: [CartonCreateWorkflowInput!]!

5$shipmentRatingInput: ShipmentRatingCreateWorkflowInput!

6$landedCostInput: LandedCostWorkFlowInput!

7$shipmentInput: ShipmentCreateWorkflowInput!

8) {

9 partyCreateWorkflow(input: $partyInput) {

10 id

11 type

12 location {

13 line1

14 locality

15 postalCode

16 countryCode

17 }

18 }

19 itemCreateWorkflow(input: $itemInput) {

20 id

21 name

22 sku

23 amount

24 currencyCode

25 hsCode

26 }

27 cartonsCreateWorkflow(input: $cartonInput) {

28 id

29 length

30 width

31 height

32 dimensionalUnit

33 weight

34 weightUnit

35 }

36 shipmentRatingCreateWorkflow(input: $shipmentRatingInput) {

37 id

38 amount

39 }

40 landedCostCalculateWorkflow(input: $landedCostInput) {

41 id

42 method

43 currencyCode

44 amountSubtotals {

45 duties

46 taxes

47 fees

48 shipping

49 landedCostTotal

50 }

51 }

52 shipmentCreateWorkflow(input: $shipmentInput) {

53 id

54 trackingDetails {

55 number

56 }

57 shipmentCartons {

58 label {

59 url

60 }

61 }

62 }

63}

Từng bước

Cột Status trên mỗi bảng dưới đây sử dụng các thuật ngữ này:

Required — yêu cầu sẽ thất bại mà không nó.
Required for label — tuỳ chọn trong lược đồ GraphQL, nhưng cần thiết để tạo nhãn Japan Post Mỹ hợp lệ.
Conditional — bắt buộc tùy thuộc vào trường khác (lưu ý nội tuyến).
Recommended — tuỳ chọn, nhưng chạy các thuế và lệ phí chính xác.
Optional — không cần.

1. `partyCreateWorkflow`

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

Trường↕	Trạng thái↕	Ghi chú↕
`type`	Required	`ORIGIN`, `DESTINATION`, `RETURN`, v.v.
`location.countryCode`	Required	Mã quốc gia ISO-2.
`location.line1`, `locality`, `administrativeAreaCode`, `postalCode`	Required for label	Các trường địa chỉ cần thiết cho nhãn hợp lệ.
`person.firstName`, `lastName`, `phone`	Required for label	Chi tiết liên hệ cần thiết cho nhãn hợp lệ.
`person.companyName`, `email`	Optional

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 được tạo và các trường địa chỉ được giải quyết.

2. `itemCreateWorkflow`

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

Trường↕	Trạng thái↕	Ghi chú↕
`currencyCode`	Required	Tiền tệ của giá đơn vị.
`quantity`	Required	Số đơn vị của mặt hàng này.
`amount`	Conditional	Giá đơn vị (không phải tổng). Bắt buộc trừ khi `totalAmount` được cung cấp.
`totalAmount`	Optional	Thay thế cho `amount`; `amount` được lấy từ `totalAmount / quantity`.
`hsCode`	Recommended	Mã tariff Hệ thống Hài hòa. Chạy tỷ giá thuế.
`countryOfOrigin`	Recommended	Mã ISO-2 nơi mặt hàng được sản xuất. Chạy thuế / FTA.
`name`, `description`	Recommended	Tên sản phẩm + mô tả dành cho khách hàng.
`customsDescription`	Optional	Ghi đè mô tả hải quan.
`sku`, `productId`	Optional	Các định danh nội bộ của bạn.
`measurements`	Optional	Trọng lượng / kích thước trên mỗi đơn vị.

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ế/lệ phí ở bước 5.

3. `cartonsCreateWorkflow`

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

Trường↕	Trạng thái↕	Ghi chú↕
`dimensionalUnit`	Required	`INCH` hoặc `CENTIMETER`.
`weight`, `weightUnit`	Required for label	Japan Post yêu cầu trọng lượng gói.
`length`, `width`, `height`	Optional	Kích thước ngoài.
`type`	Optional	Kiểu đóng gói (hộp, túi polybag, thư). Mặc định là `PACKAGE`.

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

4. `shipmentRatingCreateWorkflow`

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

Trường↕	Trạng thái↕	Ghi chú↕
`amount`	Required	Người mua đang trả bao nhiêu cho vận chuyển. Chuyển `0` nếu miễn phí.
`currencyCode`	Required	Tiền tệ của `amount`.
`serviceLevelCode`	Required	Mã dịch vụ vận chuyển (ví dụ: `japan_post.air.parcel`).
`displayName`	Optional	Tên xinh đẹp cho biên lai / hóa đơn.

Đây là tỷ giá mà người mua đã được trích dẫn tại thanh toán. Nó cung cấp vào tính toán chi phí đã hạ như tổng "vận chuyển" để thuế và lệ phí được tính toán so với giá trị CIF chính xác.

5. `landedCostCalculateWorkflow`

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

Trường↕	Trạng thái↕	Ghi chú↕
`endUse`	Required	`NOT_FOR_RESALE` hoặc `FOR_RESALE`. Một số đích áp dụng các tỷ giá khác nhau cho sử dụng cuối thương mại so với cá nhân.
`tariffRate`	Required	Mặc định là `ZONOS_PREFERRED` nếu bị bỏ qua. Cho Zonos biết nguồn tariff / phương pháp nào cần áp dụng.
`calculationMethod`	Recommended	`DDP` (người mua thanh toán trước) hoặc `DDU` (người mua thanh toán tại cửa). Sử dụng `DDP` cho thanh toán trước. Chạy liệu `LandedCost.amountSubtotals` bao gồm thuế/lệ phí.
`currencyCode`	Optional	Tiền tệ mà các tổng chi phí đã hạ được trả lại.
`arrivalDate`	Optional	Tỷ giá FX và lịch tariff được ghim vào ngày này nếu được cung cấp.

Phản hồi bao gồm amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — đây là những con số bạn hiển thị cho người mua tại 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 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 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, tiêm Later Pay Numbers của bạn, tạo ID Khai báo và liên kết ID Khai báo đến số theo dõi được trả lại bởi Japan Post.

Các trường chính:

Trường↕	Trạng thái↕	Ghi chú↕
`serviceLevel`	Required for label	Dịch vụ Japan Post để vận chuyển (ví dụ: `japan_post.air.ems_merchandise`). Phải là mức dịch vụ `japan_post.*`.
`generateLabel`	Optional	Mặc định là `true`; phải là `true` để trả lại nhãn.
`contentsType`	Recommended	`SALE_OF_GOODS`, `GIFT`, `DOCUMENTS`, `SAMPLE`, v.v. Chạy xử lý hải quan.
`nonDelivery`	Optional	Vận chuyển nên làm gì nếu giao hàng không thành công: `RETURN`, `ABANDON`, `FORWARD`.
`references`	Optional	Số tham chiếu do thương nhân cung cấp được in trên nhãn và hóa đơn thương mại. Xem bên dưới.
`declaredValue` / `isDeclaredValue`	Optional	Giá trị bảo hiểm cho lô hàng.
`shipmentConsolidationId`	Optional	Được sử dụng khi lô hàng này là một phần của phân phối theo lô.

`references` Đầu vào phụ

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. Sử dụng chúng để hiển thị số PO, số cấp phép và ghi chú văn bản tự do mà người nhận hàng hoặc cơ quan hải quan cần xem.

Trường↕	Trạng thái↕	Ghi chú↕	Độ dài↕
`invoiceNumber`	Optional	Số hóa đơn thương nhân.	—
`purchaseOrderNumber`	Optional	Số PO thương nhân.	—
`licenseNumber`	Optional	Số cấp phép xuất khẩu/nhập khẩu.	—
`certificateNumber`	Optional	Số chứng chỉ hải quan.	—
`paymentConditions`	Optional	Điều khoản thanh toán văn bản tự do được hiển thị trên hóa đơn thương mại.	Giới hạn 200 ký tự — các giá trị dài hơn sẽ tràn trên hóa đơn in.
`customsRemarks`	Optional	Ghi chú hải quan văn bản tự do.	—
`taxCode`	Optional	Mã thuế tùy chỉnh được in trên nhãn.	—

Phản hồi

Các trường thú vị trên Shipment được trả lại là:

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

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

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

Trường↕	Trả lại↕	Sử dụng khi↕
`url`	Liên kết được lưu trữ đến tệp nhãn được kết xuất (PDF), sẵn sàng để tải xuống hoặc in.	Bạn muốn trao liên kết — mở nó, gửi email hoặc tìm nạp tệp sau mà không giữ nó trong tải trọng.
`labelImage`	Hình ảnh nhãn được mã hóa base64 (PNG/PDF/ZPL) nội tuyến trong phản hồi.	Bạn muốn các byte nhãn trực tiếp trong phản hồi để đính kèm vào quy trình làm việc hoàn thành hoặc lưu vào WMS của bạn.

Chỉ chọn các trường bạn cần. Yêu cầu url giữ phản hồi nhỏ; yêu cầu labelImage trả lại nhãn đầy đủ nội tuyến để bạn không cần vòng giao tiếp thứ hai để tìm nạp nó. Ví dụ trên yêu cầu url.

Xử lý lỗi

Lỗi xác thực (trường bắt buộc bị thiếu, mã quốc gia không hợp lệ, v.v.) quay lại trong errors mảng GraphQL tiêu chuẩn 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ệ với hỗ trợ — con đường được khuyến nghị là gửi lại toàn bộ mutation với đầu vào được sửa.

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 Tài khoản Được xác minh cấp tất cả những điều này.

Bước tiếp theo

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

GraphQL API ReferenceTypes, inputs, and operations used in this guide

INPUTS

CartonCreateWorkflowInput ItemCreateWorkflowInput LandedCostWorkFlowInput PartyCreateWorkflowInput ShipmentCreateWorkflowInput ShipmentRatingCreateWorkflowInput

MUTATIONS

cartonsCreateWorkflow itemCreateWorkflow landedCostCalculateWorkflow partyCreateWorkflow shipmentCreateWorkflow shipmentRatingCreateWorkflow

Đặt lịch demo

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

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

Yêu cầu ví dụ

Từng bước

1. partyCreateWorkflow

2. itemCreateWorkflow

3. cartonsCreateWorkflow

4. shipmentRatingCreateWorkflow

5. landedCostCalculateWorkflow

6. shipmentCreateWorkflow

references Đầu vào phụ