Invia un lotto di prodotti#

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

Corpo della richiesta#

Invia processImages come valore booleano JSON (true o false), non come stringa quale "true" o "false". Le integrazioni esistenti che richiedono la preelaborazione delle immagini devono ora inviare esplicitamente processImages: true.

Campi del prodotto#

Reimporta prodotti esistenti#

Per aggiornare i dati di un prodotto, invialo nuovamente tramite POST /product-import/products. I prodotti vengono identificati tramite shopId e sku. Quando lo stesso SKU esiste già nel negozio, il record del prodotto esistente viene aggiornato anziché creare un duplicato, e i valori forniti dall'ultima importazione sovrascrivono i corrispondenti valori memorizzati, compresi campi come name, URLs del prodotto, stato e dimensioni.

L'endpoint di importazione in lotti non è un endpoint di aggiornamento parziale. Ogni elemento inviato deve soddisfare tutte le regole dei campi obbligatori del prodotto, anche quando lo SKU esiste già.

Lo SKU è l'identità usata per l'importazione e non può essere rinominato tramite reimportazione. Inviare uno SKU diverso crea o aggiorna un prodotto diverso. Per sostituire uno SKU, elimina logicamente il vecchio prodotto e importa il prodotto con il nuovo SKU.

Le informazioni del prodotto vengono aggiornate anche quando l'immagine non è cambiata. L'elaborazione delle immagini è facoltativa a ogni invio: imposta processImages: true quando necessario. Un prodotto importato in precedenza senza elaborazione delle immagini può essere inviato nuovamente con questa opzione abilitata.

Tipi di prodotto supportati#

API accetta i seguenti valori esatti di productType, distinguendo maiuscole e minuscole. Più nomi nella stessa riga sono alias dello stesso tipo di prodotto Ideal House.

Ad esempio, "Rugs", "Area Rugs" e "Area Rug" sono tutti validi e vengono trattati come lo stesso tipo di prodotto. Qualsiasi valore non elencato sopra restituisce 400 Bad Request.

Stato di importazione#

Il campo facoltativo status accetta i seguenti valori esatti:

Qualsiasi altro valore, compreso sold_out, restituisce 400 Bad Request.

Per i mobili, gli invii non attivi restituiscono il prodotto con status: inactive. Un invio attivo può restituire unprocessed, indicando che il prodotto non è ancora pronto per la visualizzazione. Questo non significa che sia stata richiesta la generazione 3D.

Generazione di modelli 3D dei mobili#

La generazione di modelli 3D dei mobili richiede tempo e consuma crediti, quindi non viene eseguita durante l'importazione dei prodotti, nemmeno quando processImages è true. Prevediamo di fornire in futuro un'azione di generazione nell'interfaccia utente o una API separata di generazione 3D. Se ti servono modelli 3D adesso, invia un'email al tuo contatto Ideal House affinché possiamo organizzare la generazione separatamente.

SKU e comportamento degli aggiornamenti#

Ideal House identifica un prodotto tramite la combinazione di shopId e sku:

• Se lo SKU non esiste nel negozio, viene creato un nuovo prodotto.
• Se lo SKU esiste già nel negozio, il prodotto esistente viene aggiornato.

Questo consente di reinviare in sicurezza un prodotto con lo stesso SKU dopo un esito di rete incerto. Usa SKUs stabili e non generare un nuovo SKU quando riprovi lo stesso prodotto. Evita di inviare lo stesso SKU più di una volta in un singolo lotto.

Requisiti delle immagini#

• La URL deve essere raggiungibile dai server Ideal House senza cookie, sessioni di accesso o intestazioni di richiesta personalizzate.
• Usa una URL stabile che restituisca direttamente l'immagine.
• Mantieni disponibile l'immagine originale finché il processo di importazione non raggiunge uno stato finale.
• I problemi di download o elaborazione delle immagini vengono segnalati come errori a livello di singolo elemento.
• Per creare immagini delle doghe della pavimentazione, imposta sia processImages: true sia processFloorImages: true.

Elaborazione facoltativa delle immagini e crediti#

La preelaborazione delle immagini è disabilitata per impostazione predefinita:

• Con processImages: false o quando il campo viene omesso, i prodotti attivi usano le immagini originali senza rimozione dello sfondo, ottimizzazione della texture o suddivisione della pavimentazione in doghe. Le informazioni del prodotto vengono comunque importate o aggiornate e non viene addebitato alcun credito per l'elaborazione delle immagini. I prodotti non attivi seguono le regole di stato descritte sopra.
• Con processImages: true, i prodotti attivi supportati ricevono l'elaborazione delle immagini descritta di seguito. La generazione 3D dei mobili non è inclusa.

I principali comportamenti di elaborazione sono:

Mural e Wall Mural ricevono gli stessi miglioramenti delle immagini della carta da parati. Per risultati ottimali, fornisci immagini complete e chiare dei prodotti; tappeti e quadri regolari devono avere sfondi bianchi o quasi bianchi, e le immagini della carta da parati devono evitare forti distorsioni prospettiche.

L'elaborazione delle immagini descritta sopra costa 1 credito per ogni nuova immagine elaborata, compresa l'ottimizzazione della texture della carta da parati. Se può essere usato un risultato già elaborato, non viene addebitato alcun credito aggiuntivo di elaborazione. Assicurati di avere crediti sufficienti prima di abilitare questa opzione. Con crediti insufficienti, l'elaborazione delle immagini non procede e il prodotto può rimanere unprocessed. Un lotto di importazione completed non conferma di per sé che ogni immagine di prodotto sia stata elaborata correttamente.

Requisiti delle dimensioni#

API non ha un campo separato per l'unità delle dimensioni. width è obbligatorio. height è normalmente obbligatorio, mentre un prodotto di pavimentazione può fornire length al suo posto; quando sono presenti entrambi, length viene usato come lunghezza della doga. Numeri e stringhe numeriche senza unità vengono interpretati come pollici. Le stringhe possono includere in, ft, cm, mm o m; i valori vengono convalidati come dimensioni positive e normalizzati in pollici prima della memorizzazione. thickness è facoltativo e accetta anche un intervallo come "3-4 mm", che viene normalizzato in "0.1-0.2 in".

dimension_display è un'etichetta di visualizzazione facoltativa e non viene usata per convalidare le dimensioni o convertire le unità. Può usare l'unità e il formato rivolti al cliente che desideri mostrare, ad esempio "24 in x 36 in" o "26 cm x 36 cm".

Esempio di richiesta#

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

Esempio cURL (elaborazione delle immagini abilitata)#

Questo esempio abilita esplicitamente la preelaborazione delle immagini. Un nuovo risultato di rimozione dello sfondo consuma 1 credito.

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

Risposta di accettazione#

Una richiesta valida restituisce 202 Accepted. L'elaborazione prosegue in modo asincrono.

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

Se il negozio ha già un processo pending o running, API restituisce 409 Conflict. Attendi che il processo corrente termini prima di inviare un altro lotto.