공급업체 문의 API

고객이 구매하기 전에 국제 배송비를 추정하세요

소파, 플로어 램프, 러닝머신, 대형 반려동물 케이지 같은 상품의 국제 배송비는 사실상 실제 포장 상태로 결정됩니다. 포장 중량, 박스 규격, 그리고 몇 개의 포장으로 나뉘어 발송되는지가 전부입니다.

그런데 이 데이터는 1688과 타오바오 상품 페이지에 아예 없거나 신뢰하기 어려운 경우가 대부분입니다. 그래서 고객은 아주 현실적인 문제에 부딪힙니다.

상품 가격은 알지만, 그 상품을 자기 나라까지 가져오는 데 얼마가 드는지는 전혀 알 수 없습니다.

공급업체 문의 API는 바로 이 간극을 메웁니다. HIOBuy의 공급업체 커뮤니케이션 서비스가 구매 전에 실제 공급업체에 연락해 포장 중량, 포장 규격, 카톤 정보를 확인하고, 그 답변을 배송비 추정에 바로 활용할 수 있는 구조화된 데이터로 애플리케이션에 돌려줍니다.

상품 API만으로는 부족한 이유

상품 API는 마켓플레이스가 알고 있는 정보, 즉 제목, 이미지, 가격, SKU, 속성, 상점 정보를 안정적으로 제공합니다. 하지만 물류 데이터는 이야기가 다릅니다.

• 중량 정보가 아예 게시되어 있지 않습니다.
• 표시된 중량이 포장 중량이 아니라 상품 순중량입니다.
• 상품 치수는 있지만 포장 후 규격은 없습니다.
• 중량을 판매자가 직접 입력한 값이라 참고용에 불과합니다.
• SKU마다 포장 중량이 다릅니다.
• 대형 상품은 여러 개의 포장으로 나뉘어 발송됩니다.
• 카톤 수량, 카톤 중량, 카톤 규격은 페이지 어디에도 없습니다.

상품 API는 마켓플레이스가 아는 것을 알려주고, 공급업체 문의는 공급업체만 확인해 줄 수 있는 것을 가져옵니다.

예시: 소파의 배송비 추정하기

미국에 있는 고객이 여러분의 앱에서 ¥800짜리 1688 소파를 보고 있습니다. 상품 API는 이미 상품, 가격, 이미지, SKU, 속성을 반환했지만 신뢰할 수 있는 포장 중량이나 포장 규격은 없습니다.

그래서 앱은 다음에 이어질 가장 중요한 질문에 답할 수 없습니다.

상품 가격   ¥800
국제 배송비 ???

부피가 큰 상품에서는 이 미지수가 상품 가격 자체를 쉽게 넘어설 수 있습니다.

앱이 문의를 생성합니다.

POST /v1/supplier-inquiries
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "questions": [
    { "type": "packed_weight" },
    { "type": "package_dimensions" },
    { "type": "carton_info" }
  ]
}

HIOBuy가 이 작업을 공급업체 커뮤니케이션 서비스에 전달하고, 중국 현지 담당자가 해당 상품의 실제 공급업체에 연락합니다. 공급업체는 소파가 두 개의 포장으로 발송된다고 회신합니다.

포장 1   32 kg   110 × 75 × 55 cm
포장 2   18 kg    90 × 60 × 40 cm

이 답변은 구조화된 JSON으로 애플리케이션에 돌아오며, 전체 흐름은 다음과 같습니다.

1688 상품
      ↓  상품 API
가격: ¥800
      ↓  신뢰할 수 있는 물류 데이터 없음
공급업체 문의
      ↓  HIOBuy가 실제 공급업체에 연락
공급업체 확인: 포장 2개, 32 kg + 18 kg, 박스 규격
      ↓  구조화된 물류 데이터
국제 배송비 추정 (중국 → 미국)
      ↓
고객은 구매 전에 대략적인 총비용을 확인

이것이 이 모든 과정의 목적입니다.

상품 비용
+ 국제 배송비 추정치
= 현실적인 구매 전 비용

HIOBuy API에서의 위치

상품 API             "이 상품은 무엇이고 가격은 얼마인가?"
        ↓
공급업체 문의 API     "공급업체는 실제로 어떻게 포장하는가?"
        ↓
배송비 견적          "국제 배송에 대략 얼마가 드는가?"

공급업체 문의는 상품 데이터와 배송비 견적 사이에 빠져 있던 계층입니다.

배송 데이터를 넘어서

배송비 추정을 위한 포장 데이터는 이 API의 가장 첫 번째이자 가장 구체적인 활용 사례이지만, 동일한 공급업체 커뮤니케이션 채널로 공급업체만 알 수 있는 모든 것을 물어볼 수 있습니다.

MOQ · 재고 · 리드타임 · 중립 포장 · 커스터마이징 · 카톤 정보 · 상품 상세, 그리고 other 타입을 통한 그 밖의 모든 질문.

즉 오늘은 포장 데이터 → 배송비 추정을 제공하지만, 같은 호출로 공급업체 정보 → 구매 의사결정도 똑같이 지원합니다. 전체 열 가지 유형과 각 답변 스키마는 질문 유형을 참고하세요.

동작 방식

1. 애플리케이션이 상품 URL, 선택적 SKU, 하나 이상의 타입이 정의된 질문을 담아 POST /v1/supplier-inquiries를 호출합니다.
2. HIOBuy가 문의를 생성하고 공급업체 커뮤니케이션 서비스에 전달합니다.
3. 중국 현지 담당자가 해당 상품의 공급업체에 연락합니다.
4. 공급업체가 회신합니다.
5. 회신은 각 질문 유형의 스키마에 맞춰 구조화된 데이터로 정규화됩니다.
6. 등록한 엔드포인트로 supplier_inquiry.message_answered 웹훅이 전송되거나, GET /v1/supplier-inquiries/{id}를 폴링할 수 있습니다.

문의는 일회성 요청이 아니라 하나의 대화입니다. 문의가 생성된 뒤에는 새 문의를 여는 대신 같은 스레드에 후속 메시지를 계속 추가합니다.

첨부 파일

어떤 질문은 사진 한 장이 있으면 훨씬 쉽게 전달됩니다. 포장 참고 이미지, SKU 스크린샷, 치수 도면, 사양서 — 반대 방향으로는 공급업체가 직접 찍은 포장 사진, 카톤 사진, 견적서 PDF 같은 것들입니다.

여러분이 보내는 메시지와 공급업체가 보내는 메시지 모두 최대 5개의 첨부 파일을 담을 수 있습니다.

{
  "message": "Please ask the supplier whether they can use packaging similar to this.",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/reference-packaging.jpg",
      "filename": "reference-packaging.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

type은 image, document, other 중 하나입니다. URL은 반드시 https://여야 하며, 그 외의 값은 INVALID_ATTACHMENT_URL로 거부됩니다.

공급업체의 회신에도 첨부 파일이 포함될 수 있습니다. 이러한 파일은 메시지의 attachments 배열과 supplier_inquiry.message_answered 웹훅에 구조화된 답변과 함께 도착합니다. 문의 서비스가 여러분에게 공개하기로 표시한 첨부 파일만 볼 수 있으며, 담당자의 작업용 파일이나 공급업체 채팅 스크린샷은 서비스 내부에 남고 API로 전달되지 않습니다.

이용 조건

공급업체 문의는 기본적으로 비활성화되어 있습니다. HIOBuy는 상업적 온보딩을 마친 뒤 애플리케이션 단위로 기능을 활성화합니다. 이용을 원하시면 HIOBuy 지원팀에 문의하세요.

기능이 활성화되지 않았거나 정지된 경우 모든 엔드포인트는 403 SUPPLIER_INQUIRY_NOT_ENABLED를 반환합니다.

지원 마켓플레이스

그 외의 링크는 UNSUPPORTED_MARKETPLACE로 실패합니다. 상품은 원본 URL 문자열이 아니라 channel + source_product_id 조합으로 식별되므로, 같은 상품을 가리키는 형태가 다른 링크는 모두 동일한 상품으로 처리됩니다.

문의 상태

pending, processing, waiting_supplier, answered는 활성 상태로 간주됩니다. 하나의 애플리케이션은 상품당 활성 문의를 하나만 보유할 수 있으며, 이를 통해 상품별 공급업체 스레드가 하나로 유지됩니다. 문의가 completed 또는 failed 상태인 상품에 생성 요청을 보내면 새 문의를 만드는 대신 해당 대화를 다시 엽니다.

웹훅

개발자 포털에서 엔드포인트를 등록하고 supplier_inquiry 카테고리를 구독하세요. 서명과 재시도는 표준 웹훅 규칙을 따릅니다.

모든 페이로드에는 inquiry_id와 product.{channel,source_product_id}가 포함됩니다.

오류 코드

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE은 의도적으로 포괄적인 코드입니다. 잔액이나 계정 상태 같은 제공자 측 사유는 노출되지 않습니다. 지원팀에 문의할 때는 request_id를 함께 알려주세요.

엔드포인트