Crear una consulta a proveedor

Dos endpoints escriben en una conversación con el proveedor: uno la inicia y otro la continúa. Ambos reciben el mismo array questions y ambos aceptan una Idempotency-Key.

Crear una consulta

POST /v1/supplier-inquiries — ámbito supplier_inquiry:write.

Cuerpo de la petición

Campo	Obligatorio	Descripción
`product_url`	Sí	Enlace absoluto a un producto de 1688 o Taobao, máximo 2048 caracteres
`questions`	Sí	Entre 1 y 10 preguntas, consulta los tipos de pregunta
`sku`	No	`{ "id": "...", "label": "..." }`, 200 caracteres cada uno: limita la pregunta a una variante
`attachments`	No	Hasta 5 referencias de archivos, consulta adjuntos

POST /v1/supplier-inquiries
Authorization: Bearer hio_live_...
Idempotency-Key: inq-2026-05-20-001
 
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "sku": { "id": "3245:12345", "label": "Negro / XL" },
  "questions": [
    { "type": "packed_weight", "note": "Peso con la caja de venta al público" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

Respuesta

201 Created, o 200 OK cuando una Idempotency-Key repite una petición anterior.

{
  "id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "product_url": "https://detail.1688.com/offer/554456348334.html",
    "canonical_product_url": "https://detail.1688.com/offer/554456348334.html",
    "title": "...",
    "image": "...",
    "shop_id": "...",
    "shop_name": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "Negro / XL"
  },
  "message_count": 1,
  "last_message_at": "2026-05-20T08:31:12.000Z",
  "created_at": "2026-05-20T08:31:11.000Z",
  "updated_at": "2026-05-20T08:31:12.000Z",
  "message": {
    "id": "smsg_1a4b...",
    "type": "initial",
    "status": "waiting_supplier"
  },
  "request_id": "req_..."
}

title, image, shop_id y shop_name se rellenan en la medida de lo posible. Para enriquecerlos se usa la API de detalle de producto, que requiere una autorización del marketplace que tu aplicación puede no tener; cuando no está disponible, estos campos permanecen en null y la consulta continúa con normalidad.

Una sola consulta activa por producto

Si el producto ya tiene una consulta activa, la llamada falla:

409 Conflict
{
  "error": {
    "code": "ACTIVE_INQUIRY_EXISTS",
    "message": "An active supplier inquiry already exists for this product.",
    "details": { "inquiry_id": "sinq_9f2c...", "next_action": "add_message" }
  }
}

Usa el inquiry_id devuelto para publicar un seguimiento. Si la conversación anterior está en completed o failed, la llamada de creación la reabre en lugar de fallar, y el nuevo mensaje se registra como follow_up.

Enviar un seguimiento

POST /v1/supplier-inquiries/{inquiry_id}/messages — ámbito supplier_inquiry:write.

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "Para 500 unidades" },
    { "type": "moq" }
  ],
  "attachments": [
    {
      "type": "image",
      "url": "https://cdn.example.com/packaging-example.jpg",
      "filename": "packaging-example.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

201 Created
{
  "inquiry_id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "message": {
    "id": "smsg_77de...",
    "type": "follow_up",
    "status": "waiting_supplier",
    "questions": [
      { "id": "sqst_...", "type": "lead_time", "note": "Para 500 unidades", "question": null, "status": "pending", "answer": null }
    ],
    "attachments": [
      {
        "id": "satt_...",
        "type": "image",
        "url": "https://cdn.example.com/packaging-example.jpg",
        "filename": "packaging-example.jpg",
        "mime_type": "image/jpeg",
        "source": "developer",
        "expires_at": null,
        "created_at": "2026-05-20T10:02:00.000Z"
      }
    ],
    "provider_note": null,
    "created_at": "2026-05-20T10:02:00.000Z",
    "answered_at": null
  },
  "request_id": "req_..."
}

Una consulta en cancelled rechaza los mensajes nuevos con 409 INQUIRY_NOT_ACTIVE. Una en completed o failed se reabre.

Adjuntos

Ambos endpoints de escritura aceptan un array attachments opcional: una foto de referencia, una captura de pantalla de un SKU, un croquis con medidas, un PDF con especificaciones. Los adjuntos pertenecen al mensaje con el que los envías, así que cada ronda de la conversación lleva los suyos.

Campo	Obligatorio	Descripción
`url`	Sí	Solo `https://`, máximo 2048 caracteres. `http:`, `file:`, `data:`, `javascript:` y `ftp:` se rechazan con `INVALID_ATTACHMENT_URL`
`type`	No	`image`, `document` u `other`; por defecto `other`
`filename`	No	Máximo 255 caracteres
`mime_type`	No	Máximo 128 caracteres: el valor que declares, almacenado tal cual

Como máximo cinco adjuntos por mensaje; de lo contrario, 400 TOO_MANY_ATTACHMENTS.

HIOBuy guarda los metadatos y la URL, nunca el archivo: no sube, descarga, copia ni actúa como proxy del contenido de los adjuntos, y nunca solicita la URL que le envías. Aloja el archivo tú mismo y asegúrate de que la URL sea accesible para el servicio de consultas mientras la conversación siga abierta.

Idempotencia

Envía Idempotency-Key (o X-Idempotency-Key, máximo 200 caracteres) en ambos endpoints de escritura. Una clave repetida dentro de la misma aplicación devuelve el mensaje creado la primera vez, con estado 200 en lugar de 201, y nunca contacta dos veces con el proveedor.

Reintenta siempre una creación que haya expirado usando la misma clave; sin ella, un reintento puede abrir una segunda conversación o provocar ACTIVE_INQUIRY_EXISTS.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support