Eine Produktcharge übermitteln#

POST https://sdkapi.ideal.house/product-import/products

Anfrageinhalt#

Senden Sie processImages als JSON-Wahrheitswert (true oder false), nicht als Zeichenfolge wie "true" oder "false". Bestehende Integrationen, die eine Bildvorverarbeitung benötigen, müssen jetzt ausdrücklich processImages: true senden.

Produktfelder#

Vorhandene Produkte erneut importieren#

Um Produktdaten zu aktualisieren, übermitteln Sie das Produkt erneut über POST /product-import/products. Produkte werden anhand von shopId und sku zugeordnet. Wenn dieselbe SKU bereits im Shop existiert, wird der vorhandene Produktdatensatz aktualisiert, statt ein Duplikat anzulegen. Die beim neuesten Import angegebenen Werte überschreiben die entsprechenden gespeicherten Werte, einschließlich Feldern wie name, Produkt-URLs, Status und Abmessungen.

Der Endpunkt für den Chargenimport unterstützt keine Teilaktualisierungen. Jeder übermittelte Artikel muss sämtliche Regeln für erforderliche Produktfelder erfüllen, auch wenn die SKU bereits existiert.

Die SKU dient als Identität beim Import und kann durch einen erneuten Import nicht umbenannt werden. Eine andere SKU erstellt oder aktualisiert ein anderes Produkt. Um eine SKU zu ersetzen, löschen Sie das alte Produkt logisch und importieren Sie das Produkt unter der neuen SKU.

Produktinformationen werden auch aktualisiert, wenn sich das Bild nicht geändert hat. Die Bildverarbeitung ist bei jeder Übermittlung optional: Setzen Sie bei Bedarf processImages: true. Ein zuvor ohne Bildverarbeitung importiertes Produkt kann mit aktivierter Option erneut übermittelt werden.

Unterstützte Produkttypen#

Die API akzeptiert die folgenden exakten productType-Werte unter Beachtung der Groß- und Kleinschreibung. Mehrere Namen in derselben Zeile sind Aliase für denselben Ideal House-Produkttyp.

Beispielsweise sind "Rugs", "Area Rugs" und "Area Rug" alle gültig und werden als derselbe Produkttyp behandelt. Jeder oben nicht aufgeführte Wert führt zu 400 Bad Request.

Importstatus#

Das optionale Feld status akzeptiert die folgenden exakten Werte:

Jeder andere Wert, einschließlich sold_out, führt zu 400 Bad Request.

Bei Möbeln liefern nicht aktive Übermittlungen den Produktstatus status: inactive zurück. Eine aktive Übermittlung kann unprocessed zurückgeben; das Produkt ist dann noch nicht zur Anzeige bereit. Dies bedeutet nicht, dass eine 3D-Generierung angefordert wurde.

3D-Modelle für Möbel generieren#

Die Generierung von 3D-Modellen für Möbel ist zeitaufwendig und verbraucht Guthaben. Sie erfolgt deshalb nicht während des Produktimports, auch wenn processImages auf true gesetzt ist. Künftig planen wir eine entsprechende Aktion in der Benutzeroberfläche oder eine separate API zur 3D-Generierung. Wenn Sie jetzt 3D-Modelle benötigen, senden Sie Ihrem Ideal House-Ansprechpartner eine E-Mail, damit wir die Generierung separat organisieren können.

SKU und Update-Verhalten#

Ideal House identifiziert ein Produkt durch die Kombination von shopId und sku:

• Wenn die SKU für den Shop nicht existiert, wird ein neues Produkt erstellt.
• Wenn die SKU für den Shop bereits vorhanden ist, wird das vorhandene Produkt aktualisiert.

Dadurch ist es sicher, ein Produkt mit derselben SKU nach einem unsicheren Netzwerkergebnis erneut einzureichen. Verwenden Sie stabile SKUs und generieren Sie keine neue SKU, wenn Sie dasselbe Produkt erneut versuchen. Vermeiden Sie es, dieselbe SKU mehr als einmal in einem Stapel zu versenden.

Bildanforderungen#

• Die URL muss für die Ideal House-Server ohne Cookies, Anmeldesitzungen oder benutzerdefinierte Anforderungsheader erreichbar sein.
• Verwenden Sie eine stabile URL, die das Bild direkt zurückgibt.
• Halten Sie das Quellbild verfügbar, bis der Importauftrag einen Endstatus erreicht.
• Probleme beim Herunterladen oder Verarbeiten von Bildern werden als Fehler auf Elementebene gemeldet.
• Um Bilder einzelner Bodendielen zu erstellen, setzen Sie sowohl processImages: true als auch processFloorImages: true.

Optionale Bildverarbeitung und Guthaben#

Die Bildvorverarbeitung ist standardmäßig deaktiviert:

• Bei processImages: false oder fehlendem Feld verwenden aktive Produkte ihre Originalbilder ohne Hintergrundentfernung, Texturoptimierung oder Aufteilung in Bodendielen. Produktinformationen werden weiterhin importiert oder aktualisiert, und es wird kein Guthaben für die Bildverarbeitung berechnet. Für nicht aktive Produkte gelten die oben beschriebenen Statusregeln.
• Bei processImages: true erhalten unterstützte aktive Produkte die unten beschriebene Bildverarbeitung. Die 3D-Generierung für Möbel ist nicht enthalten.

Die wichtigsten Verarbeitungsschritte sind:

Mural und Wall Mural erhalten dieselben Bildverbesserungen wie Wandbeläge. Stellen Sie für optimale Ergebnisse vollständige, klare Produktbilder bereit. Teppiche und regelmäßig geformte Wandkunst sollten einen weißen oder nahezu weißen Hintergrund haben; Bilder von Wandbelägen sollten keine starken perspektivischen Verzerrungen aufweisen.

Die oben beschriebene Bildverarbeitung kostet 1 Guthabeneinheit pro neu verarbeitetem Bild, einschließlich der Texturoptimierung für Wandbeläge. Wenn ein bereits verarbeitetes Ergebnis wiederverwendet werden kann, wird kein zusätzliches Verarbeitungsguthaben berechnet. Sorgen Sie vor dem Aktivieren dieser Option für ausreichendes Guthaben. Bei unzureichendem Guthaben findet keine Bildverarbeitung statt, und das Produkt kann im Zustand unprocessed bleiben. Eine Importcharge mit completed bestätigt für sich allein nicht, dass jedes Produktbild erfolgreich verarbeitet wurde.

Maßanforderungen#

Die API hat kein separates Feld für Maßeinheiten. width ist erforderlich. height ist normalerweise erforderlich; bei Bodenbelägen kann stattdessen length angegeben werden. Sind beide vorhanden, wird length als Dielenlänge verwendet. Zahlen und numerische Zeichenfolgen ohne Einheit werden als Zoll interpretiert. Zeichenfolgen dürfen in, ft, cm, mm oder m enthalten. Die Werte werden auf positive Abmessungen geprüft und vor dem Speichern in Zoll umgerechnet. thickness ist optional und akzeptiert auch einen Bereich wie "3-4 mm", der zu "0.1-0.2 in" normalisiert wird.

dimension_display ist eine optionale Anzeigebezeichnung und wird nicht zur Größenvalidierung oder Einheitenumrechnung verwendet. Sie kann die gewünschte kundenseitige Einheit und das gewünschte Format enthalten, beispielsweise "24 in x 36 in" oder "26 cm x 36 cm".

Beispielanfrage#

{
  "shopId": "shop_123",
  "processImages": false,
  "processFloorImages": false,
  "products": [
    {
      "sku": "SKU-10001",
      "name": "Gold Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
      "productUrl": "https://www.example.com/products/SKU-10001",
      "width": "24.0 in",
      "height": "36.0 in",
      "thickness": "2.0 in",
      "dimension_display": "24 in x 36 in",
      "category": "Mirror",
      "color": "Gold",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "active",
      "groupId": "mirror-series-01"
    },
    {
      "sku": "SKU-10002",
      "name": "Black Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10002.png",
      "productUrl": "https://www.example.com/products/SKU-10002",
      "width": "2 ft",
      "height": "3 ft",
      "thickness": "3-4 mm",
      "dimension_display": "2 ft x 3 ft",
      "category": "Mirror",
      "color": "Black",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "out_of_stock",
      "groupId": "mirror-series-01"
    }
  ]
}

cURL-Beispiel mit aktivierter Bildverarbeitung#

Dieses Beispiel aktiviert die Bildvorverarbeitung ausdrücklich. Ein neues Ergebnis der Hintergrundentfernung verbraucht 1 Guthabeneinheit.

curl --request POST \
  'https://sdkapi.ideal.house/product-import/products' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Client-Secret: <YOUR_CLIENT_SECRET>' \
  --data-raw '{
    "shopId": "shop_123",
    "processImages": true,
    "products": [
      {
        "sku": "SKU-10001",
        "name": "Gold Wall Mirror",
        "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
        "productUrl": "https://www.example.com/products/SKU-10001",
        "width": 24,
        "height": 36,
        "thickness": 2,
        "dimension_display": "24 in x 36 in",
        "category": "Mirror",
        "color": "Gold",
        "brand": "Example Brand",
        "productType": "Wall Art",
        "status": "active",
        "groupId": "mirror-series-01"
      }
    ]
  }'

Akzeptierte Antwort#

Eine gültige Anfrage liefert 202 Accepted zurück. Die Verarbeitung wird asynchron fortgesetzt.

{
  "jobId": "1930000000000000000",
  "shopId": "shop_123",
  "status": "pending",
  "totalCount": 1,
  "processedCount": 0,
  "successCount": 0,
  "failedCount": 0,
  "failures": [],
  "createdAt": "2026-07-21T06:30:00.000Z",
  "startedAt": null,
  "updatedAt": "2026-07-21T06:30:00.000Z",
  "completedAt": null,
  "error": null
}

Wenn für den Shop bereits ein Auftrag mit dem Status pending oder running existiert, gibt die API 409 Conflict zurück. Warten Sie, bis der aktuelle Auftrag abgeschlossen ist, bevor Sie eine weitere Charge senden.