Assistente de importação

O assistente de importação carrega produtos em massa a partir de uma planilha, mesmo que as colunas dela tenham nomes diferentes dos da plataforma. Ele separa o trabalho em etapas, para você ver o que vai acontecer antes de gravar: envia o arquivo, confere o mapeamento, executa e acompanha. É o caminho certo para planilhas grandes ou com colunas livres; para cargas pequenas no formato exato da plataforma, existe o CSV direto.

Como funciona

1. Envie o arquivo

   upload lê o cabeçalho, mostra 5 linhas de exemplo e devolve job_id, a lista de campos disponíveis e um auto_mapping com a sugestão da plataforma.

2. Ajuste o mapeamento

   Corrija o auto_mapping onde a sugestão errou. Quando o mapeamento ficar bom, salve-o como modelo para as próximas planilhas.

3. Valide

   validate percorre todas as linhas e diz quantas serão criadas, atualizadas ou ignoradas, com erros e avisos. Corrija a planilha e envie de novo até valid: true.

4. Execute

   execute grava. Use options.dry_run: true para um ensaio completo que não grava nada.

5. Acompanhe

   Consulte status até chegar a completed ou failed.

Conceitos importantes

Campos principais

O mapeamento liga cada coluna da planilha a um destes campos (a lista completa vem em available_fields). A importação exige ao menos uma coluna de identidade (name, sku, barcode ou id); para criar produto novo pelo nome, também é preciso a coluna price.

Preço: o formato importa

No execute, options.price_format define como ler a coluna de preço: auto (padrão) trata 49,90 e 49.90 como reais, mas um inteiro puro como centavos; decimal lê tudo como reais (50 = R$ 50,00); cents lê tudo como centavos e recusa decimais. Para planilhas sem vírgula use decimal e evite surpresa.

Categorias

Mapeie category_path (por exemplo Roupas///Camisetas, com o delimitador de options.category_delimiter, padrão ///) ou category_name, e use options.create_categories: true para criar as que faltarem. As categorias criadas por um seller ficam dele (veja Categorias próprias).

Endpoints

Erros comuns

1. Pular a validação. execute com mapeamento errado grava lixo. Rode validate e confira will_create, will_update e os erros.
2. Planilha com linha em branco. Linha vazia é erro fatal (fatal: true): remova a linha e valide de novo.
3. Esperar que status já traga o fim em planilhas grandes. Acima de 1.000 linhas a execução é assíncrona; repita status.
4. Mandar set_zero_quantities. Em loja multi-seller essa opção zera o estoque de todos os produtos da loja, não só dos seus. Nunca use na API do seller.
5. Preço sem vírgula na planilha. 4990 vira R$ 49,90 no modo auto, mas 50 vira R$ 0,50. Fixe price_format.
6. Reaproveitar um job_id depois de executar. O arquivo temporário é apagado ao fim; envie a planilha de novo.

Próximos passos