注文プレビュー API

POST /v1/orders/preview — create の前に、明細、価格、国内送料を検証します。

関連: Create order · Response model

リクエスト本文

lines[].id の取り方 {#line-mapping}

1. POST /v1/products/detail（または search）を呼び出す
2. レスポンス id → lines[].id（Taobao では source_product_id 不可）
3. 選択 SKU の variants[].sku_id → lines[].spec_id
4. preview 成功後、create で 同じ lines[] を使う

Taobao: Gateway が mi_id + traffic sku_id を自動で一括チェックし、その後 upstream render を呼び出します。 lines[].id には新しい id / mi_id を使ってください。定期的に変わるため、長期キャッシュしないでください。

フィールド対応

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 が含まれます。既知のゼロは 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 のエラー形式です。response_format:"upstream" は生の意味を保持するため、HTTP 200 でも上流の業務エラーが含まれる場合があります。upstream payload を確認してください。

注文プレビューは読み取り専用です。self と warehouse のどちらの調達モードでも、Gateway は App に対応するチャネルトークンを使用して marketplace の preview/render API を直接呼び出します。warehouse モードでは warehouse_channel_tokens を使用し、preview を warehouse の /procurement/preview へ転送しません。create、detail、pay、cancel、logistics は引き続き warehouse 経由です。