Risposte agli errori#

Stato HTTP	Significato	Azione consigliata
`400 Bad Request`	Il corpo della richiesta o i parametri della query non sono validi.	Correggere la richiesta prima di riprovare.
`401 Unauthorized`	Le credenziali sono mancanti, non valide, scadute o non attive.	Verificare le intestazioni di autenticazione o contattare Ideal House.
`403 Forbidden`	Il richiesto `shopId` non è associato alle credenziali.	Utilizza l'ID negozio assegnato alle credenziali. (Shop ID)
`404 Not Found`	Non è disponibile alcuno stato di importazione o prodotto corrispondente.	Verifica l'ID negozio e l'ID prodotto o SKU richiesto. (Shop ID)
`409 Conflict`	Un’altra attività di importazione è attiva per il negozio.	Attendere il completamento dell’attività di importazione corrente.
`429 Too Many Requests`	Il tasso di richiesta è troppo alto.	Riprovare con tempi di attesa crescenti in modo esponenziale con una variazione casuale.
`500 Internal Server Error`	Il servizio ha riscontrato un errore imprevisto.	Riprova con tempi di attesa crescenti in modo esponenziale. Contattare Ideal House se l'errore persiste.
`502 Bad Gateway` o `503 Service Unavailable`	L’API è temporaneamente non disponibile.	Riprovare aumentando il tempo di attesa in modo esponenziale.

Un errore di convalida può utilizzare il seguente formato:

json

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

Il testo dentro message può variare. Utilizzare il codice di stato HTTP e i campi di risposta documentati per la logica del programma.

Guida ai tentativi e al ripristino#

Interrogare lo stato ogni 2–5 secondi mentre l’attività è pending o running.
Per le risposte 429, 500, 502 e 503, aumentare i tempi di attesa in modo esponenziale, aggiungere una variazione casuale e impostare un numero massimo di tentativi.
Non ripetere automaticamente le richieste che restituiscono 400, 401 o 403 senza correggere la richiesta o le credenziali.
Dopo 409, attendere che l’attività in corso raggiunga lo stato completed o failed.
Se un invio scade prima di ricevere una risposta, interroga l'endpoint di stato prima di inviare nuovamente il batch.
Riprovare lo stesso prodotto con lo stesso SKU è sicuro perché le importazioni utilizzano il comportamento di creazione o aggiornamento.
Dopo il completamento di un’attività con errori relativi a singoli prodotti, inviare un nuovo lotto contenente soltanto i prodotti la cui elaborazione non è riuscita.
Dopo un errore a livello di attività, i prodotti conteggiati in successCount potrebbero essere già stati aggiornati. È sicuro reinviare il lotto originale con gli stessi SKUs.
L’eliminazione potrebbe essere già avvenuta anche se la richiesta restituisce 503. Ripetere la stessa richiesta di eliminazione è sicuro.

L'endpoint di stato è destinato al monitoraggio del processo attivo o più recente, non alla cronologia di importazione permanente. Conservare il batch inviato, jobId, risposte sullo stato e risultato finale nel proprio sistema per la riconciliazione e il supporto.

Lista di controllo della produzione#

Archivia il segreto del client in un gestore di segreti o in un ambiente server protetto. (Client Secret)
Utilizza uno SKU stabile e unico per ogni prodotto.
Invia non più di 500 prodotti per richiesta.
Assicurati che gli URLs delle immagini siano raggiungibili pubblicamente e rimangano disponibili durante l'elaborazione.
Impostare esplicitamente processImages: true solo quando serve la preelaborazione delle immagini e si accetta il costo di 1 credito per immagine elaborata. Altrimenti omettere il campo o impostarlo su false.
Abilitare la suddivisione delle immagini Floor soltanto impostando sia processImages sia processFloorImages su true.
Fornire name, imageUrl, productUrl, width, height e un valore supportato di productType per ogni prodotto.
Quando fornito, impostare status a active, inactive, out_of_stock, o invalid.
Inviare dimensioni positive con un’unità supportata oppure omettere l’unità per usare i pollici; i valori memorizzati vengono normalizzati in pollici.
Memorizzare il jobId restituito e confrontarlo con le successive risposte sullo stato.
Trattare completed con failedCount > 0 come un successo parziale.
Recuperare l’elenco dei prodotti una pagina alla volta invece di richiedere un catalogo senza limiti di dimensione.
Per le operazioni di eliminazione, fornire esattamente uno tra productId e sku.
Implementare un numero limitato di tentativi con tempi di attesa crescenti in modo esponenziale e una variazione casuale.

Per credenziali, valori forniti durante la configurazione iniziale, mappatura dei tipi di prodotto o problemi di integrazione persistenti, contatta il tuo rappresentante dell'integrazione Ideal House.