주문 Preview API

POST /v1/orders/preview — 생성 전에 라인, 가격, 중국 내 운임을 검증합니다.

관련 문서: Create order · Response model

요청 본문

Taobao: Gateway가 mi_id + traffic sku_id를 자동으로 배치 확인한 뒤 upstream render를 호출합니다. lines[].id에는 최신 id / mi_id를 쓰세요. 주기적으로 바뀌므로 장기 캐시하지 마세요.

Line mapping

Prefer lines[].id = search/detail id. offer_id and mi_id remain compatible.

If both id and offer_id are sent, offer_id wins. Otherwise id (then mi_id) is copied to offer_id. Do not pass Taobao source_product_id. Taobao id / mi_id rotates periodically.

예시

POST /v1/orders/preview
{
  "channel": "1688",
  "receiver": {
    "name": "张三",
    "mobile": "15251667788",
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区",
    "address": "网商路699号"
  },
  "lines": [
    {
      "id": "554456348334",
      "spec_id": "b266e0726506185beaf205cbae88530d",
      "quantity": 5
    }
  ]
}

Taobao example

POST /v1/orders/preview
{
  "channel": "taobao",
  "receiver": {
    "name": "张三",
    "mobile": "15251667788",
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区",
    "address": "网商路699号"
  },
  "lines": [
    {
      "id": "0000iIpSgysC-ca00kbG-Y-LXZu7WojtOJ5cnKTyzoID9UM",
      "spec_id": "6079564221554",
      "quantity": 5
    }
  ]
}

응답

StandardOrderPreviewResult — order response models를 참고하세요. JSON 예시: Response format.

금액은 CNY fen 단위입니다. total에는 항상 merchandise, shipping, payment가 포함됩니다. 알려진 0은 amount:0인 Money 객체로 표시하며, null은 금액을 실제로 알 수 없을 때만 사용합니다.

주문 생성 전 success === true인지 확인하세요. Gateway는 양수 결제 총액, 판매자 그룹, 요청한 모든 라인, 구매 불가 라인, 그리고 1688의 경우 op_support:true인 거래 방식을 검증합니다. 해석 가능하지만 불완전한 결과는 HTTP 200, success:false와 LINE_UNAVAILABLE, UNSUPPORTED_TRADE_MODE, PREVIEW_INCOMPLETE 등의 code를 반환합니다.

호환성을 위해 1688이 명시적으로 반환하는 SKU, 재고, MOQ 및 마켓 제한 오류는 기존 HTTP 502 오류 envelope를 유지합니다. response_format:"upstream"은 원본 의미를 유지하므로 HTTP 200에도 upstream 비즈니스 실패가 포함될 수 있습니다. upstream payload를 확인하세요.

주문 preview는 읽기 전용 작업입니다. self 및 warehouse 구매 모드 모두에서 Gateway가 App에 해당하는 채널 토큰으로 marketplace preview/render API를 직접 호출합니다. warehouse 모드에서는 warehouse_channel_tokens를 사용하며 warehouse /procurement/preview로 전달하지 않습니다. create, detail, pay, cancel, logistics 작업은 계속 warehouse를 통해 처리됩니다.