API de consultas a proveedores

Estima el envío internacional antes de que el cliente compre

Para un sofá, una lámpara de pie, una cinta de correr o un transportín grande para mascotas, el coste del envío internacional depende casi por completo de cómo se embala realmente el artículo: su peso embalado, las dimensiones de la caja y en cuántos paquetes se envía.

Esos datos faltan o no son fiables de forma habitual en las páginas de producto de 1688 y Taobao. Lo que deja a tu cliente ante un problema muy práctico:

Sabe cuánto cuesta el producto. No tiene ni idea de cuánto cuesta llevarlo hasta su país.

La API de consultas a proveedores cierra esa brecha. El servicio de comunicación con proveedores de HIOBuy contacta con el proveedor real antes de la compra, confirma el peso embalado, las dimensiones del embalaje y los detalles de las cajas, y devuelve las respuestas a tu aplicación como datos estructurados, listos para alimentar una estimación de envío.

Por qué la API de productos no basta

Las API de productos te dan de forma fiable lo que el propio marketplace conoce: título, imágenes, precio, SKU, atributos, información de la tienda. Los datos logísticos son otra historia:

• no se publica ningún peso;
• el peso mostrado es el peso neto del producto, no el peso embalado;
• existen las dimensiones del producto, pero no las dimensiones una vez embalado;
• el peso lo escribió el vendedor y solo es orientativo;
• distintos SKU se embalan con pesos distintos;
• un artículo grande se envía repartido en varios paquetes;
• la cantidad de cajas, su peso y su tamaño no aparecen en ninguna parte de la página.

La API de productos te dice lo que sabe el marketplace. Una consulta al proveedor te consigue lo que solo el proveedor puede confirmar.

Ejemplo: estimar el envío de un sofá

Un cliente en Estados Unidos está mirando en tu aplicación un sofá de 1688 con un precio de ¥800. La API de productos ya ha devuelto el producto, el precio, las imágenes, los SKU y los atributos, pero ningún peso embalado ni dimensiones de embalaje fiables.

Así que tu aplicación no puede responder a la única pregunta que importa a continuación:

Precio del producto     ¥800
Envío internacional     ???

En un artículo voluminoso, esa incógnita puede superar con facilidad el precio del propio producto.

Tu aplicación crea una consulta:

POST /v1/supplier-inquiries
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "questions": [
    { "type": "packed_weight" },
    { "type": "package_dimensions" },
    { "type": "carton_info" }
  ]
}

HIOBuy entrega la tarea al servicio de comunicación con proveedores, y un operador ubicado en China contacta con el proveedor real de ese anuncio. El proveedor responde que el sofá se envía en dos paquetes:

Paquete 1   32 kg   110 × 75 × 55 cm
Paquete 2   18 kg    90 × 60 × 40 cm

Esas respuestas llegan a tu aplicación como JSON estructurado, y el recorrido completo se ve así:

Producto de 1688
      ↓  API de productos
Precio: ¥800
      ↓  faltan datos logísticos fiables
Consulta al proveedor
      ↓  HIOBuy contacta con el proveedor real
El proveedor confirma: 2 paquetes, 32 kg + 18 kg, dimensiones de las cajas
      ↓  datos logísticos estructurados
Estimación de envío internacional (China → Estados Unidos)
      ↓
El cliente ve un coste total aproximado antes de comprar

Que es el objetivo de todo el ejercicio:

Coste del producto
+ envío internacional estimado
= un coste realista antes de la compra

Dónde encaja dentro de las API de HIOBuy

API de productos       "¿Qué es el producto y cuánto cuesta?"
        ↓
API de consultas       "¿Cómo lo va a embalar realmente el proveedor?"
        ↓
Cotización de envío    "¿Cuánto costará aproximadamente enviarlo al extranjero?"

La consulta al proveedor es la capa que falta entre los datos del producto y una cotización de envío.

Más que datos de envío

Los datos de embalaje para estimar el envío son el uso primero y más concreto de esta API, pero el mismo canal de comunicación con el proveedor responde a cualquier cosa que solo él conoce:

MOQ · stock · plazo de producción · embalaje neutro · personalización · información de las cajas · detalles del producto · cualquier otra cosa, mediante el tipo other.

Así que hoy te da datos de embalaje → estimación de envío, y la misma llamada puede servir igualmente para información del proveedor → decisión de compra. Consulta los tipos de pregunta para ver los diez y sus esquemas de respuesta.

Cómo funciona

1. Tu aplicación llama a POST /v1/supplier-inquiries con una URL de producto, un SKU opcional y una o más preguntas tipadas.
2. HIOBuy crea la consulta y la entrega al servicio de comunicación con proveedores.
3. Un operador ubicado en China contacta con el proveedor de ese anuncio.
4. El proveedor responde.
5. La respuesta se normaliza en datos estructurados conforme al esquema de cada tipo de pregunta.
6. Tu endpoint recibe el webhook supplier_inquiry.message_answered, o bien consultas GET /v1/supplier-inquiries/{id}.

Una consulta es una conversación, no una petición puntual. Una vez creada, añades mensajes de seguimiento al mismo hilo en lugar de abrir uno nuevo.

Adjuntos

Algunas preguntas son mucho más fáciles de plantear con una imagen. Una referencia de embalaje, una captura de pantalla de un SKU, un croquis con medidas, una ficha técnica; y en el otro sentido, la foto de embalaje del propio proveedor, la foto de una caja o un presupuesto en PDF.

Cada mensaje, el tuyo y el del proveedor, puede llevar hasta cinco adjuntos:

{
  "message": "Please ask the supplier whether they can use packaging similar to this.",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/reference-packaging.jpg",
      "filename": "reference-packaging.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

type es image, document u other. La URL debe ser https://; cualquier otra cosa se rechaza con INVALID_ATTACHMENT_URL.

Las respuestas del proveedor también pueden incluir adjuntos. Llegan en el array attachments del mensaje y en el webhook supplier_inquiry.message_answered, junto a las respuestas estructuradas. Solo ves los adjuntos que el servicio de consultas marcó como destinados a ti: los archivos de trabajo de los operadores y las capturas de pantalla de los chats con el proveedor quedan internos al servicio y nunca llegan a la API.

Acceso

Las consultas a proveedores están desactivadas por defecto. HIOBuy las habilita por aplicación tras la incorporación comercial; contacta con el soporte de HIOBuy para solicitar acceso.

Si la capacidad no está concedida o está suspendida, todos los endpoints devuelven 403 SUPPLIER_INQUIRY_NOT_ENABLED.

Marketplaces admitidos

Cualquier otro caso falla con UNSUPPORTED_MARKETPLACE. Un producto se identifica por channel + source_product_id, nunca por la cadena de la URL original, de modo que distintas formas de enlace de la misma oferta resuelven al mismo producto.

Estados de una consulta

pending, processing, waiting_supplier y answered cuentan como activos. Una aplicación solo puede mantener una consulta activa por producto: así se garantiza un único hilo con el proveedor por oferta. Enviar una petición de creación para un producto cuya consulta esté en completed o failed reabre esa conversación en lugar de crear una nueva.

Webhooks

Registra un endpoint en el portal de desarrolladores y suscríbete a la categoría supplier_inquiry. La firma y los reintentos siguen las reglas estándar de webhooks.

Todos los payloads incluyen inquiry_id y product.{channel,source_product_id}.

Códigos de error

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE es genérico de forma deliberada: no se exponen motivos del lado del proveedor del servicio, como el saldo o el estado de la cuenta. Indica el request_id al contactar con soporte.

Endpoints