API di importazione: importare dati tramite POST e PUT

{
  "type": "categories",
  "data": [
    {
      "categories_id": 142,
      "parent_id": 110,
      "status": 1,
      "languages": {
        "de": {
          "categories_name": "Produktattribute",
          "categories_description": "<p>Beschreibung als HTML-String...</p>"
        }
      }
    }
  ]
}

• La modalità rigorosa viene attivata solo da true; a partire dalla v2.122.12 gli spazi vuoti ai margini non vengono conteggiati (?_strict=%20true viene considerato come true). Nei negozi precedenti alla versione 4.9.173, inviare il valore senza spazi ai margini. Altri valori di _strict (ad esempio 1 o yes) e qualsiasi valore dell’elenco (?language[]=de, ?_strict[]=true) generano un errore HTTP 400 INVALID_FILTER_VALUE con il messaggio details[] (“… Nothing was written”). La verifica avviene prima che l’importazione legga o scriva qualcosa.
• Un valore vuoto significa «non impostato»; a partire dalla versione v2.122.12, in _strict è sufficiente anche uno spazio vuoto: l’importazione funziona quindi come se il parametro non fosse presente. L’importazione continua a ignorare silenziosamente i nomi di parametri sconosciuti.

{
  "success": true,
  "api_version": "2.1.0",
  "type": "categories",
  "stats": {
    "total": 2,
    "inserted": 1,
    "updated": 1,
    "failed": 0
  },
  "errors": [],
  "timestamp": "2026-01-27 14:00:00",
  "records": [
    {"index": 1, "categories_id": 144, "status": "inserted"},
    {"index": 2, "categories_id": 142, "status": "updated"}
  ]
}

I campi aggiuntivi di un prodotto vengono inseriti esclusivamente tramite il campo extra_fields – non come campo al livello superiore del prodotto. Una chiave come google_product_category, posizionata direttamente accanto a products_model, viene ignorata (e segnalata nella risposta come UNKNOWN_FIELD ).

A partire dalla versione 2.51.0, sono accettate tutte le seguenti forme di scrittura – a scelta tramite l’ID del campo o il nome del campo (si tollera l’uso di maiuscole/minuscole e spazi):

{
  "type": "products",
  "data": [{
    "products_model": "ABC-123",

    "extra_fields": {
      "Google Produktkategorie (xoPort)": "1234",
      "Google Zustand (xoPort)": "new",
      "Google Verfügbarkeit (xoPort)": "in stock"
    }

    // ... alternativ nach Feld-ID:
    // "extra_fields": {"7": "1234", "8": "new", "9": "in stock"}

    // ... oder als Liste:
    // "extra_fields": [{"products_extra_fields_id": 7, "products_extra_fields_value": "1234"}]
  }]
}

Anche la struttura restituita dall’esportazione JSON (oggetto, indicizzato in base all’ID del campo) può essere reimportata senza modifiche.

Campi di Google Shopping

I campi del feed di Google sono campi aggiuntivi standard con ID fissi:

Le schede del prodotto (ad es. «Descrizione delle prestazioni», «Scheda tecnica», «Istruzioni di montaggio») vengono gestite tramite il campo tabs – un array piatto di oggetti scheda. Un formato con nidificazione di linguaggi come {"de": […]} non è supportato e viene ignorato senza generare alcun messaggio di errore (nessun avviso, nessuna scheda).

{
  "type": "products",
  "data": [{
    "products_model": "ABC-123",

    "tabs": [
      {
        "tab_name": "Leistungsbeschreibung",
        "tab_content": "<h3>Leistungsbeschreibung</h3><p>...</p>",
        "language_id": 2,
        "sort_order": 0
      },
      {
        "tab_name": "Service description",
        "tab_content": "<h3>Service description</h3><p>...</p>",
        "language_id": 1,
        "sort_order": 0
      }
    ]
  }]
}

Comportamento in dettaglio

• Nuova creazione: ogni inserimento senza tab_id crea una nuova scheda con la propria tab_id – anche per ogni lingua. Le schede multilingue vengono quindi inviate come un inserimento per ogni lingua (vedi esempio sopra); il frontend mostra, filtrato per lingua, solo le schede della lingua attiva.
• tab_id Aggiornamento: con tab_id, la scheda esistente nella lingua specificata viene aggiornata – ma solo se la riga della lingua esiste già. Una versione linguistica mancante di una scheda esistente non può essere creata successivamente tramite API (a tal fine, inviare una nuova scheda senza ).
• Nessuna eliminazione in caso di assenza: le schede non inviate rimangono invariate. L’eliminazione delle schede avviene nel backend a livello di prodotto.
• Export-Round-Trip: GET /products fornisce le schede come oggetto con chiave tab_id (inclusi tab_name, tab_content, language_id, sort_order).

Le giacenze, le scorte di sicurezza e le scorte di segnalazione per ciascun magazzino vengono gestite nell’importazione dei prodotti esclusivamente tramite il campo storages – un array piatto di oggetti magazzino, ciascuno con storages_id (alias warehouse_id). A partire dalla v2.45.0 si tratta di un aggiornamento parziale: un payload parziale come {"storages_id": 3, "products_reorder_level": 10} modifica solo il livello di segnalazione di quel magazzino e non imposta le altre colonne del magazzino su 0.

È necessario che il sistema di magazzino avanzato sia attivato (EXTENDED_STORAGE_SYSTEM); in caso contrario, il campo viene ignorato e la risposta contiene l’avviso STORAGE_SYSTEM_DISABLED. Tutti i campi, la semantica e le insidie sono descritti nella sezione «Scorte e livelli di segnalazione per magazzino» della guida di riferimento Products.

Per POST /Import/JSON/media e PUT /Import/JSON/media/{id} (ambito media:write), come multipart/form-data e con JSON troncato: un campo che contiene esattamente un valore, sotto forma di elenco (campo del modulo entity_type[]=… o entity_type[key]=…, nel JSON troncato un array o un oggetto, anche vuoto) genera un errore HTTP 400 INVALID_FIELD_VALUE con field. Non viene letto né scritto nulla.

{
  "success": false,
  "api_version": "2.122.11",
  "error": {
    "code": "INVALID_FIELD_VALUE",
    "message": "Field \"entity_id\" must be a single value, not a list (entity_id[]=… or entity_id[key]=…; in a JSON body an array or object). Send the field once.",
    "field": "entity_id"
  }
}

• Più file comportano più richieste; l’endpoint accetta esattamente un file.
• Un campo in una voce di descriptions viene denominato in field con la sua voce, ad esempio descriptions[0].language_code. La verifica avviene prima della prima scrittura.
• Invariato: descriptions stesso è un elenco per ogni lingua; i campi sconosciuti vengono ignorati come in precedenza.
• Gli errori che ripetono un campo del modulo (entity_type in UNSUPPORTED_ENTITY_TYPE, target_folder, subfolder, file_url) venivano restituiti senza corpo in caso di UTF-8 non valido (HTTP 400, 403 o 502). Ora vengono restituiti con il corpo, con caratteri illeggibili come U+FFFD. Come in precedenza, non viene scritto nulla.