Enviar un lote de productos#

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

Cuerpo de la solicitud#

Envía processImages como un booleano en formato JSON (true o false), no como una cadena como "true" o "false". Las integraciones existentes que necesiten preprocesamiento de imágenes deben enviar explícitamente processImages: true.

Campos del producto#

Reimportar productos existentes#

Para actualizar los datos del producto, envíalo nuevamente a través de POST /product-import/products. Los productos se emparejan por shopId y sku. Cuando el mismo SKU ya existe en la tienda, el registro del producto existente se actualiza en lugar de crear uno duplicado, y los valores proporcionados por la importación más reciente sobrescriben los valores almacenados correspondientes, incluidos campos como name, las URLs del producto, el estado y las dimensiones.

El endpoint de importación por lotes no admite actualizaciones parciales. Cada elemento enviado debe cumplir todas las reglas de los campos obligatorios del producto, incluso cuando el SKU ya existe.

El SKU es la identidad de importación y no puede cambiarse de nombre mediante la reimportación. Enviar un SKU diferente crea o actualiza un producto diferente. Para reemplazar un SKU, elimina lógicamente el producto antiguo e importa el producto bajo el nuevo SKU.

La información del producto se actualiza incluso cuando la imagen no ha cambiado. El procesamiento de imágenes es opcional en cada envío: establece processImages: true cuando sea necesario. Un producto importado previamente sin procesamiento de imágenes puede enviarse nuevamente con esta opción habilitada.

Tipos de producto admitidos#

La API acepta los siguientes valores exactos de productType, que distinguen entre mayúsculas y minúsculas. Los distintos nombres de una misma fila son alias del mismo tipo de producto de Ideal House.

Por ejemplo, "Rugs", "Area Rugs" y "Area Rug" son válidos y se tratan como el mismo tipo de producto. Cualquier valor no listado arriba devuelve 400 Bad Request.

Estado de importación#

El campo opcional status acepta los siguientes valores exactos:

Cualquier otro valor, incluido sold_out, devuelve 400 Bad Request.

Para Muebles, los envíos no activos devuelven el producto status: inactive. Un envío activo puede devolver unprocessed, lo que significa que el producto aún no está listo para su visualización. Esto no significa que se haya solicitado la generación de 3D.

Generación de modelos 3D para muebles#

La generación de modelos 3D para muebles es lenta y consume créditos, por lo que no se realiza durante la importación del producto, incluso cuando processImages es true. Planeamos ofrecer una acción de generación en la interfaz de usuario o una API independiente para generar modelos 3D en el futuro. Si necesitas modelos 3D ahora, envía un correo electrónico a tu contacto de Ideal House para que podamos organizar la generación por separado.

SKU y comportamiento de actualización#

Ideal House identifica un producto por la combinación de shopId y sku:

• Si el SKU no existe para la tienda, se crea un producto nuevo.
• Si el SKU ya existe para la tienda, se actualiza el producto existente.

Esto hace seguro volver a enviar un producto con el mismo SKU después de un resultado de red incierto. Usa SKUs estables y no generes un nuevo SKU al reintentar el mismo producto. Evita enviar el mismo SKU más de una vez en un solo lote.

Requisitos de imagen#

• La URL debe ser accesible por los servidores de Ideal House sin cookies, sesiones de inicio de sesión ni encabezados de solicitud personalizados.
• Usa una URL estable que devuelva la imagen directamente.
• Mantén la imagen fuente disponible hasta que el trabajo de importación alcance un estado terminal.
• Los problemas de descarga o procesamiento de imágenes se reportan como fallas a nivel de elemento.
• Para crear imágenes de tablas de Floor, establece tanto processImages: true como processFloorImages: true.

Procesamiento de imágenes opcional y créditos#

El preprocesamiento de imágenes está deshabilitado de forma predeterminada:

• Con processImages: false o cuando el campo se omite, los productos activos usan sus imágenes originales sin eliminación de fondo, optimización de textura ni división de imágenes de materiales de suelo. La información del producto sigue importándose o actualizándose, y no se cobra ningún crédito de procesamiento de imágenes. Los productos no activos siguen las reglas de estado descritas anteriormente.
• Con processImages: true, los productos activos compatibles reciben el procesamiento de imágenes descrito a continuación. La generación de modelos 3D para muebles no está incluida.

Los principales comportamientos de procesamiento son:

Mural y Wall Mural reciben las mismas mejoras de imagen que Wall. Para obtener mejores resultados, proporciona imágenes completas y claras del producto; las alfombras y el arte de pared regular deben tener fondos blancos o casi blancos, y las imágenes de pared deben evitar una distorsión de perspectiva severa.

El procesamiento de imágenes descrito anteriormente cuesta 1 crédito por imagen procesada por primera vez, incluida la optimización de texturas de Pared. Si se puede reutilizar un resultado procesado existente, no se cobra ningún crédito adicional de procesamiento. Asegúrate de tener créditos suficientes antes de habilitar esta opción. Con créditos insuficientes, el procesamiento de imágenes no se llevará a cabo y el producto puede permanecer unprocessed. Un lote de importación con estado completed no confirma por sí mismo que todas las imágenes de producto se procesaron correctamente.

Requisitos de dimensión#

La API no tiene un campo separado de unidad de dimensión. width es obligatorio. height normalmente es requerido, mientras que un producto Floor puede proporcionar length en su lugar; cuando ambos están presentes, length se usa como el largo de la tabla del piso. Los números sin unidad y las cadenas numéricas se interpretan como pulgadas. Las cadenas pueden incluir in, ft, cm, mm o m; los valores se validan como dimensiones positivas y se normalizan a pulgadas antes del almacenamiento. thickness es opcional y también acepta un rango como "3-4 mm", que se normaliza a "0.1-0.2 in".

dimension_display es una etiqueta de visualización opcional y no se usa para validación de tamaño ni conversión de unidades. Puede usar la unidad y el formato que desees mostrar al cliente, por ejemplo "24 in x 36 in" o "26 cm x 36 cm".

Ejemplo de solicitud#

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

Ejemplo cURL (procesamiento de imágenes habilitado)#

Este ejemplo habilita explícitamente el preprocesamiento de imágenes. Un nuevo resultado de eliminación de fondo consume 1 crédito.

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

Respuesta aceptada#

Una solicitud válida devuelve 202 Accepted. El procesamiento continúa de forma asíncrona.

{
  "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 tienda ya tiene un trabajo en estado pending o running, la API devuelve 409 Conflict. Espera a que el trabajo actual termine antes de enviar otro lote.