DOCS

Zonos에 우편 화물 정보 전달하기

미국 및 유럽연합행 화물의 소포 및 운송 수단 데이터를 전송합니다.

목적지와 관계없이 동일한 두 가지 호출을 사용합니다.

호출↕전송 내용↕시점↕
brokerageManifestLinesCreate소포: 물품, 당사자, 참조 정보. 요청당 최대 100개소포 접수 시
brokerageManifestCreate운송 수단. 1번 호출에서 받은 소포 id를 지정합니다운송사 인계 시

두 호출은 서로를 차단하지 않습니다. 운송 수단이 생성된 후 접수된 소포에는 manifestLinesLink를 사용하세요.

1번 호출에서 반환된 id를 보관하세요. 2번 호출에 필요합니다.

Landed cost는 비동기적으로 계산됩니다. 성공 응답은 접수를 확인할 뿐, 견적 산출을 의미하지 않습니다. 품목 및 당사자 데이터는 계산 중에 검증되므로, API가 해당 필드 없이도 요청을 수락하더라도 아래 필드를 전송하세요.

일부 목적지는 PDDP 할증료를 추가합니다. 목적지별 PDDP 할증료를 참조하세요.

미국 이외의 목적지에는 한 번의 호출로 처리하는 대안이 있습니다.

필드 범례 

라벨↕의미↕
필수이 필드가 없으면 API가 요청을 거부합니다.
EU 필수모든 EU행 소포에 반드시 전송해야 합니다. API가 이 필드 없이 소포를 수락할 수도 있지만, 견적이 잘못되거나 실패할 수 있으며 해당 화물은 규정을 준수하지 않게 됩니다.
미국 필수모든 미국행 소포에 반드시 전송해야 합니다. 이 필드가 없으면 통관 신고를 제출할 수 없습니다.
권장견적 산출에는 필요하지 않지만 목적지 우정당국과 세관이 사용합니다. 보유하고 있다면 항상 전송하세요.
선택해당되는 경우 전송하세요.

1단계: 소포 정보 전달하기 

소포 필드

필드↕요구 사항↕참고↕
trackingNumber필수우편물 추적 번호.
currencyCode필수소포에 포함된 모든 품목 가액의 통화.
endUse필수DOCUMENTS, GIFT, FOR_RESALE, NOT_FOR_RESALE 또는 RETURN.
items필수최소 하나의 품목. 품목 필드를 참조하세요.
parties필수ORIGIN 당사자 하나와 DESTINATION 당사자 하나. 당사자 필드를 참조하세요.
shippingCostEU 필수소포의 배송 요금. EU 관세와 부가가치세는 CIF 가액을 기준으로 부과되므로, 배송비가 누락되면 0으로 처리됩니다.
shippingCostCurrencyEU 필수shippingCost의 통화. 생략하면 기본값은 USD입니다.
taxIdNumber선택IOSS에 따라 판매된 경우의 IOSS 번호. IOSS를 참조하세요.
consignmentWeight권장소포 총중량(킬로그램). 동일한 추적 번호를 공유하는 모든 라인에 같은 값을 전송하세요. 관세 산정에는 사용되지 않습니다.
referenceNumber권장중복 방지에 사용되는 소포의 고유 참조 번호. 중복 소포를 참조하세요.
shipperAccountId권장화주의 인증된 계정에 대한 Zonos 조직 ID 또는 귀사의 외부 ID. 이 값이 없으면 소포는 그 뒤에 있는 판매자가 아닌 귀사로 귀속됩니다.
postalOperatorCode선택간소화 경로에서 요청 수준의 기본값을 재정의합니다. 그 외에는 무시됩니다.
declarationId선택이 소포에 대해 이미 생성된 Zonos 신고서. 일반적으로 주문에서 확인됩니다.

품목 필드

물품 라인당 하나의 항목입니다. 세 가지 분류의 물품이 담긴 소포는 세 개의 항목을 가진 하나의 소포입니다.

필드↕요구 사항↕참고↕
quantity필수단위 수량.
countryOfOrigin필수2자리 ISO 국가 코드. 발송 국가가 아닌 제조 국가입니다.
amount필수단가. amount 또는 totalAmount 중 정확히 하나만 전송하세요.
totalAmount필수전체 수량에 대한 총 가액. amount 대신 전송하면 단가는 totalAmount / quantity가 됩니다.
description필수물품에 대한 일반 설명.
measurements필수순중량 항목을 포함하세요(단위당 WEIGHT 또는 전체 수량에 대한 TOTAL_WEIGHT 중 하나만). 아래를 참조하세요.
hsCode미국 필수물품 라인별 HS 또는 관세 코드. 10자리 권장, 최소 6자리.
customsDescription선택description과 다른 경우의 통관용 설명.
provinceOfOrigin선택국가에서 요구하는 경우 원산지 주 또는 도.
sku권장귀사의 SKU. 제품 식별자를 참조하세요.
productId권장귀사의 제품 식별자.
gtin권장국제거래단품식별코드(GTIN), 숫자만 사용.
upc선택gtin을 전송하지 않으면 gtin으로 사용됩니다.
name선택짧은 제품명.
documentId선택이미 업로드한 문서를 연결합니다.
productComposition선택제품을 구성하는 소재. 각 항목에는 material과 percentage가 필요합니다.
marketplace선택품목이 판매된 마켓플레이스(name 및 url).

HS 코드와 원산지는 물품 라인별로 지정합니다. 서로 다른 분류의 물품이 담긴 소포는 각 물품에 대한 코드와 원산지가 필요합니다. 혼합 소포에 하나의 코드만 사용하면 미국에 신고할 수 없습니다.

측정값. 각 항목에는 type, unitOfMeasure, value가 필요합니다. 중량은 순중량이며 해당 라인의 전체 수량을 포괄하므로 수량을 곱하지 마세요. 이 중량을 기준으로 관세가 산정됩니다.

  • type: WEIGHT, TOTAL_WEIGHT, VOLUME, LENGTH, WIDTH, HEIGHT 또는 ALCOHOL_BY_VOLUME
  • unitOfMeasure: GRAM, KILOGRAM, OUNCE, POUND, LITER, MILLILITER, CENTIMETER, METER, MILLIMETER, INCH, FOOT, YARD 또는 PERCENTAGE

제품 구성. 각 항목은 material과 percentage를 받으며, 선택적으로 countryOfMeltAndPour, countryOfCast, primaryCountryOfSmelt, secondaryCountryOfSmelt를 받습니다.

당사자 필드

각 당사자에는 type(발송인은 ORIGIN, 수취인은 DESTINATION), person, location이 있습니다.

필드↕출발지(발송인)↕목적지(수취인)↕
location.countryCode필수필수
location.line1필수필수
location.locality (도시)필수필수
location.postalCode권장필수(아일랜드 제외)
location.administrativeAreaCode선택미국 및 캐나다 필수
person.firstName필수필수
person.lastName필수필수
person.emailEU 필수EU 필수
person.companyName선택선택
person.phone선택선택

두 당사자 모두 세관 신고서에 기재됩니다. 불완전한 당사자 정보는 통관 실패의 가장 흔한 원인입니다.

출발지 우편번호는 필수가 아닌 권장 사항입니다. 홍콩, 아랍에미리트, 카타르에는 우편번호가 없습니다. EU 수취인 우편번호는 아일랜드를 제외하고 필수입니다.

administrativeAreaCode는 두 글자 코드를 받습니다. TEXAS가 아닌 TX를 사용하세요.

예시

1mutation BrokerageManifestLinesCreate($input: [ManifestLineInput!]!) {
2 brokerageManifestLinesCreate(input: $input) {
3 id
4 trackingNumber
5 referenceNumber
6 taxIdNumber
7 }
8}

응답

json

{
  "data": {
    "brokerageManifestLinesCreate": [
      {
        "id": "line_abc123def456",
        "trackingNumber": "RB123456799GB",
        "referenceNumber": "ITM-00184413",
        "taxIdNumber": "IM5281234567"
      }
    ]
  }
}

제품 식별자 

각 물품 라인에 있는 네 가지 필드입니다.

품목에 전송할 필드↕설명↕
productId귀사의 자체 제품 식별자
sku귀사의 재고 관리 단위(SKU)
gtin표준 GTIN
manufacturerProductId제조사의 부품 번호

유럽에서의 활용 방식

EU PDDP에는 일곱 개의 제품 식별자 필드가 있습니다. 그중 세 개는 품목에 전송한 값으로 직접 채워지므로, 여기에서 더 많이 전송할수록 신고서가 더 많이 채워집니다.

PDDP 필드↕데이터 출처↕제한↕
merchantProductIdentifier (MPID)productId, 없으면 sku50
manufacturerStandardizedProductIdentifier (S PID)gtin숫자만
manufacturerNonStandardizedProductIdentifier (NS PID)manufacturerProductId70

lccProviderProductIdentifier는 Zonos의 품목 id로 설정됩니다. manufacturerIdentifier는 전송되지 않습니다.

제약 조건:

  • gtin은 숫자만 사용합니다. 0-50123-45678-9가 아닌 05012345678900을 사용하세요.
  • gtin 또는 upc 중 하나만 전송하세요. UPC는 GTIN-12이며, upc는 gtin으로 정규화됩니다.
  • manufacturerProductId는 70자까지 허용됩니다. 다른 모든 식별자 필드는 50자에서 잘립니다.
  • 보유하지 않은 필드는 생략하세요. 빈 문자열은 거부됩니다. 일곱 개 필드 모두 최소 길이는 1입니다.

2단계: 운송 수단 정보 전달하기 

운송사 인계 시 1단계에서 받은 소포 id를 지정하여 전송합니다.

필드↕요구 사항↕참고↕
postalOperatorCode필수등록된 사업자 코드.
carrierCode필수IATA 2자리 코드(항공) 또는 SCAC(트럭, 해상).
serviceNumber필수항공편, 항차 또는 운행 번호.
arrivalDate필수ISO 8601 형식의 도착 날짜 및 시간.
destinationCode필수운송 수단의 도착지. 공항 또는 항구 코드.
transportationMode권장AIR, SEA, ROAD 또는 RAIL. 기본값은 AIR입니다.
vesselName해상 운송 필수선박명. 세관은 입항 선박을 운송사 코드가 아닌 선박명으로 식별합니다.
originCode권장운송 수단의 출발지.
awbPrefix선택항공 화물 운송장 접두사.
awbNumber선택항공 화물 운송장 번호.
weight선택운송 수단의 총중량.
weightUnit선택weight의 단위.
amount선택운송 수단의 총 가액.

항공 화물 운송장은 선택 사항입니다. 운송 수단 키는 carrierCode, serviceNumber, 날짜에서 도출됩니다.

destinationCode와 originCode는 기존 형식 그대로 전송하세요. 세관 항구 목록과의 매핑은 Zonos가 관리합니다.

1mutation BrokerageManifestCreate($input: ManifestInput!, $lineIds: [ID!]!) {
2 brokerageManifestCreate(input: $input, lineIds: $lineIds) {
3 id
4 carrierCode
5 serviceNumber
6 destinationCode
7 arrivalDate
8 }
9}

해상 발송도 같은 호출을 사용하며, transportationMode: SEA, carrierCode에 SCAC, serviceNumber에 항차 번호, vesselName을 지정하고, 도착 날짜는 몇 시간이 아닌 몇 주 후가 됩니다.

나중에 접수된 소포

운송 수단이 생성된 후 접수된 소포는 manifestLinesLink로 연결합니다.

뮤테이션

graphql

mutation ManifestLinesLink($manifestId: ID!, $lineIds: [ID!]!) {
  manifestLinesLink(manifestId: $manifestId, lineIds: $lineIds) {
    id
  }
}

유럽행 간소화 경로 

미국 이외 지역행 소포는 운송 수단 단계를 건너뛸 수 있습니다. 배열과 함께 사업자 코드를 전달하세요.

1mutation BrokerageManifestLinesCreate(
2$postalOperatorCode: PostalOperatorCode
3$input: [ManifestLineInput!]!
4) {
5 brokerageManifestLinesCreate(
6 postalOperatorCode: $postalOperatorCode
7 input: $input
8 ) {
9 id
10 trackingNumber
11 }
12}

postalOperatorCode는 운송 수단이 담았을 정보를 대신 제공합니다. 소포는 자체 값으로 요청 수준의 기본값을 재정의할 수 있습니다.

미국행 소포에는 항상 운송 수단이 필요합니다. 통관 신고서에 운송사, 운항편, 도착 항구가 기재되기 때문입니다.

EU 데이터 참고 사항 

IOSS

IOSS에 따라 판매된 경우 taxIdNumber에 IOSS 번호를 전송하세요.

형식: IM, 3자리 EU 회원국 코드, 그다음 7자리 숫자. 예: IM5281234567.

  • 유효한 경우: 수입 부가가치세 없이 견적이 산출됩니다.
  • 형식이 잘못되었거나 없는 경우: 수입 부가가치세를 포함하여 견적이 산출됩니다. 등록 번호를 전송하거나 필드를 생략하세요. 일련번호나 라인 수를 전송하지 마세요.

CIF 가액

EU 관세와 부가가치세는 CIF 가액(물품 가액과 배송비의 합)을 기준으로 부과됩니다. 모든 EU 소포에 shippingCost와 shippingCostCurrency를 전송하세요. 이를 생략하면 배송비가 0으로 처리되어 견적이 과소 산정됩니다.

목적지 당사자

수취인의 국가 코드가 포함된 DESTINATION 당사자가 필요합니다. 이 정보에 따라 적용되는 규정이 결정됩니다.

미국 데이터 참고 사항 

완전한 당사자 정보

두 당사자 모두 이름, 거리 주소, 지역, 우편번호, 주, 국가를 포함한 전체 주소가 필요합니다. administrativeAreaCode는 두 글자 주 코드를 받습니다.

품목 분류

물품 라인마다 관세 코드가 필요합니다. 10자리를 권장하며 최소 6자리입니다. 6자리 코드는 확장되어 검증됩니다. 코드가 없는 라인은 신고할 수 없습니다.

Zonos가 처리하는 항목

귀사의 계정 구성과 소포에 담긴 물품을 바탕으로 Zonos가 결정합니다.

  • 수입자(Importer of record)
  • 통관 보증 및 보증보험
  • 신고 유형 및 신고인 코드
  • 관세, 세금, 수수료
  • 세관 전송

일반 참고 사항 

중복 소포

referenceNumber는 귀사의 모든 소포에서 고유해야 합니다. 이미 사용한 번호를 다시 사용하면 기존 레코드가 반환되고 새 운송 수단으로 이동되며, 품목과 당사자 정보는 업데이트되지 않습니다. 소포를 수정하려면 같은 참조 번호로 다시 전송하지 말고 Zonos에 문의하세요.

가액

  • 품목마다 amount 또는 totalAmount 중 정확히 하나만 전송하세요. 둘 다 보내거나 둘 다 보내지 않으면 견적 산출이 실패합니다.
  • currencyCode는 소포마다 한 번 설정합니다. 소포의 모든 품목 가액에 이 통화가 사용됩니다.
  • gtin 없이 upc를 전송하면 UPC가 GTIN으로 사용됩니다.
  • 열거형 값은 일반 문자열입니다(예: "KILOGRAM").

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