단일 배송 생성

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 서비스 레벨(japan_post.*)이면, Zonos는 Verified Account의 Later Pay Number를 사용하여 귀하를 대신해 Japan Post Label API(code 52)를 호출하고, 라벨과 추적 번호를 생성하며, Declaration ID를 생성하고 연결합니다 — 모두 마지막 shipmentCreateWorkflow 단계 안에서 처리됩니다.

하나의 뮤테이션인 이유는? 각 단계는 이전 단계에 의존합니다(landed cost에는 품목과 당사자가 필요하고, 라벨에는 모든 것이 필요합니다). 하나의 GraphQL 문서로 묶으면 데이터 일관성이 유지되고 추가 왕복 5회를 피할 수 있습니다.

엔드포인트 및 인증 

이 체인의 모든 요청은 동일한 엔드포인트를 사용합니다. 헤더에 전달하는 값은 설정에 따라 다릅니다 — 해당 탭을 선택하세요.

URL:

https://api.zonos.com/graphql

헤더:

credentialToken: {{YOUR_API_TOKEN}}

예제 요청 

DDP로 미국에 발송하는 단일 Japan Post 소포에 대한 CreateDeclarationShipment 요청 전체 — 뮤테이션, 변수, 응답 — 을 복사하여 수정할 수 있습니다. 각 입력은 아래 단계별 섹션에서 설명합니다.

단계별 설명 

아래 각 표의 상태 열은 다음 용어를 사용합니다:

• 필수 — 없으면 요청이 실패합니다.
• 라벨 생성에 필수 — GraphQL 스키마상 선택이지만, 유효한 Japan Post 미국 라벨을 생성하려면 필요합니다.
• 조건부 — 다른 필드에 따라 필수(본문에 표기).
• 권장 — 선택이지만 관세·세금 정확도에 영향을 줍니다.
• 선택 — 필요하지 않습니다.

1. partyCreateWorkflow

배송에 관련된 parties를 생성합니다 — 최소 ORIGIN(발송지)과 DESTINATION(구매자/수취인)이 필요합니다.

예제 페이로드:

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

응답에는 생성된 Party ID와 해석된 주소 필드가 포함됩니다.

2. itemCreateWorkflow

배송을 구성하는 line items를 생성합니다. commercial invoice에 표시되고 landed cost 계산을 주도하는 SKU입니다.

HS code, country of origin, amount는 5단계에서 관세/세금 결과에 가장 큰 영향을 주는 세 필드입니다.

3. cartonsCreateWorkflow

물리적 패키지 — item을 담는 박스, 폴리백, 봉투 — 를 생성합니다.

각 carton은 6단계에서 carrier 라벨의 하나의 parcel이 됩니다. carton이 여러 개이면 carton당 추적 번호 하나씩인 멀티피스 배송입니다.

4. shipmentRatingCreateWorkflow

구매자에게 청구하는 배송 요금 견적을 기록합니다.

이것은 checkout에서 구매자에게 제시된 요금입니다. landed cost 계산의 "shipping" 소계로 반영되어 관세·세금이 올바른 CIF 값 기준으로 계산됩니다.

5. landedCostCalculateWorkflow

목적지 국가에 대한 관세, 세금, 수수료 계산을 실행합니다. 이전 단계의 items, parties, 배송비를 사용합니다.

응답에는 amountSubtotals(duties, taxes, fees, shipping, landedCostTotal)가 포함됩니다 — checkout에서 구매자에게 표시하고 commercial invoice에 인쇄하는 수치입니다.

6. shipmentCreateWorkflow

마지막 단계 — Shipment 엔티티를 생성하고, carrier 라벨을 생성하며, (선택) commercial invoice / packing slip을 생성합니다.

Japan Post Verified Account의 경우, Zonos는 여기서 귀하를 대신해 Japan Post Label API(code 52)를 호출하고, Later Pay Number를 주입하며, Declaration ID를 생성하고 Japan Post가 반환한 추적 번호에 Declaration ID를 연결합니다.

주요 필드:

contentsType의 경우, Verified Account 트래픽에서 가장 흔한 값은 ECOMMERCE_GOODS(소비자에게 판매, BtoC)와 COMMERCIAL_GOODS(기업 간 판매, BtoB)입니다. 이 값은 Zonos가 Japan Post 라벨 호출 시 전송하는 pkgType을 결정하므로, 선택에 따라 통관 신고서에 인쇄되는 내용이 달라집니다 — 단순한 라벨 표기 이상의 의미입니다.

nonDelivery 하위 입력

소포를 배송할 수 없는 경우 — 수취인이 수령을 거부하거나, 국경에서 반려되거나, 주소 오류로 배송 불가한 경우 — Japan Post가 취할 조치를 지정합니다.

option은 정확히 다음 네 가지 값만 허용합니다. RETURN 값은 존재하지 않습니다 — 소포가 반송되는 시점을 지정하려면 RETURN_AFTER_RETENTION 또는 RETURN_IMMEDIATELY를 사용하세요.

API는 두 반송 변형을 각각 노출하지만, Dashboard의 Return 옵션은 두 가지를 모두 포괄합니다.

transportMethod는 AIR 또는 MOST_ECONOMICAL을 허용하며, 반송되는 소포가 돌아오는 방식을 지정합니다. 두 RETURN_* 옵션에만 적용됩니다 — Dashboard는 Return이 선택된 경우에만 대응하는 Return method 필드를 표시합니다.

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

Dashboard의 Create label 대화상자에 있는 If undeliverable 선택 항목이 동일한 필드에 값을 씁니다. 따라서 Dashboard에서 생성한 라벨과 API로 생성한 라벨은 동일하게 동작합니다.

references 하위 입력

이 필드는 carrier 라벨 및/또는 commercial invoice에 인쇄됩니다. PO 번호, license 번호, 수취인 또는 세관이 확인해야 하는 자유 텍스트 비고를 표시하는 데 사용하세요.

응답

반환된 Shipment의 주요 필드는 다음과 같습니다:

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

trackingDetails.number는 Japan Post 추적 번호입니다.

label 객체는 라벨을 두 가지 방식으로 반환할 수 있습니다 — 워크플로에 맞는 방식(또는 둘 다)을 요청하세요:

필요한 필드만 선택하세요. url을 요청하면 응답 크기가 작아지고, labelImage를 요청하면 전체 라벨이 inline으로 반환되어 가져오기 위한 두 번째 왕복이 필요 없습니다. 위 예제는 url을 요청합니다.

Japan Post 서비스 레벨 

다음 코드 중 하나를 shipmentRatingCreateWorkflow의 serviceLevelCode로 전달하세요.

서비스 레벨 코드는 언더스코어가 아니라 점(.)을 사용합니다. 오류 메시지나 내부 참조에서 언더스코어 형식(japan_post_air_parcel)을 볼 수도 있지만, 이는 유효한 입력이 아닙니다.

항공 서비스

선편 서비스

유사 서비스 선택

소형 소포 vs. International Air Packet. 둘 다 2kg으로 제한됩니다. japan_post.air.packet은 Japan Post의 추적 가능한 소형 소포 서비스입니다. japan_post.air.small_packet은 추적이 불가능한 동등한 서비스입니다. 경량 소포에 추적 기능이 필요하면 japan_post.air.packet을 사용하세요.

등기 변형. 서신 및 인쇄물의 경우, 등기(書留) 버전의 서비스를 사용하면 추적 기능이 추가됩니다. japan_post.air.printed_matter와 japan_post.air.letter 자체에는 추적 기능이 포함되어 있지 않습니다.

사용 중단된 코드

japan_post.air.epacket_light는 International e-Packet Light였습니다. Japan Post는 2026년 6월 1일에 이 서비스명을 International Air Packet으로 변경하고, 모든 국가 및 지역으로 확대했습니다. 서비스 자체는 변경되지 않았습니다.

기존 코드는 여전히 정상적으로 해석되므로 기존 통합은 계속 작동하지만, 신규 작업에는 japan_post.air.packet을 사용하세요.

운송 방식 코드

japan_post.air, japan_post.surface, japan_post.economy_air, japan_post.custom도 해석되지만, 이는 특정 우편 상품이 아니라 운송 방식 또는 대체값을 나타냅니다. 일반적인 배송에는 위의 서비스 코드 중 하나를 사용하세요.

전송하는 코드 검증

인식되지 않는 serviceLevelCode는 오류를 발생시키지 않습니다. 요청은 errors 배열 없이 HTTP 200을 반환하고, serviceLevel은 null로 반환되며, shipping이 landed cost 총액에서 제외됩니다 — 따라서 응답은 정상처럼 보이지만 금액은 잘못됩니다.

총액을 신뢰하기 전에 항상 shipmentRatingCreateWorkflow.serviceLevel이 null이 아닌지 확인하세요.

현재 목록은 언제든지 다음과 같이 가져올 수 있습니다:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

이 쿼리는 carrier ID를 사용합니다. carrier 코드 japan_post를 전달하면 오류 없이 빈 목록이 반환됩니다.

오류 처리 

• 유효성 검사 오류(필수 필드 누락, 잘못된 국가 코드 등)는 표준 GraphQL errors 배열로 반환되며 체인의 나머지를 중단합니다.
• Japan Post 오류(라벨 생성 실패, 잘못된 주소 등)는 shipmentCreateWorkflow의 GraphQL 오류로 표시됩니다. 재시도가 필요하면 지원팀에 문의하세요 — 권장 경로는 수정된 입력으로 전체 뮤테이션을 다시 제출하는 것입니다.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

이 오류는 실제로 잘못된 필드가 아니라 변수 전체의 이름을 표시합니다. 거의 항상 해당 변수 안의 enum 값 하나가 자신의 enum 멤버가 아니라는 의미입니다 — 가장 흔한 경우는 nonDelivery.option, contentsType, 또는 serviceLevel입니다.

JSON 타입 문제가 아닙니다. boolean과 숫자에 따옴표를 붙이거나 제거해도 바뀌지 않습니다. payload가 거기까지 도달하지 못하고 enum 단계에서 먼저 거부되기 때문입니다.

잘못된 필드를 찾으려면 변수 안의 모든 enum 값 필드를 허용 값과 비교하세요:

모든 입력의 전체 enum 멤버는 API reference의 해당 타입 페이지에 나열되어 있습니다.

권한 

각 단계는 독립적으로 보호됩니다. API key는 체인의 각 엔티티에 대한 write scope(ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE)를 보유해야 합니다. Verified Account의 표준 판매자 역할은 이를 모두 부여합니다.

다음 단계 

• 일괄 dispatch(consolidation) — 하루 소포를 하나의 Japan Post 후납 dispatch slip으로 묶습니다.