建立單筆出貨

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

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

Workflow 變動的設計即為鏈結使用：您不需要將某一步驟的 ID 傳遞到下一步，也不需要為每個步驟各自發送請求。提交整份文件，即可取得最終的 Shipment。

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

為什麼要用單一變動？ 每個步驟都取決於前一步（Landed Cost 需要產品項目和各方資料；標籤需要所有內容）。將它們整合為單一 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

建立組成出貨的產品線項目。這些即是將出現在商業發票上，並用於計算 Landed Cost 的 SKU。

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

3. cartonsCreateWorkflow

建立實體包裝 — 也就是將用來容納商品的箱子、聚合袋或信封。

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

4. shipmentRatingCreateWorkflow

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

這是買家在結帳時所看到的運費報價。它會作為「shipping」小計項目納入 Landed Cost 計算，確保關稅和稅金是依正確的 CIF 值計算。

5. landedCostCalculateWorkflow

針對目的地國家執行關稅、稅金與手續費計算。會使用先前步驟中的商品、各方資料及運費。

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

6. shipmentCreateWorkflow

最終步驟 — 建立 Shipment 實體、產生運輸商標籤，並（視需要）產生商業發票／裝箱單。

對於日本郵便驗證帳戶而言，Zonos 也會在此步驟代表您呼叫日本郵便標籤 API（代碼 52），代入您的後付款號碼、建立申報單號，並將申報單號與日本郵便回傳的追蹤號碼連結。

關鍵欄位：

就 contentsType 而言，驗證帳戶流量中最常見的兩個值是 ECOMMERCE_GOODS（售予消費者，BtoC）和 COMMERCIAL_GOODS（企業對企業銷售，BtoB）。這兩個值會決定 Zonos 在呼叫日本郵便標籤 API 時傳送的 pkgType，因此這項選擇會影響報關單上實際列印的內容 — 不只是標籤上的顯示而已。

nonDelivery 子輸入

指示日本郵便在包裹無法送達時該如何處理 — 收貨人拒收、於邊境遭拒，或因地址錯誤而無法投遞。

option 僅接受以下四種值。並沒有 RETURN 這個值 — 請使用 RETURN_AFTER_RETENTION 或 RETURN_IMMEDIATELY 來選擇包裹「何時」退回。

API 將兩種退回變體分開公開；Dashboard 的 Return 選項則同時涵蓋這兩者。

transportMethod 接受 AIR 或 MOST_ECONOMICAL，用於設定退回包裹的運送方式。此欄位僅適用於兩個 RETURN_* 選項 — Dashboard 只有在選擇 Return 時，才會顯示對應的 Return method 欄位。

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

Dashboard Create label 對話方塊中的 If undeliverable 選擇器所寫入的即是同一個欄位，因此無論標籤是透過 Dashboard 或 API 建立，行為都相同。

references 子輸入

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

回應

傳回的 Shipment 中，值得留意的欄位如下：

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

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

label 物件可用兩種方式傳回標籤 — 請依您的工作流程選擇其中一種（或兩者皆用）：

只請求您所需要的欄位。請求 url 可讓回應內容保持精簡；請求 labelImage 則會在回應中內嵌完整標籤，讓您不需要再發送第二次請求來擷取它。上方範例請求的是 url。

日本郵便服務等級 

在 shipmentRatingCreateWorkflow 中，將下列其中一個代碼作為 serviceLevelCode 傳入。

服務等級代碼使用點號，而非底線。您可能會在錯誤訊息或內部參考資料中看到底線形式（japan_post_air_parcel），但這並非有效的輸入格式。

航空服務

水陸服務

在相似服務之間選擇

小型包裹 vs. 國際航空小包。 兩者皆以 2 公斤為上限。japan_post.air.packet 是日本郵便可追蹤的小型包裹服務。japan_post.air.small_packet 則是不可追蹤的對應服務。若輕量包裹需要追蹤功能，請使用 japan_post.air.packet。

掛號變體。 就信件與印刷品而言，追蹤功能是由該服務的掛號（書留）版本所提供。japan_post.air.printed_matter 和 japan_post.air.letter 本身並不包含追蹤功能。

已淘汰的代碼

japan_post.air.epacket_light 曾是國際 e-Packet Light 服務。日本郵便已於2026 年 6 月 1 日將此服務更名為國際航空小包，並將其擴展至所有國家和地區。服務內容本身並無變更。

舊代碼仍可正常解析，因此現有整合可繼續運作，但新開發的功能請改用 japan_post.air.packet。

運輸方式代碼

japan_post.air、japan_post.surface、japan_post.economy_air 和 japan_post.custom 同樣可以解析，但它們代表的是運輸方式或備援選項，而非特定的郵件產品。一般出貨請使用上方列出的其中一個服務代碼。

驗證您傳送的代碼

無法辨識的 serviceLevelCode 不會觸發錯誤。請求會傳回 HTTP 200，且不含 errors 陣列，serviceLevel 會傳回 null，運費也會從 Landed Cost 總額中消失 — 因此回應看起來正常，但金額卻是錯的。

在使用總額之前，請務必確認 shipmentRatingCreateWorkflow.serviceLevel 不是 null。

若要隨時取得目前的清單：

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

此查詢使用的是運輸商的 ID。若傳入運輸商代碼 japan_post，則會傳回空清單且不會出現錯誤。

錯誤處理 

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

VALIDATION_INVALID_TYPE_VARIABLE

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

此錯誤指出的是整個變數，而不是實際有問題的欄位。它幾乎都代表該變數內有某個列舉值不屬於其列舉定義 — 最常見的是 nonDelivery.option、contentsType 或 serviceLevel。

這並非 JSON 型別的問題。為布林值或數字加上或移除引號都不會有任何影響，因為酬載根本還沒被解析到那一步 — 列舉值會先被拒絕。

若要找出有問題的欄位，請逐一檢查該變數中每個列舉欄位是否符合其可接受的值：

任何輸入類型的完整列舉成員清單，皆列於其在 API reference 中的類型頁面。

權限 

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

後續步驟 

• 批次調度（整合） — 將當天的包裹組合成一份日本郵便延期付款調度單。