API d'importation : importer des données via les méthodes POST et 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>"
        }
      }
    }
  ]
}

• Seul true active le mode strict ; depuis la version v2.122.12, les espaces en fin de chaîne ne sont plus pris en compte (?_strict=%20true est considéré comme true). Dans les boutiques antérieures à la version 4.9.173, envoyez la valeur sans espace à la fin. Les autres valeurs de _strict (par exemple 1 ou yes) et toute valeur de liste (?language[]=de, ?_strict[]=true) génèrent une erreur HTTP 400 INVALID_FILTER_VALUE avec le message details[] («… Nothing was written »). La vérification s’effectue avant que l’importation ne lise ou n’écrive quoi que ce soit.
• Une valeur vide signifie « non défini » ; depuis la version v2.122.12, un simple espace vide est également accepté pour _strict: l’importation fonctionne alors comme si le paramètre n’existait pas. L’importation continue d’ignorer les noms de paramètres inconnus.

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

Les champs supplémentaires d'un produit sont exclusivement définis via le champ extra_fields – et non en tant que champ de premier niveau du produit. Une clé telle que google_product_category placée juste à côté de products_model sera ignorée (et signalée dans la réponse sous la forme UNKNOWN_FIELD ).

À partir de la version 2.51.0, chacune des notations suivantes est acceptée – au choix via l’ID du champ ou le nom du champ (la casse et les espaces sont tolérés) :

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

La structure renvoyée par l’exportation JSON (objet indexé par ID de champ) peut également être réimportée sans modification.

Champs Google Shopping

Les champs du flux Google sont des champs supplémentaires standard dotés d'identifiants fixes :

Les onglets de produit (par exemple « Description des prestations », « Fiche technique », « Instructions de montage ») sont gérés via le champ tabs – un tableau plat d’objets d’onglet. Un format imbriqué comme {"de": […]} n’ est pas pris en charge et est ignoré sans message d’erreur (pas d’avertissement, pas d’onglets).

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

Comportement détaillé

• Création : toute entrée sans tab_id crée un nouvel onglet avec sa propre tab_id – y compris par langue. Les onglets multilingues sont donc envoyés sous la forme d’une entrée par langue (voir l’exemple ci-dessus) ; le front-end n’affiche, selon le filtre de langue, que les onglets de la langue active.
• Mise à jour : avec tab_id, l’onglet existant est mis à jour dans la langue indiquée – mais uniquement si la ligne de langue existe déjà. Une version linguistique manquante d’un onglet existant ne peut pas être créée a posteriori via l’API (pour cela, envoyez un nouvel onglet sans tab_id ).
• Pas de suppression en cas d’absence : les onglets non envoyés restent inchangés. La suppression des onglets s’effectue dans le backend au niveau du produit.
• Aller-retour d’exportation : GET /products renvoie les onglets sous forme d’objet indexé par tab_id (y compris tab_name, tab_content, language_id, sort_order).

Le stock, le stock de sécurité et le seuil de réapprovisionnement par entrepôt sont gérés dans l’importation de produits exclusivement via le champ storages – un tableau plat d’objets « entrepôt », chacun comportant storages_id (alias warehouse_id). Depuis la version 2.45.0, il s’agit d’une mise à jour partielle: une charge utile partielle telle que {"storages_id": 3, "products_reorder_level": 10} ne modifie que le seuil de réapprovisionnement de cet entrepôt et ne définit pas les autres colonnes de l’entrepôt sur 0.

Le système de gestion des stocks avancé doit être activé (EXTENDED_STORAGE_SYSTEM) ; sinon, le champ est ignoré et la réponse contient l'avertissement STORAGE_SYSTEM_DISABLED. Tous les champs, leur sémantique et les pièges à éviter sont décrits dans la section « Stocks et niveaux de réapprovisionnement par entrepôt » de la référence Products.

Pour POST /Import/JSON/media et PUT /Import/JSON/media/{id} (portée media:write), en tant que multipart/form-data et avec un corps JSON : un champ contenant exactement une valeur, sous forme de liste (champ de formulaire entity_type[]=… ou entity_type[key]=…, dans le corps JSON un tableau ou un objet, même vide) renvoie un code HTTP 400 INVALID_FIELD_VALUE avec field. Rien n’est lu ni écrit.

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

• Plusieurs fichiers sont traités en plusieurs appels ; le point de terminaison n'accepte qu'un seul fichier.
• Un champ dans une entrée de descriptions porte le même nom que son entrée sur field, par exemple descriptions[0].language_code. La vérification s'effectue avant la première écriture.
• Inchangé : descriptions est une liste par langue ; les champs inconnus sont ignorés comme auparavant.
• Les erreurs qui répètent un champ de formulaire (entity_type dans UNSUPPORTED_ENTITY_TYPE, target_folder, subfolder, file_url) apparaissaient auparavant sans tronc sans UTF-8 valide (HTTP 400, 403 ou 502). Désormais, elles s’affichent avec un tronc, les caractères illisibles étant remplacés par U+FFFD. Comme auparavant, rien n’est écrit.