DOCS
Collect•
홈우편 해외 발송 솔루션 우편을 통한 배송 Zonos와 Japan Post Verified Accounts API로 라벨 생성 My Page API와 Zonos 함께 사용

Japan Post My Page API와 Zonos 함께 사용

이미 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.
Zonos가 대신 처리하는 항목

Japan Post 자격 증명, operation code(ctCode, ctId, ctPw), ship date(sendDate), DDP declaration remarks는 보내지 않습니다. Zonos가 My Page 호출 시 자동으로 설정합니다.

My Page 필드와 Zonos 매핑 

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

서비스 및 처리 → shipmentCreateWorkflow

My Page 매개변수↕Zonos 필드↕참고↕
sendType + transTypeserviceLevel (and shipmentRatingCreateWorkflow.serviceLevelCode)One Zonos service level encodes both the mail service and the transport mode — e.g. japan_post.air.parcel. Must be a japan_post.* service level.
pkgTypecontentsTypeSALE_OF_GOODS, ECOMMERCE_GOODS, COMMERCIAL_GOODS, COMMERCIAL_SAMPLE, RETURNED_GOODS, GIFT, DOCUMENTS, or OTHER.
senderInstructionnonDelivery.optionRETURN_AFTER_RETENTION, RETURN_IMMEDIATELY, FORWARD, or ABANDON. Zonos는 My Page의 단일 "return" instruction을 두 개의 값으로 분리합니다.
fw_TransTypenonDelivery.transportMethodAIR or MOST_ECONOMICAL. 두 개의 RETURN_* 옵션에 적용됩니다.
noCmisNonCommercialtrue / false.
damgesdeclaredValueInsured value. Must be in JPY, whole yen.
totalWeightcartonsCreateWorkflow.weight + weightUnitSent to Japan Post in grams.

발송인 → partyCreateWorkflow (ORIGIN party)

My Page 매개변수↕Zonos 필드↕참고↕
from_namperson.firstName + person.lastName
from_companyNameperson.companyName
from_postallocation.postalCode
from_add1 / from_add2 / from_add3location.line1 / location.line2 / location.locality
from_preflocation.administrativeAreaCode도(현).
from_telperson.phone

수취인 → partyCreateWorkflow (DESTINATION party)

수취인 to_* 매개변수는 발송인 필드와 동일한 방식으로 DESTINATION party에 매핑됩니다.

My Page 매개변수↕Zonos 필드↕참고↕
to_namperson.firstName + person.lastName
to_companyNameperson.companyName
to_couCdlocation.countryCodeUS or PR.
to_add1 / to_add2 / to_add3location.line1 / location.line2 / location.locality
Postal code / state / phonelocation.postalCode / location.administrativeAreaCode / person.phone

품목 → itemCreateWorkflow

My Page 매개변수↕Zonos 필드↕참고↕
item_pkgcustomsDescription품목 통관 설명. 반각 문자 기준 최대 85자.
item_hsCodehsCode
item_numquantity
item_weightmeasurements (per-unit weight)
item_costamount단가.
item_curUnitcurrencyCode

주요 변환 

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

  • 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, 품목 상세가 인쇄 라벨에서 일치하는지 확인하세요.
라이브 전 테스트

Zonos로 프로덕션 미국 물량을 보내기 전에 테스트 배송으로 전체 flow를 검증하세요. My Page 연동은 그 외 용도로 유지됩니다.

관련 주제 

이 페이지가 도움이 되었나요?

지원 받기·법적 문서·© 2026 Zonos
이 페이지에서:
  • Japan Post My Page API와 Zonos 함께 사용
  • Zonos의 역할
  • My Page 필드와 Zonos 매핑