Zonos + Japan Post API 모델
Japan Post Verified Account 판매자는 Zonos를 직접 호출합니다. Zonos는 Japan Post 자격 증명을 사용하고 모든 라벨에 Later Pay Number를 포함하여 우편료가 귀하의 계정에 청구되도록 합니다.
단일 GraphQL 요청에서 Zonos는:
- Verified Account 및 Later Pay Number를 검증합니다.
- 귀하를 대신해 Japan Post Label API(code 52)를 호출하여 라벨과 추적 번호를 생성합니다.
- 미국 관세 선납용 Declaration ID를 생성합니다.
declarationShipmentCreate로 Declaration ID를 추적 번호에 연결합니다.- 라벨, 추적 번호, 배송 레코드를 반환합니다.
Japan Post API 자격 증명(CTID / CT password)은 필요 없습니다. Zonos Verified Account에 연결된 Japan Post Later Pay Number(後納お客様番号)가 필요합니다.
어떤 설정인가요?
모든 사용자가 라벨과 manifest 생성을 위해 Zonos를 호출하므로 Japan Post 자격 증명(CTID / CT password)을 제공할 필요가 없습니다. 설정에 따라 달라지는 것은 전달하는 Zonos API 헤더입니다 — 아래 표에서 해당 행을 찾은 뒤 각 flow의 Endpoint and authentication 섹션에서 해당 탭을 사용하세요.
| ↕ | Ecommerce merchant↕ | Shipping platform (BYOA)↕ | 3PL / Logistic Partner / Reseller↕ |
|---|---|---|---|
| Who you are | A brand shipping your own orders | A platform many merchants create labels through | A partner shipping on behalf of many merchant clients |
| Verified Account you set up | One Verified Account (your own) | Each merchant sets up their own; you ship on their behalf | One Verified Account used for all your shippers |
| Zonos API headers to pass | credentialToken (yours) only | credentialToken (yours) + accountKey (each merchant's) | credentialToken (yours) only |
| Whose Later Pay Number is billed postage | Yours | Each merchant's | Yours |
| Who Zonos invoices for duties | You | Each merchant | You |
BYOA(Bring Your Own Account): 각 판매자가 자체 Japan Post Verified Account를 보유하고, 플랫폼이 판매자의 account key를 전달하여 해당 판매자를 대신해 라벨을 생성합니다(플랫폼 자체 계정으로 배송하지 않음).
두 가지 API flow
소포 dispatch 방식에 따라 두 가지 연동 패턴이 있습니다.
단일 배송 생성
기본 체인입니다. 하나의 GraphQL 요청이 parties, items, packaging 등 원시 입력부터 인쇄 가능한 Japan Post 라벨까지 배송을 처리합니다. 주문이 들어올 때마다 개별 소포를 발송하는 경우 사용합니다.
일괄 dispatch(consolidation)
후납 일괄 flow입니다. 아침에 consolidation을 열고, 하루 동안 단일 배송 체인으로 배송을 연결한 뒤, 일과 종료 시 consolidation을 마감하여 전체 batch를 아우르는 Japan Post dispatch slip을 받습니다. 소포별가 아니라 일과 종료 시 Japan Post 우편료를 한 번에 정산하는 경우 사용합니다.
이미 Japan Post My Page API를 사용 중인가요?
현재 Japan Post My Page API(ctCode=52)로 라벨을 생성한다면 해당 연동을 유지하고 관세 선납 미국 라벨용으로 Zonos를 추가할 수 있습니다. 필드별 매핑 및 확인 체크리스트는 My Page API와 Zonos 함께 사용을 참고하세요.
API로 라벨 생성
fulfillment 시스템을 Zonos GraphQL API와 연동하여 관세 선납 Japan Post 라벨을 생성하세요.
Verified Account를 사용하는 Japan Post 라벨 워크플로를 프로그래밍 방식으로 구축하는 엔지니어링 팀을 위한 섹션입니다. 개발 리소스가 없는 중소 규모 발송자는 Dashboard에서 라벨 생성을 참고하세요.