Formato de respuesta

Las rutas POST compatibles aceptan un campo opcional response_format en el cuerpo JSON. Omítelo o usa standard para los modelos unificados predeterminados de HIOBuy.

Modos

Valor	Descripción
`standard` (predeterminado)	Tipos normalizados: `StandardProductDetail`, `StandardProductList`, `StandardOrderPreviewResult`, etc.
`upstream`	Paso directo del proveedor: JSON oficial de 1688 Open API o Taobao IOP en `upstream`, sin mapeo de campos.

Envoltorio upstream

Cuando response_format es 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: identificador principal de la API del proveedor (ruta de 1688 o ruta Taobao IOP)
upstream: cuerpo JSON HTTP sin procesar de esa llamada
upstream_steps: llamadas previas opcionales (por ejemplo, carga de imagen antes de búsqueda por imagen)

Respuesta preview estándar {#standard-preview}

POST /v1/orders/preview (1688 y Taobao) devuelve StandardOrderPreviewResult en modo standard. Los importes están en fen (centavos CNY). Referencia de campos: Pedidos de compra.

{
  "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 añade trade_types, pay_channels y promotions. Con response_format: "upstream", preview devuelve en su lugar el JSON sin procesar del proveedor.

Rutas de producto

Endpoint	Canales	API upstream (ejemplos)
`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 siempre devuelve solo standard. POST /v1/products/freight/estimate usa el mismo cuerpo que order preview y devuelve solo el envío.

Rutas de pedido (1688 y Taobao)

Endpoint	Estándar	API upstream (ejemplos)
`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`	✓	Despacha por `channel` (1688 / taobao)
`POST /v1/orders/create`	✓	Despacha por `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`	✓	Despacha por `channel`
`POST /v1/orders/detail`	✓	Detalle de pedido por `order_id`
`POST /v1/orders/logistics/trace`	✓	Trazabilidad logística nacional
`POST /v1/orders/purchase/query`	✓	Lista de compras de Taobao

Ejemplo: búsqueda 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"
  }'

Validación

Los valores inválidos (por ejemplo, vendor_raw) devuelven HTTP 400 con VALIDATION_ERROR. Consulta Errores.

OpenAPI

Especificación legible por máquina: openapi.json (esquemas UpstreamApiResponse, UpstreamStep).