Importação avançada

A importação e a exportação simples da seção anterior servem quando a planilha já está no formato do modelo. Esta seção cobre o resto: planilhas de ERP e de fornecedores com colunas de outros nomes, ajustes de valor durante a carga, simulação sem gravar e exportação com as colunas e o formato que você escolher. É o mesmo conjunto de rotas que a tela de importação do painel usa.

Como funciona

O fluxo de importação

1. Enviar o arquivo

   POST /advanced-import/upload lê a planilha, detecta o separador e devolve as colunas, as primeiras linhas e um mapeamento sugerido. Nada é gravado. Guarde o job_id.

2. Validar

   POST /advanced-import/validate aplica o mapeamento e as opções e conta quantos produtos seriam criados, atualizados e pulados, com os erros por linha. Repita até valid ser true.

3. Executar

   POST /advanced-import/execute grava. Com até 1.000 linhas o resultado vem na própria resposta; acima disso, vira trabalho em segundo plano. Use dry_run: true para ensaiar.

4. Acompanhar

   GET /advanced-import/jobs/{id} mostra o andamento e os erros. Veja também Jobs de importação.

O fluxo de exportação

Consulte GET /advanced-export/fields/products para saber as chaves de campo, escolha as que quer e chame POST /advanced-export/execute com os filtros e o formato. Se repetir a mesma seleção, salve como predefinição.

Campos e grupos

Os campos de produto são agrupados: basic (identificação, status, seller), pricing (preços e impostos), inventory (estoque e quantidade mínima/máxima), shipping (peso, dimensões, frete), content (descrições), seo, relationships (categorias, produto pai, grupos de usuários), images, features, variations e timestamps. Cada campo informa se é obrigatório na importação.

Conceitos-chave

Job

O job é um registro temporário que guarda o arquivo enviado, o mapeamento e o andamento. A mesma consulta vale para os dois conjuntos de rotas (/import/jobs/{id} e /advanced-import/jobs/{id}). Status: pending, processing, completed, failed.

Estratégia de importação

Valores e moeda

Preço em planilha é em reais. Se a sua planilha tem centavos inteiros, diga "price_format": "cents". Veja as opções em Assistente de importação.

Moderação

Quando a loja exige aprovação de produtos novos, os produtos importados podem cair em moderação em vez de ir direto ao ar. A validação e o job contam esses casos em moderation_count.

Endpoints

Erros comuns

• Pular a validação e executar direto: um mapeamento errado grava lixo. Valide, e ensaie com dry_run.
• Mapear a coluna ao contrário: o field_mapping é nome da coluna da planilha para campo do produto ("Código": "sku"), não o oposto.
• Esquecer o seller: produto novo exige vendor_id (coluna mapeada ou default_vendor_id).
• Ligar set_zero_quantities sem querer: zera o estoque de todo o catálogo antes da carga.
• Esperar 404 em validate ou execute com job_id errado: a resposta é 500.
• Assumir que a exportação avançada falha com status de erro: um erro no meio do arquivo chega dentro de um 200.
• Usar date_to como "até o fim do dia": ele vale a meia-noite de abertura do dia informado.

Próximos passos