HIOBuy 오픈 플랫폼

HIOBuy는 Taobao, 1688, Weidian의 공식 인증 기술 파트너입니다. HIOBuy는 중국 공급원을 하나의 통합 API로 여러분의 플랫폼에 연결합니다. 단순한 상품 데이터뿐 아니라 카탈로그 동기화부터 자동 구매, 그리고 선택적으로 국제 배송까지 전체 흐름을 제공합니다.

HIOBuy가 제공하는 것

일반적인 마켓플레이스 스크레이퍼나 읽기 전용 데이터 피드와 달리 HIOBuy는 end-to-end fulfillment를 중심으로 설계되었습니다. 연동은 여러분의 스토어프런트와 HIOBuy 구매 API를 통해 실제 거래를 만들어야 합니다.

다이어그램(HIOBuy가 중국 공급원을 여러분의 플랫폼에 연결: 상품 동기화, 주문 수신, 자동 구매, 상태 동기화)

HIOBuy는 중국 마켓플레이스와 여러분의 비즈니스 사이에서 상품을 동기화하고, 주문을 수신하며, 자동 구매를 수행하고, 상태를 대시보드로 다시 전달합니다.

기능	여러분에게 의미하는 것
Product sync	`/v1/products/*`를 통해 1688, Taobao, Weidian의 검색, 상세, 이미지 검색, SKU/재고/가격을 동기화
Order receiving	사이트에서 판매가 발생하면 백엔드가 고객 주문을 HIOBuy로 전송
Auto purchasing	HIOBuy가 `/v1/orders/*`를 통해 공급 마켓플레이스에 대응 주문을 생성
Status sync	구매 진행 상황, 중국 내 물류, 그리고 창고 모드의 국제 추적이 여러분 시스템으로 돌아옴 — Webhooks 참고
International fulfillment	선택 사항: `/v1/fulfillment/*`를 통해 창고 입고 소포를 해외로 발송(창고 모드 전용)

다른 API와의 차이

공식 채널 접근 — 비공식 스크레이핑이 아니라 인증된 파트너 연동입니다.
거래 중심 — 상품 API는 소싱과 체크아웃을 지원하고, 구매 API는 구매 루프를 완료합니다.
통합 표준 응답 — 1688, Taobao, Weidian 전반에 하나의 스키마를 사용합니다. Response format 참고.
선택적 풀스택 풀필먼트 — 자체 물류를 운영하는 구매자를 위한 self mode와 HIOBuy가 보관 및 국제 배송을 처리하는 warehouse mode를 제공합니다.

허용 사용 및 쿼터 {#acceptable-use}

API 접근은 무제한이 아닙니다. 쿼터와 속도 제한은 상업 계약 및 플랫폼을 통한 예상 **거래량(GMV)**과 연결됩니다.

HIOBuy는 상품 탐색이 실제 주문으로 이어지는 연동을 위한 서비스입니다. 고객이 여러분 사이트에서 구매하고, 백엔드가 /v1/orders/*를 호출해 구매를 진행해야 합니다. 의미 있는 구매 활동 없이 상품 검색/상세만 소비하거나, HIOBuy 카탈로그 API를 사용하면서 구매는 HIOBuy를 우회하는 애플리케이션은 지원되지 않으며 검토 후 중단될 수 있습니다.

기술적인 rate-limit 헤더와 오류 코드는 Rate limits에 문서화되어 있습니다. 상업 조건은 온보딩 중 합의되며 개별 엔드포인트 페이지에 반복하지 않습니다.

연동 흐름 {#integration-flows}

앱을 인증할 때 developer portal에서 fulfillment 모드를 선택하세요. 상품 API 경로는 유사하지만 구매와 국제 배송 방식이 다릅니다.

Self fulfillment — 직접 구매를 운영

이미 마켓플레이스 계정이 있고 창고 운영을 직접 처리하는 경우에 적합합니다.

상품 동기화 — 1688 / Taobao / Weidian → HIOBuy Gateway: search, detail, images, SKU, stock
표시 — HIOBuy Gateway → 여러분의 스토어프런트
고객 주문 — 고객 → 여러분의 웹사이트
구매 — 여러분의 백엔드 → HIOBuy Gateway: POST /v1/orders/preview → create → pay
자동 구매 — HIOBuy Gateway → Marketplace(여러분의 OAuth)
상태 반환 — Marketplace → HIOBuy Gateway: purchase & domestic logistics
대시보드 동기화 — HIOBuy Gateway → 여러분의 대시보드

Self mode에서는 국제 배송(/v1/fulfillment/*)을 사용할 수 없습니다. 해외 배송은 직접 처리합니다.

HIOBuy warehouse fulfillment — end-to-end

하나의 창고 코드가 모든 채널을 연결하며, HIOBuy가 구매, 보관, 국제 배송을 처리합니다.

Product APIs — 여전히 마켓플레이스에 직접 호출(저지연)
상품 동기화 — 고객에게 보이는 사이트로 동기화
고객 주문 — 여러분의 웹사이트에서 발생
구매 — POST /v1/orders/*(HIOBuy warehouse로 전달)
자동 구매 — HIOBuy warehouse → Marketplace, 관리형 토큰 사용
입고 — 상품 도착, 주문 상세에 parcel_nos 표시
국제 배송 — freight/estimate → preview → create → pay
배송 — /v1/fulfillment/shipments/logistics/trace로 추적

구매와 국제 API는 HIOBuy를 통해 라우팅됩니다. Product API는 속도를 위해 플랫폼에 직접 호출됩니다.

모드 비교

	Self fulfillment	HIOBuy warehouse
채널 토큰	채널별 OAuth를 직접 관리	하나의 창고 코드가 모든 채널 연결
`/v1/products/*`	Gateway → marketplace	Gateway → marketplace(직접, 저지연)
`/v1/orders/*`	Gateway → marketplace(사용자 토큰)	Gateway → HIOBuy warehouse API
`/v1/fulfillment/*`	사용 불가	국제 배송 + 잔액

개발자가 되는 방법 {#become-a-developer}

회사, 웹사이트, 사용 사례(예: 구매대행, 크로스보더 스토어)로 등록합니다.
이메일 주소를 확인합니다.
로그인한 뒤 개발자 포털에서 App을 생성하고 연동 방식과 예상 트래픽을 설명합니다.
HIOBuy review를 기다립니다. 거래 기반 소싱에 맞는 앱을 승인하며, 이에 따라 쿼터와 채널 접근 권한을 받습니다.
승인 후: authorize channels(self OAuth 또는 창고 코드) 후 API Keys에서 API 키를 생성합니다.
연동: 상품 상세 → 고객 체크아웃 → 구매 preview/create → pay → 상태 webhooks. 창고 모드에서는 국제 배송 흐름을 추가합니다.

창고 개발자 코드가 필요하신가요? 앱이 warehouse fulfillment로 승인된 뒤 HIOBuy 운영팀에 문의하세요.

API 참조 맵

Base URL: https://api.hiobuy.com/v1

영역	Prefix	문서
Products	`/v1/products/*`	Products
Procurement	`/v1/orders/*`	Procurement orders
Fulfillment	`/v1/fulfillment/*`	Shipments & balance

두 가지 주문 유형을 혼동하지 마세요: procurement(/v1/orders/*)는 중국 판매자에게서 구매해 중국 내 창고로 보내는 과정이고, international shipment(/v1/fulfillment/shipments/*)는 입고된 소포를 해외로 보내는 과정입니다.

권장 읽기 순서 {#reading-order}

Become a developer — 등록, 앱 승인, API 키
Authentication + Portal authorization
Products → Procurement orders
선택 사항: Fulfillment(창고 모드)
프로덕션 안정화 시 Errors & Rate limits

Public API 범위 {#public-api-scope}

이 문서는 지원되는 Public API surface를 설명합니다. 일부 경로는 내부 또는 사용 중단 용도(예: legacy /v1/shipments, refund routes)로 openapi.json 에 나타날 수 있습니다. 여기에 나열되지 않은 엔드포인트는 사용할 수 없는 것으로 간주하세요.

기술 규칙 {#technical-conventions}

Auth: Authorization: Bearer YOUR_API_KEY — Authentication
JSON 본문의 Product language — Languages
가격: 상품은 CNY yuan, 주문과 배송은 fen
response_format: "standard"(기본값) 또는 "upstream" — Response format

OpenAPI spec: api.hiobuy.com/openapi.json

Published documentation: hiobuy.com/api-docs