Catalog API

Catalog API는 Verified Account 카탈로그를 구축하는 세 가지 방법 중 하나로, 개발 인력이 있고 이미 제품 데이터를 보유한 시스템(ERP, WMS, PIM 또는 배송 플랫폼)을 갖춘 배송업체를 위한 옵션입니다. 해당 시스템이 기준 데이터(source of truth)로 유지되며, 채널 연동에서 동기화하거나 CSV 파일을 업로드하는 대신 Zonos에 제품을 직접 기록합니다. 지원되는 채널을 통해 판매하거나 코드를 작성하고 싶지 않다면, 이 두 가지 옵션으로 더 적은 작업으로 동일한 카탈로그를 구축할 수 있습니다.

API로 생성한 품목은 다른 방식으로 추가한 품목과 완전히 동일하게 처리됩니다. 품목이 카탈로그에 들어오면 Zonos는 어떤 경로로 추가되었는지 구분하지 않습니다. HS 코드를 제공하지 않은 경우 각 품목은 통관을 위해 분류되고, 미국 PGA(Partner Government Agency) 요건에 대해 심사되며, 해당 품목이 포함된 배송물의 관세 및 세금 계산에 사용됩니다.

이 중 한 부분은 API 밖에서 처리됩니다. PGA 심사에서 품목에 조치 필요 플래그가 지정되면, 해당 플래그와 연결된 규정 준수 질문지는 Dashboard에서 답변하고 확인해야 합니다. 이를 위한 API는 없으며, Zonos가 가능한 항목을 미리 채워 두므로 대부분의 작업은 검토하고 확인하는 것입니다. 이 연동을 구축하는 사람과 해당 플래그를 처리하는 사람은 대개 다르므로, 카탈로그가 로드된 후 조직 내 누군가가 Dashboard에서 이를 처리하도록 계획하세요. 플래그가 지정된 품목도 배송이 차단되지는 않지만, 배송 전에 플래그를 해소해야 미국 국경에서 배송물이 보류되는 것을 막을 수 있습니다.

작동 방식 

1. 배송하는 각 제품에 대해 카탈로그 품목을 생성합니다.

2. 각 품목에 우편 운송사가 전달할 식별자가 포함되어 있는지 확인합니다.

3. 배송 데이터가 Zonos에 도달하면 각 항목이 카탈로그 품목과 매칭되고, 해당 품목의 제품 데이터가 계산에 적용됩니다.

카탈로그 품목 생성 

catalogItemCreate는 목록을 입력으로 받으므로 한 번의 요청으로 여러 제품을 보낼 수 있습니다.

동일한 제품을 두 번 보내는 경우

이미 존재하는 SKU 또는 product ID를 가진 제품을 보내면, Zonos는 새 제품을 추가하지 않고 해당 제품을 업데이트합니다. 따라서 재시도와 반복 실행은 안전합니다.

반대로, SKU 또는 product ID가 같은 서로 다른 두 제품은 하나로 병합됩니다. 대량으로 등록하기 전에 데이터에 중복이 없는지 확인하세요.

필드

품목을 매칭 가능하게 만들기 

Zonos는 식별자를 사용해 각 배송 항목을 카탈로그 품목과 연결하며, 그 순서는 product ID, SKU, name입니다. 어떤 식별자를 사용하든 카탈로그와 운송사에 보내는 데이터 간에 정확하고 일관되게 유지하세요.

우편 배송에는 추가 제약이 있습니다. Zonos는 우편 운송사로부터 제한된 필드만 전달받으며, 많은 경로에서 제품별 정보를 담은 필드는 세관 설명뿐입니다. 카탈로그 전체에서 동일한 설명은 그 자체로는 어떤 제품도 식별할 수 없습니다.

운송사에 보내는 세관 설명을 product ID 또는 SKU로 시작하세요.

123456 - Men's bifold wallet, cowhide leather

식별자는 해당 카탈로그 품목의 productId 또는 sku와 정확히 일치해야 합니다.

설명 필드는 짧습니다. 예를 들어 Canada Post 제출 시에는 약 49자까지만 허용되므로, 식별자가 길다면 설명 부분을 줄이세요. 설명 문구보다 식별자가 더 중요합니다. 일부 우편 운송사는 긴 설명을 잘라냅니다. 식별자를 맨 앞에 두면 설명 부분만 잘리며, Zonos는 여전히 식별자를 카탈로그 품목과 매칭해 전체 설명을 가져올 수 있습니다.

품목의 customsDescription을 운송사에 보내는 문자열과 동일하게 설정할 필요는 없지만, 그렇게 하면 항목이 매칭되지 않아 원인을 파악해야 할 때 양쪽을 직접 비교할 수 있습니다.

매칭은 주로 다음과 같은 경우에 실패합니다:

• 설명에 식별자가 없는 경우
• 식별자가 카탈로그의 어떤 productId 또는 sku와도 일치하지 않는 경우
• 운송사의 글자 수 제한으로 식별자가 잘린 경우
• 배송마다 형식이 달라지는 경우

이 동작은 아직 확정되지 않았으며 출시 전에 변경될 수 있습니다.

카탈로그 품목 업데이트 

catalogItemUpdate는 생성과 동일한 입력 타입을 사용합니다. 변경하려는 필드만 보내세요.

참고: 생략한 필드는 변경되지 않으므로 부분 업데이트가 안전합니다. null을 보내도 값이 지워지지 않으며 무시됩니다. 값을 다른 값으로 덮어쓸 수는 있지만 API로 비울 수는 없습니다. 필드를 비워야 하는 경우 Zonos 담당자에게 문의하세요.

품목 다시 조회하기 

catalogItem 쿼리는 id, productId 또는 sku를 받습니다. Zonos가 제품에 대해 보유한 정보를 확인할 때 사용하세요.

카탈로그 품목 삭제 

catalogItemDelete는 SKU나 product ID가 아닌 Zonos 카탈로그 품목 ID를 받습니다. 먼저 catalogItem 쿼리로 ID를 확인하세요.

관련 문서 

• 채널 연동 — 지원되는 판매 채널에서 카탈로그를 자동으로 동기화합니다.
• CSV 가져오기 — 코드를 작성하는 대신 스프레드시트로 카탈로그 품목을 업로드합니다.
• PGA 심사 — 카탈로그 품목이 미국 정부 기관(PGA) 요건을 충족하는지 심사합니다.
• Catalog 작동 방식 — Zonos가 제품 데이터를 어떻게 활용하는지 알아봅니다.