使用Zonos與日本郵政的My Page API

本指南適用於已經與日本郵政My Page Web API整合以建立標籤(操作 ctCode=52)的團隊。對於現在需要預付關稅的美國件貨，你通過Zonos建立標籤。Zonos是My Page工作流程的延伸：它代你呼叫My Page標籤API (ctCode=52)，新增美國關稅申報編號和DDP標記，並將My Page標籤和追蹤號碼返回給你。日本郵政仍然會製作標籤並透過你的日後付款編號向你收取郵資。

簡言之：你繼續在My Page上構建，而Zonos負責處理往美國件貨的美國關稅層。

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

Zonos如何融入 

對於往美國的件貨，你將件貨發送到Zonos的CreateDeclarationShipmentGraphQL工作流程，而不是直接呼叫My Page。在該單一請求中，Zonos：

1. 使用你的已驗證帳戶的日後付款編號代你呼叫日本郵政標籤API (ctCode=52)，所以郵資仍然被計入你的日本郵政帳戶。
2. 建立美國關稅申報編號並將其連結到追蹤號碼。
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. 申報編號已建立並已連結。 只有當申報編號連結到追蹤號碼時，件貨才是預付關稅——Zonos在同一請求中完成此操作。
3. DDP已列印在標籤上。 開啟返回的標籤並確認DDP標記存在。
4. 該件貨在你的Zonos Dashboard中出現 在你的已驗證帳戶下。
5. 對於批量派送， 確認合併關閉並返回日本郵政派送單(代碼61)。請參閱批量派送(合併)。
6. 與My Page標籤進行比較。 以兩種方式建立相同的件貨並確認服務等級、重量、申報價值和項目詳情在列印標籤上相符。

相關 

• 建立單一件貨 ——CreateDeclarationShipment 工作流程的完整欄位參考。
• 批量派送(合併) ——將當天的件貨集中為一張日本郵政派送單。