API로 라벨 생성

Verified Account를 사용하는 Japan Post 라벨 워크플로를 프로그래밍 방식으로 구축하는 엔지니어링 팀을 위한 섹션입니다. 개발 리소스가 없는 중소 규모 발송자는 Dashboard에서 라벨 생성을 참고하세요.

Zonos + Japan Post API 모델 

Japan Post Verified Account 판매자는 Zonos를 직접 호출합니다. Zonos는 자체 Japan Post 자격 증명을 사용하고 모든 라벨에 Later Pay Number를 포함하여 우편료가 귀하의 계정에 청구되도록 합니다.

단일 GraphQL 요청에서 Zonos는:

1. Verified Account 및 Later Pay Number를 검증합니다.
2. 귀하를 대신해 Japan Post Label API(code 52)를 호출하여 라벨과 추적 번호를 생성합니다.
3. 관세 선납용 Declaration ID를 생성합니다.
4. declarationShipmentCreate로 Declaration ID를 추적 번호에 연결합니다.
5. 라벨, 추적 번호, 배송 레코드를 반환합니다.

본인의 Japan Post API 자격 증명(CTID / CT password)은 필요 없습니다. 단, Zonos Verified Account에 연결된 Japan Post Later Pay Number(後納お客様番号)가 필요합니다.

어떤 설정인가요? 

모든 사용자가 라벨과 manifest 생성을 위해 Zonos를 호출하므로 Japan Post 자격 증명(CTID / CT password)을 제공할 필요가 없습니다. 설정에 따라 달라지는 것은 전달하는 Zonos API 헤더입니다 — 아래 표에서 해당 행을 찾은 뒤 각 흐름의 엔드포인트 및 인증 섹션에서 해당 탭을 사용하세요.

BYOA(Bring Your Own Account): 각 판매자가 자체 Japan Post Verified Account를 보유하고, 플랫폼이 판매자의 account key를 전달하여 해당 판매자를 대신해 라벨을 생성합니다(플랫폼 자체 계정으로 배송하지 않음).

두 가지 API 흐름 

소포 발송 방식에 따라 두 가지 연동 패턴이 있습니다.

단일 배송 생성

기본 체인입니다. 하나의 GraphQL 요청이 parties, items, packaging 등 원시 입력부터 인쇄 가능한 Japan Post 라벨까지 배송을 처리합니다. 주문이 들어올 때마다 개별 소포를 발송하는 경우 사용합니다.

단일 배송 생성 →

일괄 발송(consolidation)

후납 일괄 흐름입니다. 아침에 consolidation을 열고, 하루 동안 단일 배송 체인으로 배송을 연결한 뒤, 일과 종료 시 consolidation을 마감하여 전체 일괄분을 아우르는 Japan Post 발송 전표를 받습니다. 소포별로 정산하는 대신 일과 종료 시 Japan Post 우편료를 한 번에 정산하는 경우 사용합니다.

일괄 발송(consolidation) →

이미 Japan Post My Page API를 사용 중인가요? 

현재 Japan Post My Page API(ctCode=52)로 라벨을 생성한다면 해당 연동을 유지하고 관세 선납 미국 라벨용으로 Zonos를 추가할 수 있습니다. 필드별 매핑 및 확인 체크리스트는 My Page API와 Zonos 함께 사용을 참고하세요.