VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Lote, importação e exportação

Importar um arquivo

Cria ou atualiza produtos a partir de um arquivo CSV ou XLSX em uma única chamada, e baixa o modelo CSV com as colunas esperadas.

Use esta rota quando você tem uma planilha (de um ERP, de um fornecedor ou de uma migração) e quer carregá-la em uma requisição. Cada linha vira um produto: se já existe um produto com o mesmo SKU ele é atualizado, senão é criado. A chamada é síncrona: responde quando o arquivo foi processado, com as contagens e os problemas linha a linha.

Para arquivos grandes, para mapear colunas com nomes diferentes dos nossos, ou para pré-visualizar antes de gravar, use o Assistente de importação. Os dois leem os mesmos formatos de arquivo.

Formatos e limites
  • CSV (.csv, .txt): o separador é detectado nas primeiras linhas, ; (Excel brasileiro) ou ,. UTF-8, com ou sem BOM.
  • XLSX (.xlsx, .xlsm): lê-se a primeira planilha, com o cabeçalho na primeira linha.
  • Tamanho máximo do arquivo nesta rota: 100 MiB (413 acima disso).
  • Qualquer outra extensão é recusada com 415.

Baixar o modelo

GET/api/v1/admin/products/import/templateAdmin

Baixar o modelo CSV

Devolve um CSV pequeno (Content-Type: text/csv, arquivo produtos_modelo.csv) com o cabeçalho e duas linhas de exemplo. Sem parâmetros.

As colunas do modelo, em ordem:

ColunaSignificado no exemplo
product_codeSKU (SKU-001). Apelido de sku.
nameNome do produto.
pricePreço de venda em reais, com vírgula (49,90).
list_pricePreço "de", opcional (59,90).
statusA ativo, H oculto, D desativado.
quantityEstoque (100).
weightPeso em kg (0,500).
category_idCategoria (o exemplo mostra um nome).
vendor_idSeller (o exemplo mostra um nome, slug, e-mail ou id).
descriptionDescrição completa.
short_descriptionResumo curto.
bash
curl "$BASE_URL/api/v1/admin/products/import/template" \
  -H "Authorization: Bearer $TOKEN" -o produtos_modelo.csv
200Modelo (CSV)
text
product_code;name;price;list_price;status;quantity;weight;category_id;vendor_id;description;short_description
SKU-001;Produto Exemplo 1;49,90;59,90;A;100;0,500;Higiene e Beleza;Nome do vendedor (ou slug/e-mail/ID);Descrição completa;Resumo curto
SKU-002;Produto Exemplo 2;129,00;;A;50;1,200;Higiene e Beleza;Nome do vendedor (ou slug/e-mail/ID);Outra descrição;Outro resumo
O modelo usa nomes, esta rota exige UUIDs

Nas linhas de exemplo, category_id e vendor_id trazem nomes legíveis. O assistente resolve nomes (seller por razão social, slug, e-mail ou id; categoria por nome ou caminho), mas a rota de uma chamada abaixo exige UUIDs reais nas duas colunas. Importar o modelo como foi baixado pela rota de uma chamada faz toda linha falhar com um erro de banco de dados sobre UUID inválido.

Importar

POST/api/v1/admin/products/importAdmin

Importar produtos de CSV ou XLSX em uma chamada

Envie um corpo multipart/form-data. Exige o privilégio manage_catalog.

Colunas (os nomes do cabeçalho não diferenciam maiúsculas; no arquivo só name e price são obrigatórias, mais um seller em toda linha):

Coluna (apelidos)TipoObservações
sku (product_code)textoIdentifica o produto. Até 128 caracteres. Se vazio, gera-se um SKU IMP-... e toda importação cria um produto novo para essa linha.
nametextoObrigatório, até 512 caracteres. O HTML é removido.
slugtextoNome na URL. Gerado a partir do nome quando vazio. Se já existir, acrescenta-se um sufixo e vem um aviso.
pricedecimalObrigatório. Veja a regra de preço abaixo.
list_price, cost_price, shipping_freightdecimalOpcionais. Vazio mantém o valor atual.
quantity (stock_quantity, qty)inteiroSe a coluna não existe, o estoque atual é preservado.
min_quantity, max_quantity, quantity_stepinteiroRegras de quantidade de compra. quantity_step vale 1 por padrão.
statustextoA, D, H (qualquer caixa) ou active, disabled, hidden. Vazio ou não reconhecido vira ativo.
category_iduuidUUID da categoria.
vendor_iduuidUUID do seller. Obrigatório em toda linha, a menos que você mande o campo de formulário vendor_id.
description, short_description (short_desc), promo_texttextoAté 65.535 caracteres na descrição. HTML inseguro é removido.
weight, length, width, heightnúmeroKg e cm.
free_shippingtextoY, yes, true, 1, s, sim valem verdadeiro; qualquer outra coisa é falso.
meta_title (seo_title), meta_description (seo_description), meta_keywords (keywords)textoTextos de SEO.

Regra do preço. Um valor com separador decimal (49.90, 49,90, R$ 49,90) é lido em reais. Um valor sem separador é lido em centavos: 4990 é R$ 49,90, mas 50 é R$ 0,50. Escreva sempre duas casas.

Corpo da requisição (multipart/form-data)

filefileobrigatório
O arquivo CSV ou XLSX.
update_existingbooleanpadrão: true
Mande false para pular as linhas cujo SKU já existe (vão para os erros, nada é alterado).
skip_errorsbooleanpadrão: true
Mande false para parar na primeira linha ruim. As linhas anteriores continuam importadas.
vendor_iduuid
Seller aplicado a todas as linhas, sobrepondo a coluna.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/products/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.csv" \
  -F "update_existing=true"

Um arquivo que funciona com as colunas acima:

text
sku;name;price;quantity;status;category_id;vendor_id
CAM-001;Camiseta Azul;49,90;10;A;345ac33e-4dcd-4d60-bedf-a2c2d47897d9;9d9d9d56-eb43-4719-889d-055632f7c7da
CAN-002;Caneca Branca;4990;20;A;345ac33e-4dcd-4d60-bedf-a2c2d47897d9;9d9d9d56-eb43-4719-889d-055632f7c7da

Resposta

200Importação concluída
json
{
  "total": 3,
  "created": 3,
  "imported": 3,
  "updated": 0,
  "skipped": 0,
  "errors": [],
  "warnings": null
}
200Algumas linhas recusadas
json
{
  "total": 2,
  "created": 0,
  "imported": 0,
  "updated": 0,
  "skipped": 2,
  "errors": [
    { "row": 2, "message": "db error: pq: invalid input syntax for type uuid: \"Higiene e Beleza\" (22P02)" },
    { "row": 3, "field": "price", "message": "price is required" }
  ],
  "warnings": null
}

Campos da resposta

totalinteger
Linhas de dados lidas (o cabeçalho não conta).
createdinteger
Produtos novos. imported é o mesmo número, mantido para clientes antigos.
updatedinteger
Produtos existentes alterados.
skippedinteger
Linhas não importadas; cada uma tem uma entrada em errors.
errorsarray
Sempre um array. Cada item: row (número da linha na planilha, o cabeçalho é a linha 1), field (quando conhecido) e message.
warningsarray
Linhas que foram importadas mas não exatamente como escritas, por exemplo um slug que já estava em uso. null quando vazio.

Erros

StatusQuandoExemplo de corpo
400A requisição não é multipart{"error":"failed to parse multipart form","detail":"request Content-Type isn't multipart/form-data"}
400Sem o campo file{"error":"missing file field in form","detail":"..."}
400Arquivo vazio, ou linha vazia no meio dos dados{"error":"csv_empty","detail":"uploaded file is empty"} ou {"error":"csv_empty_row","detail":"..."}
400XLSX malformado{"error":"invalid spreadsheet","detail":"..."}
401 / 403Sem token / sem manage_catalog{"error":"missing authorization header"} / {"error":"insufficient privileges","required":"manage_catalog"}
413Arquivo maior que 100 MiB{"error":"file too large","detail":"CSV upload exceeds the 100 MiB limit"}
415Extensão diferente de .csv, .txt, .xml, .xlsx ou .xlsm{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}
500Falta a coluna obrigatória name ou price no cabeçalho{"error":"import products failed","detail":"missing required column: name"}
A importação grava na hora e aqui não tem desfazer

Esta rota não tem simulação e não devolve undo_id. Atualizar por SKU sobrescreve nome, preço, descrição e as outras colunas presentes. Teste o arquivo antes na pré-visualização do assistente. Uma célula de status vazia ou não reconhecida deixa o produto ativo, então uma reimportação pode reativar produtos ocultos.

Confira os erros mesmo com 200

Um arquivo em que todas as linhas falharam ainda responde 200. Compare created + updated com total e leia errors.

Veja também

  • Assistente de importação
  • Exportar
  • Criar um produto
Anterior
Edição estilo planilha
Próxima
Assistente de importação
Nesta página
  • Baixar o modelo
  • Importar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também