搭配 Zonos 使用日本郵局 My Page API

本指南適用於已整合日本郵局 My Page Web API 以建立標籤（操作 ctCode=52）的團隊。對於現在需要預付關稅的美國寄送包裹，您可透過 Zonos 建立標籤。Zonos 是 My Page 工作流程的延伸：它代表您呼叫 My Page 標籤 API (ctCode=52)、新增美國關稅聲明 ID 和 DDP 標記，然後將 My Page 標籤和追蹤號碼退回給您。日本郵局仍會製作標籤，並透過您的延期付款帳號帳單郵資。

簡言之：您繼續在 My Page 上進行開發，Zonos 為寄往美國的出貨處理美國關稅層。

如果您是首次整合，請從建立單一出貨開始。

Zonos 的角色 

對於寄往美國的包裹，您將出貨傳送至 Zonos CreateDeclarationShipment GraphQL 工作流程，而不是直接呼叫 My Page。在該單一請求中，Zonos 會：

1. 代表您呼叫日本郵局標籤 API (ctCode=52)，使用您驗證帳號的延期付款帳號，以便郵資仍以帳單方式計入您的日本郵局帳戶。
2. 建立美國關稅聲明 ID，並將其連結至追蹤號碼。
3. 新增 DDP 標記至標籤。
4. 將日本郵局標籤和追蹤號碼退回給您。

CreateDeclarationShipment 鏈結七個步驟。您為 ctCode=52 請求已組合的相同資料會分散在它們中：

• 寄件者/收件者 → partyCreateWorkflow 的 ORIGIN 和 DESTINATION 各方。
• 物品 → itemCreateWorkflow（shipmentCartons 內的明細項目）。
• 包裝和重量 → cartonsCreateWorkflow。
• 服務、處理和海關旗標 → shipmentCreateWorkflow。

您的 My Page 欄位如何對應至 Zonos 

每個表格顯示日本郵局 My Page ctCode=52 參數在 Zonos 工作流程中的位置。如需完整欄位詳細資訊、類型和必要欄位，請參閱建立單一出貨。

服務和處理 → shipmentCreateWorkflow

寄件者 → partyCreateWorkflow（ORIGIN 方）

收件者 → partyCreateWorkflow（DESTINATION 方）

收件者 to_* 參數對應至 DESTINATION 方的方式與寄件者欄位相同。

物品 → itemCreateWorkflow

值得了解的轉換 

這些是最常需要注意的轉換：

• 服務等級取代 sendType + transType。 選擇單一 Zonos japan_post.* 服務等級，符合您目前作為兩個不同參數傳送的郵件服務和運輸方式。
• 投保價值 (declaredValue) 必須以日幣 (JPY) 表示，整數日圓。 其他貨幣或分數日圓將被拒絕。
• 重量以克數傳送至日本郵局。 在紙箱上提供 weight + weightUnit；Zonos 會轉換。
• 物品海關說明限制為 85 個半寬字元。
• 所有地址欄位必須以英文（羅馬）字元表示。

驗證您的美國標籤 

當您透過 Zonos 建立美國標籤時，確認它從頭到尾正常運作：

1. 工作流程會傳回追蹤號碼和標籤。 檢查回應中的 shipmentCreateWorkflow.trackingDetails.number 和 shipmentCartons[].label.url。
2. 已建立聲明 ID 並連結。 只有當聲明 ID 連結至追蹤號碼時，出貨才會預付關稅——Zonos 在同一請求內執行此操作。
3. DDP 已列印在標籤上。 開啟退回的標籤，並確認存在 DDP 標記。
4. 出貨出現在您的 Zonos 儀表板（在您的驗證帳號下）。
5. 針對批量分派， 確認整合已關閉，並傳回日本郵局分派單（代碼 61）。請參閱批量分派（整合）。
6. 與 My Page 標籤比較。 以兩種方式建立相同的出貨，並確認列印標籤上的服務等級、重量、已聲明價值和物品詳細資訊相符。

相關 

• 建立單一出貨 — CreateDeclarationShipment 工作流程的完整欄位參考。
• 批量分派（整合） — 將當天的包裹合併到一個日本郵局分派單中。