Japan Post My Page API와 Zonos 함께 사용

이 가이드는 이미 Japan Post My Page Web API로 라벨을 생성(operation ctCode=52)하는 팀을 위한 것입니다. 관세를 선납해야 하는 미국 향 소포의 경우 Zonos를 통해 라벨을 생성합니다. Zonos는 My Page workflow의 확장입니다: 귀하를 대신해 My Page Label API(ctCode=52)를 호출하고, 미국 관세 Declaration ID와 DDP 표기를 추가한 뒤 My Page 라벨과 추적 번호를 반환합니다. Japan Post는 여전히 라벨을 생성하고 Later Pay Number로 우편료를 청구합니다.

요약하면, My Page 기반 구축은 유지하고 미국 향 배송의 미국 관세 레이어는 Zonos가 처리합니다.

처음 연동하는 경우 단일 배송 생성부터 시작하세요.

Zonos의 역할 

미국 향 소포의 경우 My Page를 직접 호출하는 대신 Zonos CreateDeclarationShipment GraphQL workflow로 배송을 보냅니다. 단일 요청에서 Zonos는:

1. Verified Account의 Later Pay Number를 사용해 귀하를 대신해 Japan Post Label API(ctCode=52)를 호출하여 우편료가 Japan Post 계정에 계속 청구되도록 합니다.
2. 미국 관세 Declaration ID를 생성하고 추적 번호에 연결합니다.
3. 라벨에 DDP 표기를 추가합니다.
4. Japan Post 라벨과 추적 번호를 반환합니다.

CreateDeclarationShipment는 7단계를 연결합니다. ctCode=52 요청에 이미 조립하는 동일 데이터가 다음에 분배됩니다.

• 발송인/수취인 → partyCreateWorkflow의 ORIGIN 및 DESTINATION parties.
• 품목 → itemCreateWorkflow(shipmentCartons 내 line items).
• 포장 및 무게 → cartonsCreateWorkflow.
• 서비스, handling, customs flags → shipmentCreateWorkflow.

My Page 필드와 Zonos 매핑 

각 표는 Japan Post My Page ctCode=52 매개변수가 Zonos workflow의 어디에 해당하는지 보여줍니다. 필드 상세, 타입, 필수 여부는 단일 배송 생성을 참고하세요.

Service and handling → shipmentCreateWorkflow

Sender → partyCreateWorkflow (ORIGIN party)

Receiver → partyCreateWorkflow (DESTINATION party)

The receiver to_* parameters map to the DESTINATION party the same way the sender fields do.

Items → itemCreateWorkflow

주요 변환 

다음 변환에 가장 자주 주의가 필요합니다.

• Service level이 sendType + transType를 대체합니다. 오늘 두 개의 별도 매개변수로 보내는 우편 서비스와 운송에 해당하는 단일 Zonos japan_post.* service level을 선택하세요.
• 보험 가치(declaredValue)는 JPY 정수(whole yen)여야 합니다. 다른 통화나 소수 yen은 거부됩니다.
• 무게는 Japan Post에 그램으로 전송됩니다. carton에 weight + weightUnit을 지정하면 Zonos가 변환합니다.
• 품목 customs description은 half-width 85자로 제한됩니다.
• 모든 주소 필드는 영어(로마자)여야 합니다.

미국 라벨 검증 

Zonos로 미국 라벨을 생성할 때 end-to-end가 작동했는지 확인하세요.

1. Workflow가 추적 번호와 라벨을 반환합니다. 응답에서 shipmentCreateWorkflow.trackingDetails.number 및 shipmentCartons[].label.url을 확인하세요.
2. Declaration ID가 생성·연결되었습니다. Declaration ID가 추적 번호와 연결되어야 관세 선납 상태입니다 — Zonos가 동일 요청에서 처리합니다.
3. 라벨에 DDP가 인쇄됩니다. 반환된 라벨을 열어 DDP 표기가 있는지 확인하세요.
4. 배송이 Verified Account 하의 Zonos Dashboard에 표시됩니다.
5. Batch dispatch의 경우 consolidation이 마감되고 Japan Post dispatch slip(Code 61)이 반환되는지 확인하세요. 일괄 dispatch(consolidation) 참고.
6. My Page 라벨과 비교. 동일 배송을 두 경로로 생성하고 service level, 무게, insured value, 품목 상세가 인쇄 라벨에서 일치하는지 확인하세요.

관련 주제 

• 단일 배송 생성 — CreateDeclarationShipment workflow 전체 필드 참조.
• 일괄 dispatch(consolidation) — 하루 소포를 하나의 Japan Post dispatch slip으로 묶습니다.