계정 설정

Verified Account를 생성하고, 결제 수단을 추가하고, 연동을 연결하세요.

Step 1 — Verified Account 생성

Česká pošta 등록 링크를 통해 Zonos Verified Account에 등록하세요. 비즈니스 주소와 결제 설정을 완료하세요.

미국행 배송의 관세 납부 비용을 충당할 수 있도록 Zonos 계정에 결제 수단을 추가하세요.

Zonos Dashboard에 로그인한 뒤 Account → Integrations로 이동하세요. 표에는 두 개의 키가 표시됩니다:

Dashboard에 표시되는 이름↕	용도↕	API에 사용?↕
Account key	우편 사업자와 연동하기 위한 식별자	❌ NO
API key	Zonos API를 호출하기 위한 인증 키	✅ YES — 이 키를 사용하세요

API key 행에 있는 토큰을 복사하세요. 이 토큰은 credential_live_로 시작합니다. 두 연동 방식 모두에 이 키가 필요합니다.

API key는 안전하게 보관하세요. 소스 코드 저장소(source control)에 커밋하거나 외부에 공개하지 마세요. 유출되었다고 판단되면 동일한 Account → Integrations 페이지에서 재발급하세요.

Zonos Dashboard의 Item Quoter 도구를 사용하면 배송 전에 제품의 예상 관세 비용을 조회할 수 있습니다 — Declaration ID를 생성하지 않고도 요금을 확인하고 미리 계획하는 데 유용합니다.

기술 환경에 맞는 방식을 선택하세요. 두 방식 모두 Declaration ID를 생성하며, 이후 이를 Česká pošta의 배송 시스템에 업로드합니다.

자체 시스템에서 Zonos를 직접 호출하는 기술 고객 및 개발자를 위한 방식입니다.

엔드포인트

인증

API key를 credentialToken 헤더에 전달하세요: credentialToken: credential_live_xxxxxxxxxxxxxxxxxx

API 예제

전체 요청과 응답을 포함한 API 예제 전체를 확인하려면 Česká pošta 계정에 로그인하세요.

Declaration ID 생성 후

Declaration ID를 배송 정보와 함께 Česká pošta에 제출하세요. Česká pošta가 Declaration ID를 배송과 연결하고 추적 번호를 반환합니다. Zonos는 추적 번호를 발급하지 않습니다.

오류 처리

오류/증상↕	가능한 원인 및 해결 방법↕
Security requirement failed	API key가 유효하지 않거나 잘못된 헤더로 전달되었습니다. Account Key가 아닌 API Key를 사용하고 있는지, 헤더 이름이 정확히 `credentialToken`인지 확인하세요.
HTTP 401 Unauthorized	요청 헤더에 API key가 없습니다. `credentialToken`이 포함되어 있는지 확인하세요.
response의 `errors` array	mutation이 GraphQL 오류를 반환했습니다. errors array의 `message` 필드에서 자세한 내용을 확인하세요.
예기치 않은 response 형식	response에 `data.declarationCreate.id`가 포함되어 있지 않습니다. 전체 response body를 기록하고 mutation 텍스트가 예제와 정확히 일치하는지 확인하세요.