単一 shipment の作成

CreateDeclarationShipment は 6 つの *Workflow mutation を 1 GraphQL request に chain。各 step は前 step の data を build し、complete shipment を 1 round trip で create:

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 mutation は chained 設計 — step 間で ID を thread 不要、step ごと separate request 不要。document 全体 submit で final Shipment を取得。

final step の serviceLevel が Japan Post service level（japan_post.*）の場合、Zonos は Verified Account Later Pay Numbers で Japan Post Label API（code 52）を呼び出し、label と tracking number を generate、Declaration ID を create して link — すべて final shipmentCreateWorkflow step 内。

1 mutation の理由: 各 step は前 step に依存（landed cost は items + parties 必要、label はすべて必要）。1 GraphQL document に bundle して data consistency を保ち 5 extra round trip を回避。

Endpoint and authentication 

この chain の request は同一 endpoint。headers は setup により異なる — tab を選択。

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Example request 

copy-and-adapt 可能な complete CreateDeclarationShipment request — mutation、variables、response — 米国 DDP 向け単一 Japan Post parcel 用。各 input は以下 step-by-step で breakdown。

Step-by-step 

以下 table の Status column 用語:

• Required — なければ request fail。
• Required for label — GraphQL schema では optional だが valid Japan Post 米国 label に必要。
• Conditional — 他 field に依存（inline 記載）。
• Recommended — optional だが accurate duty/tax に重要。
• Optional — 不要。

1. partyCreateWorkflow

shipment の parties を create — 最低 ORIGIN（ship from）と DESTINATION（buyer / consignee）。

Example payload:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

response は created Party ID と resolved address fields を return。

2. itemCreateWorkflow

shipment を構成する line items を create。commercial invoice に表示され landed-cost calculation を drive する SKU。

HS code、country of origin、amount が step 5 duty/tax outcome に最も影響する 3 field。

3. cartonsCreateWorkflow

physical packages — item を入れる boxes、polybags、letters を create。

各 carton は step 6 carrier label 上 1 parcel。multiple cartons → carton ごと tracking number の multi-piece shipment。

4. shipmentRatingCreateWorkflow

buyer に請求する shipping rate quote を record。

checkout で buyer に quote された rate。landed-cost calculation の „shipping“ subtotal となり correct CIF value で duty/tax を compute。

5. landedCostCalculateWorkflow

destination country 向け duties、taxes、fees calculation を実行。prior steps の items、parties、shipping cost を使用。

response に amountSubtotals（duties、taxes、fees、shipping、landedCostTotal）— checkout で buyer に表示し commercial invoice に print する数値。

6. shipmentCreateWorkflow

terminal step — Shipment entity を create、carrier label を generate、（optional）commercial invoice / packing slip。

Japan Post Verified Account では Zonos が Japan Post Label API（code 52）を呼び出し Later Pay Numbers を inject、Declaration ID を create し Japan Post return tracking number に link する step。

Key fields:

references sub-input

carrier label および/または commercial invoice に print。consignee または customs authority が見る PO number、license number、free-text remarks を surface。

Response

return された Shipment の主要 fields:

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

trackingDetails.number は Japan Post tracking number。

label object は 2 方式で label return — workflow に合う方（または両方）を request:

必要 field のみ select。url は response を small に; labelImage は full label inline で 2nd round trip 不要。上記 example は url を request。

Error handling 

• Validation errors（required field 欠如、invalid country code 等）は standard GraphQL errors array で return し chain 残り abort。
• Japan Post errors（label generation failure、invalid address 等）は shipmentCreateWorkflow 上 GraphQL error。retry 必要なら support 連絡 — recommended は corrected input で full mutation resubmit。

Permissions 

各 step は independently secured。API key に chain 各 entity write scope 必須（ITEM_WRITE、CARTON_WRITE、SHIPMENT_RATING_WRITE、LANDED_COST_WRITE、SHIPMENT_WRITE）。Verified Account standard merchant role がすべて grant。

Next steps 

• Batch dispatch (consolidation) — 1 日分 parcel を 1 つの Japan Post deferred-payment dispatch slip に bundle。