Format de réponse

Les routes POST prises en charge acceptent un champ optionnel response_format dans le corps JSON. Omettez-le ou utilisez standard pour les modèles unifiés HIOBuy par défaut.

Modes

Valeur	Description
`standard` (par défaut)	Types normalisés — `StandardProductDetail`, `StandardProductList`, `StandardOrderPreviewResult`, etc.
`upstream`	Transmission fournisseur — JSON officiel 1688 Open API ou Taobao IOP dans `upstream`, sans mapping de champs.

Enveloppe upstream

Lorsque response_format vaut 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 — identifiant principal de l’API fournisseur (chemin 1688 ou route Taobao IOP)
upstream — corps JSON HTTP brut de cet appel
upstream_steps — appels précédents optionnels (par ex. téléversement d’image avant recherche par image)

Réponse de prévisualisation standard {#standard-preview}

POST /v1/orders/preview (1688 et Taobao) retourne StandardOrderPreviewResult en mode standard. Les montants sont en fen (centimes CNY). Référence des champs : Commandes d’approvisionnement.

{
  "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 ajoute trade_types, pay_channels et promotions. Avec response_format: "upstream", la prévisualisation retourne plutôt le JSON fournisseur brut.

Routes produit

Endpoint	Canaux	API upstream (exemples)
`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 retourne toujours uniquement standard. POST /v1/products/freight/estimate utilise le même corps que la prévisualisation de commande et retourne seulement les frais d’expédition.

Routes commande (1688 et Taobao)

Endpoint	Standard	API upstream (exemples)
`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`	✓	Dispatch selon `channel` (1688 / taobao)
`POST /v1/orders/create`	✓	Dispatch selon `channel`
`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`	✓	Dispatch selon `channel`
`POST /v1/orders/detail`	✓	Détail de commande par `order_id`
`POST /v1/orders/logistics/trace`	✓	Suivi logistique domestique
`POST /v1/orders/purchase/query`	✓	Liste d’achats Taobao

Exemple — recherche upstream

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"
  }'

Validation

Les valeurs invalides (par ex. vendor_raw) retournent HTTP 400 avec VALIDATION_ERROR. Voir Erreurs.

OpenAPI

Spécification lisible par machine : openapi.json (schémas UpstreamApiResponse, UpstreamStep).