Een productbatch indienen#

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

Verzoekinhoud#

Verzend processImages als een JSON-boolean, true of false, niet als een tekenreeks zoals "true" of "false". Bestaande integraties die beeldvoorbewerking nodig hebben, moeten nu expliciet processImages: true verzenden.

Productvelden#

Bestaande producten opnieuw importeren#

Dien het product opnieuw in via POST /product-import/products om productgegevens bij te werken. Producten worden gekoppeld op basis van shopId en sku. Als dezelfde SKU al in de winkel bestaat, wordt het bestaande productrecord bijgewerkt in plaats van een duplicaat aan te maken. Waarden uit de nieuwste import overschrijven de bijbehorende opgeslagen waarden, waaronder velden zoals name, product-URLs, status en afmetingen.

Het batchimportendpoint is geen endpoint voor gedeeltelijke updates. Elk ingediend item moet voldoen aan alle regels voor verplichte productvelden, ook als de SKU al bestaat.

De SKU is de importidentiteit en kan niet via herimport worden hernoemd. Een andere SKU indienen maakt een ander product aan of werkt dat andere product bij. Verwijder het oude product logisch en importeer het product onder de nieuwe SKU om een SKU te vervangen.

Productinformatie wordt bijgewerkt, ook als de afbeelding niet is veranderd. Beeldverwerking is bij elke indiening optioneel: stel indien nodig processImages: true in. Een product dat eerder zonder beeldverwerking is geïmporteerd, kan opnieuw worden ingediend met deze optie ingeschakeld.

Ondersteunde producttypen#

De API accepteert de volgende exacte, hoofdlettergevoelige productType-waarden. Meerdere namen in een rij zijn alternatieve namen voor hetzelfde Ideal House-producttype.

Bijvoorbeeld: "Rugs", "Area Rugs" en "Area Rug" zijn allemaal geldig en worden als hetzelfde producttype behandeld. Elke niet hierboven vermelde waarde retourneert 400 Bad Request.

Importstatus#

Het optionele veld status accepteert de volgende exacte waarden:

Elke andere waarde, inclusief sold_out, retourneert 400 Bad Request.

Bij meubels retourneren niet-actieve indieningen product-status: inactive. Een actieve indiening kan unprocessed retourneren, wat betekent dat het product nog niet gereed is voor weergave. Dit betekent niet dat 3D-generatie is aangevraagd.

3D-modellen van meubels genereren#

Het genereren van 3D-meubelmodellen kost tijd en credits en wordt daarom niet tijdens productimport uitgevoerd, ook niet wanneer processImages gelijk is aan true. We zijn van plan later een generatieactie in de interface of een afzonderlijke 3D-generatie-API aan te bieden. Heb je nu 3D-modellen nodig, mail dan je contactpersoon bij Ideal House zodat we de generatie afzonderlijk kunnen regelen.

SKU en bijwerkgedrag#

Ideal House identificeert een product met de combinatie van shopId en sku:

• Als de SKU niet in de winkel bestaat, wordt een nieuw product aangemaakt.
• Als de SKU al in de winkel bestaat, wordt het bestaande product bijgewerkt.

Daardoor kun je een product na een onzeker netwerkresultaat veilig opnieuw indienen met dezelfde SKU. Gebruik stabiele SKUs en genereer geen nieuwe SKU wanneer je hetzelfde product opnieuw probeert. Vermijd dat dezelfde SKU meer dan eenmaal in één batch wordt verzonden.

Afbeeldingsvereisten#

• De URL moet voor de servers van Ideal House bereikbaar zijn zonder cookies, aanmeldsessies of aangepaste verzoekheaders.
• Gebruik een stabiele URL die de afbeelding rechtstreeks retourneert.
• Houd de bronafbeelding beschikbaar totdat de importtaak een eindstatus bereikt.
• Problemen bij het downloaden of verwerken van afbeeldingen worden als fouten per item gemeld.
• Stel zowel processImages: true als processFloorImages: true in om afbeeldingen van vloerplanken te maken.

Optionele beeldverwerking en credits#

Beeldvoorbewerking is standaard uitgeschakeld:

• Met processImages: false of wanneer het veld wordt weggelaten, gebruiken actieve producten hun oorspronkelijke afbeeldingen zonder achtergrondverwijdering, textuuroptimalisatie of opsplitsing in vloerplanken. Productinformatie wordt nog steeds geïmporteerd of bijgewerkt en er worden geen credits voor beeldverwerking afgeschreven. Niet-actieve producten volgen de hierboven beschreven statusregels.
• Met processImages: true krijgen ondersteunde actieve producten de hieronder beschreven beeldverwerking. 3D-generatie voor meubels is niet inbegrepen.

De belangrijkste verwerkingen zijn:

Mural en Wall Mural krijgen dezelfde beeldverbeteringen als wandproducten. Lever voor het beste resultaat volledige, duidelijke productafbeeldingen aan; vloerkleden en regelmatige wandkunst moeten een witte of bijna witte achtergrond hebben en wandafbeeldingen moeten sterke perspectiefvervorming vermijden.

De hierboven beschreven beeldverwerking kost 1 tegoedeenheid per nieuw verwerkte afbeelding, inclusief optimalisatie van wandtexturen. Als een bestaand verwerkt resultaat kan worden gebruikt, worden geen extra verwerkingscredits afgeschreven. Zorg voor voldoende credits voordat je deze optie inschakelt. Bij onvoldoende credits gaat beeldverwerking niet door en kan het product unprocessed blijven. Een completed-importbatch bevestigt op zichzelf niet dat elke productafbeelding succesvol is verwerkt.

Afmetingsvereisten#

De API heeft geen afzonderlijk veld voor maateenheden. width is verplicht. height is normaal gesproken verplicht, maar een vloerproduct mag in plaats daarvan length opgeven; als beide aanwezig zijn, wordt length als planklengte gebruikt. Getallen en numerieke tekenreeksen zonder eenheid worden als inches geïnterpreteerd. Tekenreeksen mogen in, ft, cm, mm of m bevatten; waarden worden als positieve afmetingen gevalideerd en vóór opslag naar inches omgerekend. thickness is optioneel en accepteert ook een bereik zoals "3-4 mm", dat wordt genormaliseerd naar "0.1-0.2 in".

dimension_display is een optioneel weergavelabel en wordt niet gebruikt voor maatvalidatie of eenheidsconversie. Het mag de eenheid en opmaak gebruiken die je aan klanten wilt tonen, bijvoorbeeld "24 in x 36 in" of "26 cm x 36 cm".

Voorbeeldverzoek#

{
  "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-voorbeeld met beeldverwerking ingeschakeld#

Dit voorbeeld schakelt beeldvoorbewerking expliciet in. Een nieuw resultaat van achtergrondverwijdering verbruikt 1 credit.

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

Antwoord bij acceptatie#

Een geldig verzoek retourneert 202 Accepted. De verwerking gaat asynchroon verder.

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

Als de winkel al een pending- of running-taak heeft, retourneert de API 409 Conflict. Wacht totdat de huidige taak is voltooid voordat je een nieuwe batch indient.