Lieferantenanfrage-API

Internationale Versandkosten schätzen, bevor der Kunde kauft

Bei einem Sofa, einer Stehlampe, einem Laufband oder einer großen Transportbox für Haustiere hängen die internationalen Versandkosten fast ausschließlich davon ab, wie der Artikel tatsächlich verpackt ist: Verpackungsgewicht, Kartonmaße und die Anzahl der Pakete, in denen er versendet wird.

Genau diese Daten fehlen auf Produktseiten von 1688 und Taobao regelmäßig oder sind unzuverlässig. Damit steht Ihr Kunde vor einem sehr praktischen Problem:

Er weiß, was das Produkt kostet. Er hat keine Ahnung, was es kostet, es in sein Land zu bringen.

Die Lieferantenanfrage-API schließt diese Lücke. Der Lieferantenkommunikations-Service von HIOBuy kontaktiert vor dem Kauf den echten Lieferanten, lässt Verpackungsgewicht, Paketmaße und Kartondetails bestätigen und liefert die Antworten als strukturierte Daten an Ihre Anwendung zurück — bereit für eine Versandkostenschätzung.

Warum die Produkt-API nicht ausreicht

Die Produkt-APIs liefern zuverlässig das, was der Marktplatz selbst weiß: Titel, Bilder, Preis, SKUs, Attribute, Shop-Informationen. Bei Logistikdaten sieht es anders aus:

• es ist überhaupt kein Gewicht angegeben;
• das angezeigte Gewicht ist das Nettogewicht des Produkts, nicht das Verpackungsgewicht;
• Produktmaße existieren, aber nicht die Maße nach dem Verpacken;
• das Gewicht wurde vom Verkäufer eingetragen und ist nur ein Richtwert;
• verschiedene SKUs werden zu unterschiedlichen Gewichten verpackt;
• ein großer Artikel wird auf mehrere Pakete verteilt versendet;
• Kartonanzahl, Kartongewicht und Kartongröße stehen nirgends auf der Seite.

Die Produkt-API sagt Ihnen, was der Marktplatz weiß. Eine Lieferantenanfrage bringt Ihnen das, was nur der Lieferant bestätigen kann.

Beispiel: Versandkosten für ein Sofa schätzen

Ein Kunde in den USA sieht sich in Ihrer Anwendung ein Sofa von 1688 zum Preis von ¥800 an. Die Produkt-API hat Produkt, Preis, Bilder, SKUs und Attribute bereits geliefert — aber kein verlässliches Verpackungsgewicht und keine Paketmaße.

Damit kann Ihre Anwendung die einzige Frage nicht beantworten, auf die es als Nächstes ankommt:

Produktpreis           ¥800
Internationaler Versand ???

Bei einem sperrigen Artikel kann diese Unbekannte den Produktpreis leicht übersteigen.

Ihre Anwendung stellt eine Anfrage:

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

HIOBuy übergibt die Aufgabe an den Lieferantenkommunikations-Service, und ein Mitarbeiter in China kontaktiert den tatsächlichen Lieferanten dieses Angebots. Der Lieferant antwortet, dass das Sofa als zwei Pakete versendet wird:

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

Diese Antworten kommen als strukturiertes JSON in Ihrer Anwendung an, und der gesamte Ablauf sieht so aus:

1688-Produkt
      ↓  Produkt-API
Preis: ¥800
      ↓  verlässliche Logistikdaten fehlen
Lieferantenanfrage
      ↓  HIOBuy kontaktiert den echten Lieferanten
Lieferant bestätigt: 2 Pakete, 32 kg + 18 kg, Kartonmaße
      ↓  strukturierte Logistikdaten
Schätzung des internationalen Versands (China → USA)
      ↓
Der Kunde sieht vor dem Kauf die ungefähren Gesamtkosten

Und darum geht es bei der ganzen Sache:

Produktkosten
+ geschätzter internationaler Versand
= realistische Kosten vor dem Kauf

Die Einordnung innerhalb der HIOBuy-APIs

Produkt-API            "Was ist das Produkt, und was kostet es?"
        ↓
Lieferantenanfrage-API "Wie verpackt der Lieferant es tatsächlich?"
        ↓
Versandangebot         "Was kostet der internationale Versand ungefähr?"

Die Lieferantenanfrage ist die fehlende Ebene zwischen Produktdaten und einem Versandangebot.

Mehr als nur Versanddaten

Verpackungsdaten für die Versandkostenschätzung sind der erste und konkreteste Anwendungsfall dieser API, aber derselbe Lieferantenkommunikationskanal beantwortet alles, was nur der Lieferant weiß:

MOQ · Bestand · Lieferzeit · neutrale Verpackung · Anpassungen · Kartoninformationen · Produktdetails · alles Weitere über den Typ other.

Heute erhalten Sie damit also Verpackungsdaten → Versandkostenschätzung, und derselbe Aufruf kann ebenso Lieferanteninformationen → Einkaufsentscheidung liefern. Alle zehn Typen und ihre Antwortschemata finden Sie unter Fragetypen.

Funktionsweise

1. Ihre Anwendung ruft POST /v1/supplier-inquiries mit einer Produkt-URL, einer optionalen SKU und einer oder mehreren typisierten Fragen auf.
2. HIOBuy erstellt die Anfrage und übergibt sie an den Lieferantenkommunikations-Service.
3. Ein Mitarbeiter in China kontaktiert den Lieferanten dieses Angebots.
4. Der Lieferant antwortet.
5. Die Antwort wird gemäß dem Schema des jeweiligen Fragetyps in strukturierte Daten normalisiert.
6. Ihr Endpunkt erhält den Webhook supplier_inquiry.message_answered, oder Sie rufen GET /v1/supplier-inquiries/{id} per Polling ab.

Eine Anfrage ist eine Konversation, keine einmalige Abfrage. Sobald sie existiert, fügen Sie weitere Folgenachrichten demselben Thread hinzu, statt eine zweite Anfrage zu eröffnen.

Anhänge

Manche Fragen lassen sich mit einem Bild deutlich leichter stellen. Eine Verpackungsreferenz, ein SKU-Screenshot, eine Maßzeichnung, ein Datenblatt — und in der anderen Richtung das eigene Verpackungsfoto des Lieferanten, ein Kartonfoto oder ein Angebots-PDF.

Jede Nachricht, Ihre wie die des Lieferanten, kann bis zu fünf Anhänge tragen:

{
  "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 ist image, document oder other. Die URL muss https:// sein; alles andere wird mit INVALID_ATTACHMENT_URL abgelehnt.

Auch Lieferantenantworten können Anhänge enthalten. Sie treffen im attachments-Array der Nachricht sowie im Webhook supplier_inquiry.message_answered ein — gemeinsam mit den strukturierten Antworten. Sie sehen ausschließlich Anhänge, die der Anfrageservice für Sie freigegeben hat: interne Arbeitsdateien der Mitarbeiter und Screenshots des Lieferantenchats bleiben im Service und erreichen die API nie.

Zugang

Lieferantenanfragen sind standardmäßig deaktiviert. HIOBuy schaltet die Funktion nach kommerziellem Onboarding pro Anwendung frei — wenden Sie sich für den Zugang an den HIOBuy-Support.

Fehlt die Capability oder ist sie ausgesetzt, liefert jeder Endpunkt 403 SUPPLIER_INQUIRY_NOT_ENABLED zurück.

Unterstützte Marktplätze

Alles andere schlägt mit UNSUPPORTED_MARKETPLACE fehl. Ein Produkt wird über channel + source_product_id identifiziert, nie über die rohe URL-Zeichenkette — unterschiedliche Linkformen desselben Angebots werden also auf dasselbe Produkt aufgelöst.

Anfragestatus

pending, processing, waiting_supplier und answered gelten als aktiv. Eine Anwendung darf pro Produkt nur eine aktive Anfrage halten — das sorgt für genau einen Lieferanten-Thread je Angebot. Eine Create-Anfrage für ein Produkt mit einer completed- oder failed-Anfrage öffnet die bestehende Konversation erneut, statt eine neue anzulegen.

Webhooks

Registrieren Sie im Entwicklerportal einen Endpunkt und abonnieren Sie die Kategorie supplier_inquiry. Signierung und Wiederholungsversuche folgen den üblichen Webhook-Regeln.

Jedes Payload enthält inquiry_id und product.{channel,source_product_id}.

Fehlercodes

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE ist bewusst generisch gehalten: anbieterseitige Gründe wie Guthaben oder Kontostatus werden nicht offengelegt. Geben Sie die request_id an, wenn Sie den Support kontaktieren.

Endpunkte