Enviar um Lote de Produto#

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

Corpo da Solicitação#

Envie processImages como um booleano JSON (true ou false), não como string como "true" ou "false". Integrações existentes que precisam de pré-processamento de imagem devem agora enviar explicitamente processImages: true.

Campos do Produto#

Reimportar Produtos Existentes#

Para atualizar os dados do produto, envie-o novamente por meio de POST /product-import/products. Os produtos são correspondidos por shopId e sku. Quando o mesmo SKU já existe na loja, o registro do produto existente é atualizado em vez de criar um duplicado, e os valores fornecidos pela importação mais recente substituem os valores armazenados correspondentes, incluindo campos como name, URLs do produto, status e dimensões.

O endpoint de importação em lote não é um endpoint de atualização parcial. Cada item enviado deve satisfazer todas as regras de campos obrigatórios do produto, mesmo quando o SKU já existe.

O SKU é a identidade de importação e não pode ser renomeado por meio de reimportação. Enviar um SKU diferente cria ou atualiza um produto diferente. Para substituir um SKU, exclua logicamente o produto antigo e importe o produto sob o novo SKU.

As informações do produto são atualizadas mesmo quando a imagem não mudou. O processamento de imagem é opcional em cada envio: defina processImages: true quando necessário. Um produto anteriormente importado sem processamento de imagem pode ser enviado novamente com essa opção habilitada.

Tipos de Produto Suportados#

A API aceita os seguintes valores exatos de productType, com diferenciação de maiúsculas e minúsculas. Vários nomes na mesma linha da tabela são aliases para o mesmo tipo de produto Ideal House.

Por exemplo, "Rugs", "Area Rugs" e "Area Rug" são todos válidos e são tratados como o mesmo tipo de produto. Qualquer valor não listado acima retorna 400 Bad Request.

Status da Importação#

O campo status opcional aceita os seguintes valores exatos:

Qualquer outro valor, incluindo sold_out, retorna 400 Bad Request.

Para Furniture, envios não ativos retornam produto status: inactive. Um envio ativo pode retornar unprocessed, indicando que o produto ainda não está pronto para exibição. Isso não significa que a geração de modelo 3D foi solicitada.

Geração de Modelo 3D para Furniture#

A geração de modelo 3D para Furniture é demorada e consome créditos, portanto não é realizada durante a importação do produto, mesmo quando processImages é true. Planejamos fornecer uma ação de geração na interface do usuário ou uma API separada de geração 3D no futuro. Se você precisar de modelos 3D agora, envie um e-mail para seu contato da Ideal House para que possamos providenciar a geração separadamente.

SKU e Comportamento de Atualização#

A Ideal House identifica um produto pela combinação de shopId e sku:

• Se o SKU não existir para a loja, um novo produto será criado.
• Se o SKU já existir para a loja, o produto existente será atualizado.

Isso torna seguro reenviar um produto com o mesmo SKU após um resultado de rede incerto. Use SKUs estáveis e não gere um novo SKU ao repetir o mesmo produto. Evite enviar o mesmo SKU mais de uma vez em um único lote.

Requisitos de Imagem#

• O URL deve ser acessível pelos servidores da Ideal House sem cookies, sessões de login ou cabeçalhos de solicitação personalizados.
• Use um URL estável que retorne a imagem diretamente.
• Mantenha a imagem original disponível até que o trabalho de importação atinja um status terminal.
• Problemas de download ou processamento de imagem são relatados como falhas em nível de item.
• Para criar imagens de tábuas do Piso, defina tanto processImages: true quanto processFloorImages: true.

Processamento de Imagem Opcional e Créditos#

O pré-processamento de imagem está desativado por padrão:

• Com processImages: false ou quando o campo for omitido, os produtos ativos usam suas imagens originais, sem remoção de fundo, otimização de textura ou divisão de piso. As informações do produto ainda são importadas ou atualizadas, e nenhum crédito de processamento de imagem é cobrado. Produtos não ativos seguem as regras de status descritas acima.
• Com processImages: true, os produtos ativos suportados recebem o processamento de imagem descrito abaixo. A geração de modelo 3D para Furniture não está incluída.

Os principais comportamentos de processamento são:

Mural e Wall Mural recebem as mesmas melhorias de imagem que Wall. Para melhores resultados, forneça imagens de produto completas e claras; Rugs e Wall Art regulares devem ter fundos brancos ou quase brancos, e as imagens Wall devem evitar distorção de perspectiva severa.

O processamento de imagem descrito acima custa 1 crédito por imagem processada pela primeira vez, incluindo otimização de textura Wall. Se um resultado processado existente pode ser reutilizado, nenhum crédito adicional de processamento é cobrado. Certifique-se de ter créditos suficientes antes de habilitar essa opção. Com créditos insuficientes, o processamento de imagem não prosseguirá e o produto pode permanecer unprocessed. Um lote de importação completed não confirma por si só que todas as imagens dos produtos foram processadas com sucesso.

Requisitos de Dimensão#

A API não possui um campo separado para unidade de dimensão. width é obrigatória. height é normalmente obrigatória, enquanto um produto Floor pode fornecer length em vez disso; quando ambos estão presentes, length é usado como o comprimento da tábua do piso. Números sem unidade e strings numéricas são interpretados como polegadas. Strings podem incluir in, ft, cm, mm ou m; os valores são validados como dimensões positivas e normalizados para polegadas antes do armazenamento. thickness é opcional e também aceita uma faixa como "3-4 mm", que é normalizada para "0.1-0.2 in".

dimension_display é um rótulo de exibição opcional e não é usado para validação de tamanho ou conversão de unidade. Pode usar a unidade e o formato voltados para o cliente que você deseja exibir, por exemplo "24 in x 36 in" ou "26 cm x 36 cm".

Exemplo de Solicitação#

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

Exemplo cURL (Processamento de Imagem Habilitado)#

Este exemplo habilita explicitamente o pré-processamento de imagem. Um novo resultado de remoção de fundo consome 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"
      }
    ]
  }'

Resposta Aceita#

Uma solicitação válida retorna 202 Accepted. O processamento continua de forma assí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
}

Se a loja já tiver um trabalho pending ou running em andamento, a API retorna 409 Conflict. Aguarde o término do trabalho atual antes de enviar outro lote.