DOCS

建立單筆出貨

Collect•
首頁郵件出口解決方案 透過郵局寄送 Zonos 和日本郵政 認證帳戶 透過 API 建立標籤 建立單筆出貨

建立單筆出貨

CreateDeclarationShipment GraphQL 工作流程可在單次往返中將日本郵便出貨從原始輸入轉換為可列印的標籤。

CreateDeclarationShipment 將六個 *Workflow 變動鏈結為單一 GraphQL 請求。每個步驟以前一個步驟所提供的資料為基礎，所有步驟一起提交，這樣完整的出貨就可在單次往返中建立：

partyCreateWorkflow            → 描述始發地和目的地方
itemCreateWorkflow             → 描述產品線項目
cartonsCreateWorkflow          → 描述實體包裝
shipmentRatingCreateWorkflow   → 記錄運輸商報價
landedCostCalculateWorkflow    → 計算關稅/稅金/手續費
shipmentCreateWorkflow         → 建立出貨和標籤

Workflow 變動設計用於鏈結：您無需將一個步驟的 ID 傳遞到下一步，也無需針對每一步發送獨立的請求。提交整份文件，即可取得最終 Shipment。

當最後一步上的 serviceLevel 是日本郵便服務等級（japan_post.*），Zonos 會代表您使用驗證帳戶的後付款號碼呼叫日本郵便標籤 API（代碼 52），生成標籤和追蹤號碼、建立申報單號，並在該最終 shipmentCreateWorkflow 步驟內將它們連結起來。

為什麼要單一變動？ 每一步都取決於前一步（著陸成本需要產品和方；標籤需要所有內容）。將它們組合成單一 GraphQL 文件可確保資料一致性並避免五次額外的往返。

端點和認證 

此鏈中的所有請求都使用相同的端點。您在標頭中傳遞的內容取決於您的設置 - 選擇您的標籤。

URL：

https://api.zonos.com/graphql

標頭：

您在自己的驗證帳戶下運送自己的訂單。以自己的身份進行驗證 - 不需要帳戶金鑰。

credentialToken: {{YOUR_API_TOKEN}}

查找位置： Zonos Dashboard → Settings → Integrations → Account Key 區段。複製 API key 列上的權杖；這就是您的 credentialToken。

範例請求 

完整的 CreateDeclarationShipment 請求，您可以複製和調整 - 變動、其變數和回應 - 用於寄往美國的單筆日本郵便包裹（DDP）。下面的逐步區段中會詳細說明每個輸入。

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}

逐步說明 

下列各表中的狀態欄使用以下術語：

  • 必須 — 沒有它請求就會失敗。
  • 標籤必須 — 在 GraphQL 架構中是可選的，但生成有效的日本郵便美國標籤所需。
  • 條件式 — 取決於另一個欄位而必須（在行內註明）。
  • 建議 — 可選，但可確保準確的關稅和稅金。
  • 可選 — 不需要。

1. partyCreateWorkflow

為出貨中涉及的方建立 - 至少為 ORIGIN（出貨的來源地）和 DESTINATION（買家/收貨人）。

欄位↕狀態↕備註↕
type必須ORIGIN、DESTINATION、RETURN 等。
location.countryCode必須ISO-2 國家代碼。
location.line1、locality、administrativeAreaCode、postalCode標籤必須有效標籤所需的地址欄位。
person.firstName、lastName、phone標籤必須有效標籤所需的聯絡詳細資料。
person.companyName、email可選

範例負載：

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

回應會傳回建立的 Party ID 和已解析的地址欄位。

2. itemCreateWorkflow

為組成出貨的產品線項目建立。這些是將出現在商業發票上並推動著陸成本計算的 SKU。

欄位↕狀態↕備註↕
currencyCode必須單位價格的貨幣。
quantity必須此項目的單位數。
amount條件式單位價格（不是總數）。除非提供 totalAmount，否則必須。
totalAmount可選amount 的替代方案；amount 源自 totalAmount / quantity。
hsCode建議協調制度稅則代碼。推動關稅率。
countryOfOrigin建議製造物品所在地的 ISO-2 代碼。推動關稅/自由貿易協定。
name、description建議面向客戶的產品名稱和說明。
customsDescription可選海關說明覆蓋。
sku、productId可選您的內部識別碼。
measurements可選每個單位的重量/尺寸。

HS 代碼、原產國和金額是第 5 步中最影響關稅/稅金結果的三個欄位。

3. cartonsCreateWorkflow

為實體包裝 — 包裝盒、聚袋或信封建立，這些將保存產品。

欄位↕狀態↕備註↕
dimensionalUnit必須INCH 或 CENTIMETER。
weight、weightUnit標籤必須日本郵便需要包裝重量。
length、width、height可選外部尺寸。
type可選包裝風格（盒、聚袋、信封）。預設為 PACKAGE。

每個紙箱在第 6 步的運輸商標籤上成為一個包裹。多個紙箱 → 多件出貨，每個紙箱一個追蹤號碼。

4. shipmentRatingCreateWorkflow

記錄商家向買家收取的運費報價。

欄位↕狀態↕備註↕
amount必須買家支付的運費。如果免費，請傳遞 0。
currencyCode必須amount 的貨幣。
serviceLevelCode必須運輸商服務代碼（例如 japan_post.air.parcel）。
displayName可選收據/發票的美化名稱。

這是買家在結帳時報價的運費。它作為「運費」小計進入著陸成本計算，以便針對正確的 CIF 值計算關稅和稅金。

5. landedCostCalculateWorkflow

針對目的地國家/地區執行關稅、稅金和手續費計算。使用先前步驟中的產品、方和運費。

欄位↕狀態↕備註↕
endUse必須NOT_FOR_RESALE 或 FOR_RESALE。某些目的地為商業與個人最終用途適用不同的稅率。
tariffRate必須如果省略，預設為 ZONOS_PREFERRED。告訴 Zonos 要套用哪個稅則來源/方法。
calculationMethod建議DDP（買家預付）或 DDU（買家在門口支付）。使用 DDP 進行預付。推動 LandedCost.amountSubtotals 是否包含關稅/稅金。
currencyCode可選傳回著陸成本小計的貨幣。
arrivalDate可選如果提供，FX 匯率和稅則時間表將固定在此日期。

回應包括 amountSubtotals（duties、taxes、fees、shipping、landedCostTotal）— 這些是您在結帳時顯示給買家並在商業發票上列印的數字。

6. shipmentCreateWorkflow

終端步驟 — 建立 Shipment 實體、生成運輸商標籤，以及（可選）商業發票/包裝單。

對於日本郵便驗證帳戶，這也是 Zonos 代表您呼叫日本郵便標籤 API（代碼 52）的地方，注入您的後付款號碼、建立申報單號，並將申報單號連結到日本郵便傳回的追蹤號碼。

關鍵欄位：

欄位↕狀態↕備註↕
serviceLevel標籤必須要使用的日本郵便服務（例如 japan_post.air.ems_merchandise）。必須是 japan_post.* 服務等級。
generateLabel可選預設為 true；必須為 true 才能傳回標籤。
contentsType建議SALE_OF_GOODS、GIFT、DOCUMENTS、SAMPLE 等。推動海關待遇。
nonDelivery可選如果遞送失敗，運輸商應執行的操作：RETURN、ABANDON、FORWARD。
references可選商家提供的參考號碼，列印在標籤和商業發票上。請見下方。
declaredValue / isDeclaredValue可選出貨的保險價值。
shipmentConsolidationId可選在此出貨是批次調度的一部分時使用。

references 子輸入

這些欄位會列印在運輸商標籤和/或商業發票上。使用它們來表示收貨人或海關當局需要看到的 PO 號碼、許可證號碼和自由文字備註。

欄位↕狀態↕備註↕長度↕
invoiceNumber可選商家發票號碼。—
purchaseOrderNumber可選商家 PO 號碼。—
licenseNumber可選出口/進口許可證號碼。—
certificateNumber可選海關證書號碼。—
paymentConditions可選商業發票上顯示的免費文字付款條款。限制為 200 字元 — 較長的值會在列印的發票上溢出。
customsRemarks可選免費文字海關備註。—
taxCode可選標籤上列印的自訂稅碼。—

回應

傳回 Shipment 上有趣的欄位為：

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

trackingDetails.number 是日本郵便追蹤號碼。

label 物件可以用兩種方式傳回標籤 — 請求適合您的工作流程的任何一種（或兩者）：

欄位↕傳回↕使用時機↕
url指向轉譯標籤檔案 (PDF) 的託管連結，準備下載或列印。您想要交付連結 — 開啟它、透過電子郵件傳送或稍後不在負載中保存檔案時。
labelImageBase64 編碼的標籤影像 (PNG/PDF/ZPL) 在線應答中。您想直接在回應中取得標籤位元組，以附加到履行工作流程或儲存到您的 WMS 時。

只請求您需要的欄位。請求 url 會使回應保持較小；請求 labelImage 會在線傳回完整標籤，因此您無需第二次往返來擷取它。上面的範例要求 url。

錯誤處理 

  • 驗證錯誤（缺少必要欄位、無效的國家代碼等）會回到標準 GraphQL errors 陣列，並中止其餘的鏈。
  • 日本郵便錯誤（標籤生成失敗、無效地址等）會在 shipmentCreateWorkflow 上顯示為 GraphQL 錯誤。如果需要重試，請聯絡支援 — 建議的路徑是使用更正的輸入重新提交完整變動。

權限 

每個步驟都是獨立受保護的。您的 API 金鑰必須對鏈中的每個實體 (ITEM_WRITE、CARTON_WRITE、SHIPMENT_RATING_WRITE、LANDED_COST_WRITE、SHIPMENT_WRITE) 保有寫入權限。驗證帳戶上的標準商家角色會授予所有這些權限。

後續步驟 

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

CartonCreateWorkflowInput ItemCreateWorkflowInput LandedCostWorkFlowInput PartyCreateWorkflowInput ShipmentCreateWorkflowInput ShipmentRatingCreateWorkflowInput

MUTATIONS

cartonsCreateWorkflow itemCreateWorkflow landedCostCalculateWorkflow partyCreateWorkflow shipmentCreateWorkflow shipmentRatingCreateWorkflow

預約演示

這個頁面有幫助嗎？

獲取支持·法律文件·© 2026 Zonos
在此頁面：