建立單份寄件

CreateDeclarationShipment 將六個 *Workflow 變異鏈接到單個 GraphQL 請求中。每一步都基於前面步驟提供的資料，所有步驟一起提交，以便在一次往返中建立完整的寄件：

partyCreateWorkflow            → 描述原始地點和目的地方
itemCreateWorkflow             → 描述商品明細項
cartonsCreateWorkflow          → 描述實物包裝
shipmentRatingCreateWorkflow   → 記錄運輸商報價
landedCostCalculateWorkflow    → 計算關稅 / 稅項 / 費用
shipmentCreateWorkflow         → 建立寄件 + 標籤

Workflow 變異的設計可連鎖：您無需將 ID 從一個步驟引入下一個步驟，也無需為每個步驟發送單獨的請求。提交整份文件，取回最終的 Shipment。

當最終步驟上的 serviceLevel 是日本郵政服務級別（japan_post.*）時，Zonos 代表您使用已驗證帳戶的延期支付號碼呼叫日本郵政標籤 API（代碼 52），產生標籤和追蹤號碼，建立聲明 ID，並將它們連結 — 全部在最終 shipmentCreateWorkflow 步驟中進行。

為什麼只用一個變異？ 每個步驟都依賴於前一個步驟（已登陸成本需要商品 + 方面；標籤需要所有內容）。將它們捆綁到單個 GraphQL 文件中可保持資料一致性，避免五次額外的往返。

端點和身份驗證 

此鏈中的請求都使用相同的端點。您在標題中傳入的內容取決於您的設定 — 選擇您的標籤。

URL：

https://api.zonos.com/graphql

標題：

credentialToken: {{YOUR_API_TOKEN}}

範例請求 

一個完整的 CreateDeclarationShipment 請求，您可以複製和調整 — 變異、其變數和回應 — 針對運送至美國的單個日本郵政包裹 DDP。下方逐步部分會逐項分析每個輸入。

逐步說明 

下方每個表格上的狀態欄使用這些術語：

• 必需 — 無需請求將失敗。
• 標籤必需 — GraphQL 架構中為選擇性，但產生有效的日本郵政美國標籤所需。
• 條件式 — 取決於另一個欄位而需要（內聯註明）。
• 建議 — 選擇性，但能推動準確的關稅和稅項。
• 選擇性 — 不需要。

1. partyCreateWorkflow

建立涉及寄件的方 — 至少 ORIGIN（寄件從哪裡寄出）和 DESTINATION（買家 / 收件人）。

範例負載：

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

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

2. itemCreateWorkflow

建立組成寄件的商品明細項。這些是將出現在商業發票上且會推動已登陸成本計算的 SKU。

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

3. cartonsCreateWorkflow

建立實物包裝 — 將容納商品的盒子、聚酯膜或信封。

每個紙箱在步驟 6 的運輸商標籤上變成一個包裹。多個紙箱 → 多件寄件，每個紙箱有一個追蹤號碼。

4. shipmentRatingCreateWorkflow

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

這是買家在結帳時被報價的費率。它作為「運送」小計流入已登陸成本計算，以便針對正確的 CIF 值計算關稅和稅項。

5. landedCostCalculateWorkflow

運行目的地國家的關稅、稅項和費用計算。使用先前步驟中的商品、方和運送成本。

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

6. shipmentCreateWorkflow

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

對於日本郵政已驗證帳戶，這也是 Zonos 代表您呼叫日本郵政標籤 API（代碼 52）、注入您的延期支付號碼、建立聲明 ID，並將聲明 ID 連結到日本郵政傳回的追蹤號碼的地方。

關鍵欄位：

references 子輸入

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

回應

傳回的 Shipment 上有趣的欄位是：

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

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

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

僅選擇您需要的欄位。請求 url 可保持回應較小；請求 labelImage 會內聯傳回完整標籤，因此您無需第二次往返來取回它。上方範例請求 url。

錯誤處理 

• 驗證錯誤（遺漏的必需欄位、無效的國家代碼等）會進入標準 GraphQL errors 陣列並中止鏈的其餘部分。
• 日本郵政錯誤（標籤產生失敗、無效地址等）出現為 shipmentCreateWorkflow 上的 GraphQL 錯誤。如果需要重試，請聯繫支援 — 建議的路徑是使用已更正的輸入重新提交完整變異。

權限 

每個步驟都獨立保護。您的 API 金鑰必須擁有鏈中每個實體的寫入範圍（ITEM_WRITE、CARTON_WRITE、SHIPMENT_RATING_WRITE、LANDED_COST_WRITE、SHIPMENT_WRITE）。已驗證帳戶上的標準商家角色可授予所有這些。

後續步驟 

• 批次分派（整合） — 將當天的包裹集合到一份日本郵政延期支付分派單中。