Soumettre un lot de produits#

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

Corps de la requête#

Envoyez processImages en tant que booléen JSON (true ou false), et non en tant que chaîne telle que "true" ou "false". Les intégrations existantes qui ont besoin d'un prétraitement d'images doivent désormais explicitement envoyer processImages: true.

Champs du produit#

Réimportation des produits existants#

Pour mettre à jour les données du produit, soumettez à nouveau le produit via POST /product-import/products. Les produits sont associés par shopId et sku. Lorsqu'un même SKU existe déjà dans la boutique, la fiche produit existante est mise à jour au lieu de créer un doublon, et les valeurs fournies lors du dernier import écrasent les valeurs stockées correspondantes, y compris les champs tels que name, les URLs du produit, le statut et les dimensions.

Le point de terminaison d'importation par lot ne prend pas en charge les mises à jour partielles. Chaque élément soumis doit respecter toutes les règles relatives aux champs produit obligatoires, même lorsque le SKU existe déjà.

Le SKU est l'identité d'importation et ne peut pas être renommé par réimportation. La soumission d'un SKU différent crée ou met à jour un produit différent. Pour remplacer un SKU, supprimez logiquement l'ancien produit et importez le produit sous le nouveau SKU.

Les informations du produit sont mises à jour même lorsque l'image n'a pas changé. Le traitement des images est optionnel à chaque soumission : définissez processImages: true lorsque cela est nécessaire. Un produit précédemment importé sans traitement d'images peut être soumis à nouveau avec cette option activée.

Types de produits pris en charge#

L'API accepte les valeurs productType exactes et sensibles à la casse suivantes. Plusieurs noms dans une même ligne sont des alias pour le même type de produit Ideal House.

Par exemple, "Rugs", "Area Rugs" et "Area Rug" sont tous valides et sont traités comme le même type de produit. Toute valeur non listée ci-dessus renvoie 400 Bad Request.

Statut d'importation#

Le champ optionnel status accepte les valeurs exactes suivantes :

Toute autre valeur, y compris sold_out, retourne 400 Bad Request.

Pour les meubles, les soumissions non actives renvoient un produit status: inactive. Une soumission active peut renvoyer unprocessed, ce qui signifie que le produit n'est pas encore prêt à être affiché. Cela ne veut pas dire que la génération 3D a été demandée.

Génération de modèles 3D pour le mobilier#

La génération de modèle 3D pour les meubles est longue et consomme des crédits, elle n'est donc pas exécutée lors de l'importation du produit, même lorsque processImages est true. Nous prévoyons de proposer une action de génération dans l'interface utilisateur ou une API de génération 3D distincte à l'avenir. Si vous avez besoin de modèles 3D dès maintenant, veuillez envoyer un e-mail à votre contact Ideal House afin que nous puissions organiser la génération séparément.

Comportement des SKU et des mises à jour#

Ideal House identifie un produit par la combinaison de shopId et sku :

• Si le SKU n'existe pas pour le magasin, un nouveau produit est créé.
• Si le SKU existe déjà pour le magasin, le produit existant est mis à jour.

Cela rend sécurisée la resoumission d'un produit avec le même SKU après un résultat réseau incertain. Utilisez des SKU stables et ne générez pas de nouveau SKU lors de la nouvelle soumission du même produit. Évitez d'envoyer le même SKU plus d'une fois dans un même lot.

Exigences relatives aux images#

• L'URL doit être accessible par les serveurs Ideal House sans cookies, sessions de connexion ou en-têtes de requête personnalisés.
• Utilisez une URL stable qui retourne l'image directement.
• Gardez l'image source disponible jusqu'à ce que la tâche d'importation atteigne un statut terminal.
• Les problèmes de téléchargement ou de traitement des images sont signalés en tant qu'échecs au niveau de l'élément.
• Pour créer des images de planches de sol, définissez à la fois processImages: true et processFloorImages: true.

Traitement des images optionnel et crédits#

Le prétraitement des images est désactivé par défaut :

• Avec processImages: false ou lorsque le champ est omis, les produits actifs utilisent leurs images originales sans suppression de l'arrière-plan, optimisation de texture ou découpage en lames de revêtement de sol. Les informations du produit sont toujours importées ou mises à jour, et aucun crédit de traitement d'image n'est facturé. Les produits non actifs suivent les règles de statut décrites ci-dessus.
• Avec processImages: true, les produits actifs pris en charge reçoivent le traitement d'image décrit ci-dessous. La génération 3D pour les meubles n'est pas incluse.

Les principaux comportements de traitement sont :

Mural et Wall Mural reçoivent les mêmes améliorations d'image que Wall. Pour obtenir les meilleurs résultats, fournissez des images produits complètes et claires ; les tapis et les œuvres murales classiques doivent avoir des arrière-plans blancs ou quasi blancs, et les images murales doivent éviter une distorsion de perspective sévère.

Le traitement d'image décrit ci-dessus coûte 1 crédit par image nouvellement traitée, y compris l'optimisation de texture pour Wall. Si un résultat traité existant peut être réutilisé, aucun crédit de traitement supplémentaire n'est facturé. Assurez-vous d'avoir suffisamment de crédits avant d'activer cette option. En cas de crédits insuffisants, le traitement d'image ne sera pas exécuté et le produit peut rester unprocessed. Un lot d'import completed ne confirme pas à lui seul que chaque image de produit a été traitée avec succès.

Exigences relatives aux dimensions#

L'API ne dispose pas de champ distinct pour l'unité de dimension. width est requis. height est normalement requis, tandis qu'un produit de type Sol peut fournir length à la place ; lorsque les deux sont présents, length est utilisé comme longueur de planche de sol. Les nombres sans unité et les chaînes numériques sont interprétés comme des pouces. Les chaînes peuvent inclure in, ft, cm, mm ou m ; les valeurs sont validées comme des dimensions positives et normalisées en pouces avant le stockage. thickness est optionnel et accepte également une plage telle que "3-4 mm", qui est normalisée en "0.1-0.2 in".

dimension_display est une étiquette d'affichage optionnelle et n'est pas utilisée pour la validation de taille ou la conversion d'unité. Elle peut utiliser l'unité et le format affichés au client, par exemple "24 in x 36 in" ou "26 cm x 36 cm".

Exemple de requête#

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

Exemple cURL avec traitement des images activé#

Cet exemple active explicitement le prétraitement d'image. Un nouveau résultat de suppression d'arrière-plan consomme 1 crédit.

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

Réponse acceptée#

Une requête valide renvoie 202 Accepted. Le traitement se poursuit de manière asynchrone.

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

Si la boutique a déjà une tâche au statut pending ou running, l'API renvoie 409 Conflict. Attendez que la tâche en cours se termine avant de soumettre un autre lot.