API de demande fournisseur

Estimer le transport international avant l’achat

Pour un canapé, un lampadaire, un tapis de course ou une grande cage pour animaux, le coût du transport international dépend presque entièrement de la façon dont l’article est réellement emballé : son poids emballé, les dimensions de ses cartons et le nombre de colis dans lesquels il est expédié.

Ces données sont le plus souvent absentes ou peu fiables sur les fiches produit 1688 et Taobao. Ce qui place votre client devant un problème très concret :

Il sait combien coûte le produit. Il n’a aucune idée de ce que coûte son acheminement jusqu’à son pays.

L’API de demande fournisseur comble cette lacune. Le service de communication fournisseur de HIOBuy contacte le vrai fournisseur avant l’achat, confirme le poids emballé, les dimensions des colis et les détails carton, puis renvoie les réponses à votre application sous forme de données structurées — prêtes à alimenter une estimation de transport.

Pourquoi l’API Produit ne suffit pas

Les API produit vous fournissent de façon fiable ce que la place de marché connaît elle-même : titre, images, prix, SKU, attributs, informations sur la boutique. Les données logistiques, c’est une autre histoire :

• aucun poids n’est publié ;
• le poids affiché est le poids net du produit, pas le poids emballé ;
• les dimensions du produit existent, mais pas les dimensions après emballage ;
• le poids a été saisi par le vendeur et n’est qu’indicatif ;
• des SKU différents donnent des poids emballés différents ;
• un article volumineux est expédié réparti sur plusieurs colis ;
• le nombre de cartons, leur poids et leur taille ne figurent nulle part sur la page.

L’API Produit vous dit ce que la place de marché sait. Une demande fournisseur vous apporte ce que seul le fournisseur peut confirmer.

Exemple : estimer le transport d’un canapé

Un client aux États-Unis consulte dans votre application un canapé 1688 affiché à ¥800. L’API produit a déjà renvoyé le produit, le prix, les images, les SKU et les attributs — mais aucun poids emballé ni dimensions de colis fiables.

Votre application ne peut donc pas répondre à la seule question qui compte ensuite :

Prix du produit         ¥800
Transport international ???

Sur un article volumineux, cette inconnue peut facilement dépasser le prix du produit lui-même.

Votre application ouvre une demande :

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

HIOBuy confie la tâche au service de communication fournisseur, et un opérateur basé en Chine contacte le fournisseur réel de cette annonce. Le fournisseur répond que le canapé est expédié en deux colis :

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

Ces réponses reviennent à votre application en JSON structuré, et le parcours complet ressemble à ceci :

Produit 1688
      ↓  API Produit
Prix : ¥800
      ↓  données logistiques fiables manquantes
Demande fournisseur
      ↓  HIOBuy contacte le vrai fournisseur
Le fournisseur confirme : 2 colis, 32 kg + 18 kg, dimensions des cartons
      ↓  données logistiques structurées
Estimation du transport international (Chine → États-Unis)
      ↓
Le client voit un coût total approximatif avant d'acheter

Ce qui est tout l’objet de l’exercice :

Coût du produit
+ transport international estimé
= un coût réaliste avant achat

Sa place parmi les API HIOBuy

API Produit                 « Quel est le produit, et combien coûte-t-il ? »
        ↓
API de demande fournisseur  « Comment le fournisseur va-t-il réellement l'emballer ? »
        ↓
Devis de transport          « Combien coûtera à peu près l'expédition internationale ? »

La demande fournisseur est la couche manquante entre les données produit et un devis de transport.

Plus que des données de transport

Les données d’emballage pour l’estimation du transport sont le premier et le plus concret des usages de cette API, mais le même canal de communication fournisseur répond à tout ce que seul le fournisseur sait :

MOQ · stock · délai de production · emballage neutre · personnalisation · informations carton · détails produit · et tout le reste, via le type other.

Aujourd’hui, cela vous donne donc données d'emballage → estimation du transport, et le même appel peut tout aussi bien servir informations fournisseur → décision d'achat. Consultez les types de question pour les dix types et leurs schémas de réponse.

Fonctionnement

1. Votre application appelle POST /v1/supplier-inquiries avec une URL produit, un SKU facultatif et une ou plusieurs questions typées.
2. HIOBuy crée la demande et la confie au service de communication fournisseur.
3. Un opérateur basé en Chine contacte le fournisseur de cette annonce.
4. Le fournisseur répond.
5. La réponse est normalisée en données structurées conformément au schéma de chaque type de question.
6. Votre endpoint reçoit le webhook supplier_inquiry.message_answered, ou vous interrogez GET /v1/supplier-inquiries/{id}.

Une demande est une conversation, pas une requête ponctuelle. Une fois créée, vous ajoutez vos messages de relance au même fil plutôt que d’en ouvrir un second.

Pièces jointes

Certaines questions sont bien plus simples à poser avec une image. Une référence d’emballage, une capture d’écran de SKU, un croquis coté, une fiche technique — et dans l’autre sens, la photo d’emballage du fournisseur, une photo de carton ou un devis en PDF.

Chaque message, le vôtre comme celui du fournisseur, peut transporter jusqu’à cinq pièces jointes :

{
  "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 vaut image, document ou other. L’URL doit être en https:// ; toute autre valeur est rejetée avec INVALID_ATTACHMENT_URL.

Les réponses du fournisseur peuvent elles aussi comporter des pièces jointes. Elles arrivent dans le tableau attachments du message ainsi que dans le webhook supplier_inquiry.message_answered, aux côtés des réponses structurées. Vous ne voyez que les pièces jointes que le service de demande a marquées comme vous étant destinées — les fichiers de travail des opérateurs et les captures d’écran des échanges avec le fournisseur restent internes au service et n’atteignent jamais l’API.

Accès

La demande fournisseur est désactivée par défaut. HIOBuy l’active application par application après l’intégration commerciale — contactez le support HIOBuy pour en faire la demande.

Si la capacité est absente ou suspendue, chaque endpoint renvoie 403 SUPPLIER_INQUIRY_NOT_ENABLED.

Places de marché prises en charge

Tout le reste échoue avec UNSUPPORTED_MARKETPLACE. Un produit est identifié par channel + source_product_id, jamais par la chaîne d’URL brute : différentes formes de lien pour une même offre pointent donc vers le même produit.

Statuts de demande

pending, processing, waiting_supplier et answered sont considérés comme actifs. Une application ne peut détenir qu’une seule demande active par produit — c’est ce qui garantit un fil fournisseur unique par offre. Envoyer une requête de création pour un produit dont la demande est completed ou failed rouvre cette conversation au lieu d’en créer une nouvelle.

Webhooks

Enregistrez un endpoint dans le portail développeur et abonnez-vous à la catégorie supplier_inquiry. La signature et les tentatives de renvoi suivent les règles standard des webhooks.

Chaque payload contient inquiry_id et product.{channel,source_product_id}.

Codes d’erreur

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE reste volontairement générique : les causes côté prestataire, comme le solde ou l’état du compte, ne sont pas exposées. Indiquez le request_id lorsque vous contactez le support.

Endpoints