My Page API と Zonos の併用

Japan Post My Page Web API でラベルを作成する（operation ctCode=52）既存連携向けです。米国向け parcel では関税前払いが必要になり、Zonos 経由でラベルを作成します。Zonos は My Page workflow の拡張: 代わりに My Page Label API（ctCode=52）を呼び出し、米国 duty Declaration ID と DDP marking を追加し、My Page ラベルと tracking number を返します。Japan Post は引き続きラベルを生成し、Later Pay Number 経由で postage を請求します。

要約: My Page 上で構築を継続し、米国向け shipment の U.S. duty layer は Zonos が処理します。

初めて連携する場合は Create a single shipment から開始してください。

Zonos の位置づけ 

米国向け parcel では、My Page を直接呼び出す代わりに shipment を Zonos CreateDeclarationShipment GraphQL workflow に送信します。その 1 リクエストで Zonos は:

1. Verified Account の Later Pay Number を使用し、代わりに Japan Post Label API（ctCode=52）を呼び出し — postage は引き続き Japan Post アカウントに請求。
2. 米国 duty Declaration ID を作成し tracking number に紐づけ。
3. ラベルに DDP marking を追加。
4. Japan Post ラベルと tracking number を返却。

CreateDeclarationShipment は 7 ステップを chain します。ctCode=52 リクエスト用に既に組み立てているデータは次に分散されます:

• Sender / receiver → partyCreateWorkflow の ORIGIN と DESTINATION parties。
• Items → itemCreateWorkflow（shipmentCartons 内 line items）。
• Packaging and weight → cartonsCreateWorkflow。
• Service, handling, customs flags → shipmentCreateWorkflow。

My Page フィールドと Zonos のマッピング 

各表は Japan Post My Page ctCode=52 パラメータが Zonos workflow のどこに対応するかを示します。詳細は Create a single shipment を参照してください。

Service and handling → shipmentCreateWorkflow

Sender → partyCreateWorkflow（ORIGIN party）

Receiver → partyCreateWorkflow（DESTINATION party）

receiver to_* パラメータは sender フィールドと同様に DESTINATION party にマップします。

Items → itemCreateWorkflow

注意すべき変換 

最も注意が必要な transform:

• Service level が sendType + transType を置き換え。 今日 2 パラメータで送っている mail service と transport に一致する単一 Zonos japan_post.* service level を選択。
• Insured value（declaredValue）は JPY 整数必須。 他通貨や小数円は拒否されます。
• Weight は gram で Japan Post に送信。 carton で weight + weightUnit を提供、Zonos が変換。
• Item customs description は半角 85 文字以内。
• すべての address フィールドは英語（Roman）文字必須。

米国向けラベルの検証 

Zonos 経由で米国向けラベルを作成したら end-to-end で確認:

1. Workflow が tracking number と label を返す。 shipmentCreateWorkflow.trackingDetails.number と shipmentCartons[].label.url を確認。
2. Declaration ID が作成・紐づけされた。 Declaration ID が tracking number にリンクされているときのみ duty-prepaid — 同一リクエスト内で Zonos が実行。
3. DDP がラベルに印刷されている。 返却 label で DDP marking を確認。
4. Shipment が Verified Account 配下の Zonos Dashboard に表示される。
5. Batch dispatch では consolidation が close し Japan Post dispatch slip（Code 61）が返ることを確認。Batch dispatch (consolidation) 参照。
6. My Page ラベルと比較。 同一 shipment を両方で作成し、service level、weight、declared value、item details が印刷 label で一致することを確認。

関連 

• Create a single shipment — CreateDeclarationShipment workflow の完全フィールド参照。
• Batch dispatch (consolidation) — 1 日分 parcel を 1 枚の Japan Post dispatch slip に bundle。