응답 형식

HIOBuy Public API의 일부 POST 라우트는 두 가지 응답 형태를 지원합니다. JSON 본문에 선택적 response_format을 지정할 수 있습니다.

한눈에 보기

기본값은 standard입니다. response_format을 생략하거나 "response_format": "standard"를 사용하세요.

	`standard` (권장)	`upstream`
반환 내용	HIOBuy 통합 모델 — 채널 간 동일 JSON 구조	업스트림 제공자 원본 JSON (1688 Open API, Taobao IOP 등)
필드 매핑	HIOBuy Gateway가 처리	없음 — 벤더 공식 문서와 동일
1688 vs Taobao	동일 엔드포인트 → 동일 구조	채널마다 다른 업스트림 JSON
용도	프로덕션 통합, 멀티 채널	공식 문서 대조, 디버깅, 마이그레이션

권장: 일반 통합은 **standard**를 사용하세요. 업스트림 네이티브 payload가 필요할 때만 **upstream**을 사용합니다.

모드

값	설명
`standard` (기본값)	HIOBuy 정규화 타입 — `StandardProductDetail`, `StandardOrderPreviewResult` 등. `channel`이 `1688`이든 `taobao`든 동일 구조.
`upstream`	업스트림 패스스루 — 1688 / Taobao 공식 JSON을 `upstream`에 반환. HIOBuy 매핑 없음.

Upstream envelope

response_format이 upstream이면:

{
  "channel": "1688",
  "response_format": "upstream",
  "upstream_api": "com.alibaba.fenxiao.crossborder/product.search.keywordQuery",
  "upstream": {
    "result": {
      "success": true
    }
  },
  "upstream_steps": [],
  "request_id": "req_abc123"
}

upstream_api — 기본 벤더 API 식별자(1688 path 또는 Taobao IOP route)
upstream — 해당 호출의 원본 HTTP JSON 본문
upstream_steps — 선택적 선행 호출(예: 이미지 검색 전 이미지 업로드)

Standard preview 응답 {#standard-preview}

POST /v1/orders/preview(1688 및 Taobao)는 standard 모드에서 StandardOrderPreviewResult를 반환합니다. 금액은 fen(CNY cents) 단위입니다. 필드 참조: Procurement orders.

{
  "channel": "taobao",
  "success": true,
  "total": {
    "payment": {
      "amount": 12900,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 0,
      "currency": "CNY"
    }
  },
  "unavailable_lines": [],
  "sellers": [
    {
      "seller_id": "...",
      "lines": [
        {
          "offer_id": "...",
          "spec_id": "...",
          "quantity": 5
        }
      ]
    }
  ],
  "request_id": "req_..."
}

1688은 trade_types, pay_channels, promotions를 추가합니다. response_format: "upstream"을 사용하면 preview는 원본 벤더 JSON을 반환합니다.

상품 라우트

엔드포인트	채널	Upstream API(예시)
`POST /v1/products/detail`	1688, taobao	`queryProductDetail` / `/traffic/item/get`
`POST /v1/products/search`	1688, taobao	`keywordQuery` / `/traffic/item/search`
`POST /v1/products/search-by-image`	1688, taobao	upload + `imageQuery` / upload + `/traffic/item/imgsearch`

POST /v1/products/parse는 항상 standard만 반환합니다. POST /v1/products/freight/estimate는 주문 preview와 동일한 본문을 사용하며 배송비만 반환합니다.

주문 라우트(1688 및 Taobao)

엔드포인트	Standard	Upstream API(예시)
`POST /v1/orders/list`	✓	`alibaba.trade.getBuyerOrderList`
`POST /v1/orders/1688/preview`	✓	`alibaba.createOrder.preview`
`POST /v1/orders/1688/create`	✓	`alibaba.trade.createCrossOrder`
`POST /v1/orders/preview`	✓	`channel`에 따라 dispatch(1688 / taobao)
`POST /v1/orders/create`	✓	`channel`에 따라 dispatch
`POST /v1/orders/taobao/preview`	✓	`/purchase/order/render`
`POST /v1/orders/taobao/create`	✓	`/purchase/order/create`
`POST /v1/orders/cancel`	✓	`alibaba.trade.cancel`
`POST /v1/orders/pay`	✓	`channel`에 따라 dispatch
`POST /v1/orders/detail`	✓	`order_id`로 주문 상세 조회
`POST /v1/orders/logistics/trace`	✓	중국 내 물류 추적
`POST /v1/orders/purchase/query`	✓	Taobao 구매 목록

예시 — upstream search

curl https://api.hiobuy.com/v1/products/search \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "response_format": "upstream",
    "channel": "1688",
    "keyword": "phone case",
    "page": 1,
    "page_size": 10,
    "language": "en"
  }'

검증

유효하지 않은 값(예: vendor_raw)은 HTTP 400과 VALIDATION_ERROR를 반환합니다. Errors를 참고하세요.

OpenAPI

머신 판독 사양: openapi.json (스키마 UpstreamApiResponse, UpstreamStep).

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support