Créer une demande fournisseur

Deux endpoints écrivent dans une conversation fournisseur : l’un l’ouvre, l’autre la poursuit. Tous deux acceptent le même tableau questions ainsi qu’un en-tête Idempotency-Key.

Créer une demande

POST /v1/supplier-inquiries — scope supplier_inquiry:write.

Corps de la requête

Champ	Obligatoire	Description
`product_url`	Oui	Lien produit 1688 ou Taobao absolu, 2048 caractères maximum
`questions`	Oui	1 à 10 questions, voir les types de questions
`sku`	Non	`{ "id": "...", "label": "..." }`, 200 caractères chacun — restreint la question à une seule variante
`attachments`	Non	Jusqu’à 5 références de fichiers, voir les pièces jointes

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": "Noir / XL" },
  "questions": [
    { "type": "packed_weight", "note": "Poids avec la boîte de vente" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

Réponse

201 Created, ou 200 OK lorsqu’un Idempotency-Key rejoue une requête antérieure.

{
  "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": "Noir / 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 et shop_name sont renseignés au mieux. Leur enrichissement passe par l’API de détail produit, qui requiert une autorisation de place de marché dont votre application ne dispose peut-être pas — lorsqu’elle est indisponible, ces champs restent à null et la demande se poursuit normalement.

Une seule demande active par produit

Si le produit fait déjà l’objet d’une demande active, l’appel échoue :

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

Utilisez l’inquiry_id renvoyé pour publier une relance. Si la conversation précédente est completed ou failed, l’appel de création la rouvre au lieu d’échouer, et le nouveau message est enregistré comme follow_up.

Poser une question de relance

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

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "Pour 500 unités" },
    { "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": "Pour 500 unités", "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_..."
}

Une demande cancelled rejette les nouveaux messages avec 409 INQUIRY_NOT_ACTIVE. Une demande completed ou failed est rouverte.

Pièces jointes

Les deux endpoints d’écriture acceptent un tableau attachments facultatif — une photo de référence, une capture d’écran de SKU, un croquis coté, une fiche technique en PDF. Les pièces jointes appartiennent au message avec lequel vous les envoyez : chaque tour de la conversation porte donc les siennes.

Champ	Obligatoire	Description
`url`	Oui	`https://` uniquement, 2048 caractères maximum. `http:`, `file:`, `data:`, `javascript:` et `ftp:` sont rejetés avec `INVALID_ATTACHMENT_URL`
`type`	Non	`image`, `document` ou `other` ; vaut `other` par défaut
`filename`	Non	255 caractères maximum
`mime_type`	Non	128 caractères maximum — la valeur que vous déclarez, stockée telle quelle

Cinq pièces jointes au maximum par message, sinon 400 TOO_MANY_ATTACHMENTS.

HIOBuy conserve les métadonnées et l’URL, jamais le fichier : il ne téléverse, ne télécharge, ne copie ni ne relaie le contenu des pièces jointes, et n’appelle jamais l’URL que vous envoyez. Hébergez le fichier vous-même et assurez-vous que l’URL reste accessible au service de demande aussi longtemps que la conversation est ouverte.

Idempotence

Envoyez Idempotency-Key (ou X-Idempotency-Key, 200 caractères maximum) sur les deux endpoints d’écriture. Une clé réutilisée au sein de la même application renvoie le message créé la première fois, avec le statut 200 au lieu de 201, et ne contacte jamais le fournisseur deux fois.

Réessayez toujours une création expirée avec la même clé — sans elle, une nouvelle tentative risque d’ouvrir une seconde conversation ou de déclencher ACTIVE_INQUIRY_EXISTS.

Get Support

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

Email support