建立單份寄件

CreateDeclarationShipment 將六個 *Workflow 變異串連成單一個 GraphQL 請求。每個步驟均建基於前面步驟提供的資料，並且所有步驟會一併提交，以便在一次往返中建立完整的寄件：

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

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 連結到日本郵政傳回的追蹤號碼的地方。

關鍵欄位：

就 contentsType 而言，已驗證帳戶流量中最常見的兩個值是 ECOMMERCE_GOODS（賣給消費者，即 BtoC）和 COMMERCIAL_GOODS（企業之間銷售，即 BtoB）。這兩個值會決定 Zonos 在呼叫日本郵政標籤 API 時傳送的 pkgType，因此這項選擇會改變海關申報單上列印的內容——並非只是標籤上的文字而已。

nonDelivery 子輸入

告知日本郵政在包裹無法派送時應如何處理——例如被收件人拒收、在邊境被拒絕入境，或因地址錯誤而無法派送。

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

API 將兩種退回方式分開提供；Dashboard 的退回選項則同時涵蓋兩者。

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

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

Dashboard 建立標籤對話方塊中的若無法派送選項會寫入相同的欄位，因此無論是在 Dashboard 建立的標籤，還是透過 API 建立的標籤，行為都完全一致。

references 子輸入

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

回應

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

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

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

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

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

日本郵政服務級別 

在 shipmentRatingCreateWorkflow 中，將以下其中一個代碼傳入 serviceLevelCode。

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

空運服務

水陸路服務

在相似服務之間作出選擇

小包 對比 國際空運小包。 兩者的重量上限均為 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，而運費亦會從到岸成本總額中消失——因此回應看似正確，但金額其實是錯的。

在依賴總額之前，請務必確認 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 參考中。

權限 

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

後續步驟 

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