Lieferantenanfrage erstellen

Zwei Endpunkte schreiben in eine Lieferantenkonversation: einer startet sie, einer setzt sie fort. Beide erwarten dasselbe questions-Array und beide akzeptieren einen Idempotency-Key.

Anfrage erstellen

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

Request-Body

Feld	Erforderlich	Beschreibung
`product_url`	Ja	Absoluter Produktlink von 1688 oder Taobao, maximal 2048 Zeichen
`questions`	Ja	1–10 Fragen, siehe Fragetypen
`sku`	Nein	`{ "id": "...", "label": "..." }`, je 200 Zeichen — grenzt die Frage auf eine Variante ein
`attachments`	Nein	Bis zu 5 Dateiverweise, siehe Anhänge

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": "Schwarz / XL" },
  "questions": [
    { "type": "packed_weight", "note": "Gewicht inklusive Verkaufsverpackung" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

Response

201 Created, oder 200 OK, wenn ein Idempotency-Key eine frühere Anfrage wiederholt.

{
  "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": "Schwarz / 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 und shop_name werden nach bestem Bemühen befüllt. Die Anreicherung nutzt die Produktdetail-API, die eine Marktplatz-Autorisierung erfordert, über die Ihre Anwendung möglicherweise nicht verfügt — ist sie nicht verfügbar, bleiben diese Felder null und die Anfrage läuft normal weiter.

Eine aktive Anfrage pro Produkt

Existiert für das Produkt bereits eine aktive Anfrage, schlägt der Aufruf fehl:

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

Verwenden Sie die zurückgegebene inquiry_id, um eine Folgefrage zu senden. Ist die vorherige Konversation completed oder failed, öffnet der Create-Aufruf sie erneut, statt fehlzuschlagen, und die neue Nachricht wird als follow_up erfasst.

Folgefrage stellen

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

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "Für 500 Stück" },
    { "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": "Für 500 Stück", "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_..."
}

Eine cancelled-Anfrage weist neue Nachrichten mit 409 INQUIRY_NOT_ACTIVE ab. Eine completed- oder failed-Anfrage wird wieder geöffnet.

Anhänge

Beide Schreib-Endpunkte akzeptieren ein optionales attachments-Array — ein Referenzfoto, ein SKU-Screenshot, eine Maßzeichnung, ein Spezifikations-PDF. Anhänge gehören zu der Nachricht, mit der Sie sie senden, jede Runde der Konversation trägt also ihre eigenen.

Feld	Erforderlich	Beschreibung
`url`	Ja	Nur `https://`, maximal 2048 Zeichen. `http:`, `file:`, `data:`, `javascript:` und `ftp:` werden mit `INVALID_ATTACHMENT_URL` abgelehnt
`type`	Nein	`image`, `document` oder `other`; Standardwert `other`
`filename`	Nein	Maximal 255 Zeichen
`mime_type`	Nein	Maximal 128 Zeichen — Ihr angegebener Wert, wird unverändert gespeichert

Höchstens fünf Anhänge pro Nachricht, andernfalls 400 TOO_MANY_ATTACHMENTS.

HIOBuy speichert die Metadaten und die URL, nie die Datei: Anhangsinhalte werden nicht hochgeladen, heruntergeladen, kopiert oder geproxyt, und die von Ihnen gesendete URL wird nie abgerufen. Hosten Sie die Datei selbst und stellen Sie sicher, dass die URL für den Anfrageservice erreichbar bleibt, solange die Konversation offen ist.

Idempotenz

Senden Sie Idempotency-Key (oder X-Idempotency-Key, maximal 200 Zeichen) an beiden Schreib-Endpunkten. Ein wiederholter Schlüssel innerhalb derselben Anwendung liefert die beim ersten Mal erstellte Nachricht zurück, mit Status 200 statt 201, und kontaktiert den Lieferanten nie ein zweites Mal.

Wiederholen Sie einen abgelaufenen Create-Aufruf immer mit demselben Schlüssel — ohne ihn kann ein Retry eine zweite Konversation eröffnen oder auf ACTIVE_INQUIRY_EXISTS laufen.

Get Support

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

Email support