Respostas de Erro#

Código HTTP	Significado	Ação recomendada
`400 Bad Request`	O corpo da requisição ou os parâmetros de consulta são inválidos.	Corrija a requisição antes de tentar novamente.
`401 Unauthorized`	As credenciais estão ausentes, inválidas, expiradas ou inativas.	Verifique os cabeçalhos de autenticação ou entre em contato com Ideal House.
`403 Forbidden`	O `shopId` solicitado não está associado às credenciais.	Use o Shop ID atribuído às credenciais.
`404 Not Found`	Não há status de importação ou produto correspondente disponível.	Verifique o Shop ID e o ID do Produto ou SKU solicitado.
`409 Conflict`	Há outra tarefa de importação ativa para a loja.	Aguarde a conclusão da tarefa de importação atual.
`429 Too Many Requests`	A taxa de requisições é muito alta.	Retente com backoff exponencial e jitter.
`500 Internal Server Error`	O serviço encontrou um erro inesperado.	Retente com backoff exponencial. Contate a Ideal House se o erro persistir.
`502 Bad Gateway` ou `503 Service Unavailable`	O API está temporariamente indisponível.	Retente com backoff exponencial.

Um erro de validação pode usar o seguinte formato:

json

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

O texto em message pode variar. Use o código de status HTTP e os campos de resposta documentados para a lógica do programa.

Orientações de Retentativa e Recuperação#

Faça polling a cada 2 a 5 segundos enquanto a tarefa estiver pending ou running.
Para respostas 429, 500, 502 e 503, use backoff exponencial com jitter e defina um limite máximo de retentativas.
Não realize retentativa automática para respostas 400, 401 ou 403 sem corrigir a requisição ou as credenciais.
Após 409, aguarde até que a tarefa ativa atinja completed ou failed.
Se o envio expirar antes de receber uma resposta, consulte o endpoint de status antes de enviar o lote novamente.
Retentar o mesmo produto com o mesmo SKU é seguro, pois as importações usam comportamento de criar-atualizar.
Após uma tarefa concluída com falhas em nível de item, envie um novo lote contendo apenas os produtos com falha.
Após uma falha em nível de tarefa, os produtos contados em successCount podem já ter sido atualizados. Reenviar o lote original com os mesmos SKUs é seguro.
Uma exclusão já pode ter sido aplicada mesmo que a requisição retorne 503. Retentar a mesma requisição de exclusão é seguro.

O endpoint de status destina-se a acompanhar a tarefa ativa ou mais recente, não um histórico permanente de importações. Armazene o lote enviado, jobId, respostas de status e o resultado final em seu próprio sistema para conciliação e suporte.

Lista de Verificação de Produção#

Armazene o Client Secret em um gerenciador de segredos ou ambiente de servidor protegido.
Use um SKU estável e único para cada produto.
Envie no máximo 500 produtos por requisição.
Certifique-se de que os URLs das imagens estejam acessíveis publicamente e permaneçam disponíveis durante o processamento.
Defina explicitamente processImages: true apenas quando o pré-processamento de imagem for necessário e a taxa associada de 1 crédito por imagem for aceita. Caso contrário, omita-o ou defina como false.
Ative a divisão de piso apenas definindo tanto processImages quanto processFloorImages como true.
Forneça name, imageUrl, productUrl, width, height e um productType compatível para cada produto.
Quando fornecido, defina status como active, inactive, out_of_stock ou invalid.
Envie dimensões como valores positivos com uma unidade compatível, ou omita a unidade para usar polegadas; os valores armazenados são normalizados para polegadas.
Persista o jobId retornado e compare-o com as respostas de status subsequentes.
Considere completed com failedCount > 0 como um sucesso parcial.
Pageine pela lista de produtos em vez de solicitar um catálogo ilimitado.
Forneça exatamente um de productId ou sku para operações de exclusão.
Implemente retentativas limitadas com backoff exponencial e jitter.

Para credenciais, valores de integração, mapeamento de tipos de produto ou problemas persistentes de integração, entre em contato com seu representante de integração da Ideal House.