Importação e exportação
Como exportar cadastros em planilha e importar produtos, categorias, características, marcas, clientes e preços por quantidade, com o mapa de todas as rotas.
Importar e exportar em lote é a forma de levar um catálogo inteiro para a Venddor (vindo de uma planilha ou de um ERP) e de tirar os dados da loja para conferir, corrigir fora e subir de novo. Esta seção cobre as rotas simples: uma chamada exporta um arquivo, outra recebe um arquivo e grava os registros. O assistente de importação em etapas, com mapeamento de colunas e predefinições, está em Importação avançada.
Como funciona
Exportar
Você chama um GET em /api/v1/admin/export/<cadastro> e recebe o arquivo como anexo (Content-Disposition: attachment). O formato padrão é CSV em UTF-8 com BOM, para o Excel abrir os acentos certos. Para receber XLSX ou XLS, mande ?format=xlsx ou ?format=xls. Um valor de format desconhecido cai em CSV.
Os filtros vão na query string. ids aceita uma lista de ids separados por vírgula e exporta só esses registros. status aceita a letra (A, H, D) ou a palavra por extenso em português ou inglês (ativo, oculto, inativo, active...). Uma palavra que a plataforma não conhece volta 400 unknown_record_status, em vez de um arquivo vazio.
Importar
Você envia o arquivo em multipart/form-data, no campo file. A plataforma lê o cabeçalho, detecta o separador (, ou ;), valida linha a linha e grava. O resultado é um resumo (ImportResult) com contagens e a lista de erros por linha. Para produtos, a importação é um upsert pelo SKU: SKU novo cria, SKU existente atualiza.
Registros e letras de status
Os cadastros guardam o status em uma letra:
| Letra | Significado | Aparece na loja |
|---|---|---|
A | Ativo | Sim |
H | Oculto | Não |
D | Desativado | Não |
Na importação de produtos, uma célula de status que a plataforma não reconhece não derruba a linha: o produto vira ativo e a linha ganha um aviso no relatório de erros.
Privilégios por grupo de rotas
| Rotas | Privilégio exigido |
|---|---|
| Exportar produtos, modelos de produto e categoria, preços por quantidade; importar produtos, imagens em ZIP e preços por quantidade | manage_catalog |
| Exportar e importar categorias | manage_categories |
| Exportar e importar características e marcas | manage_features |
| Exportar e importar usuários | manage_users |
| Exportar pedidos | manage_orders |
| Exportar páginas e promoções | manage_content |
| Importar XML e importar de uma URL | manage_settings |
| Consultar job, andamento, cancelar e baixar erros | manage_catalog |
Sem o privilégio, a resposta é 403. A exportação de usuários traz CPF e CNPJ: conceda esse privilégio com cuidado.
Conceitos-chave
Separador, decimal e acentos
O modelo de produtos usa ; e vírgula decimal (49,90), o padrão brasileiro do Excel. Os modelos de categorias e promoções usam ,. Na importação, o separador é detectado sozinho. Preços aceitam o prefixo R$ e a vírgula decimal; valores negativos são recusados.
Importação síncrona e assíncrona
A rota de importação de produtos escolhe o caminho pelo tamanho do arquivo. Até 256 linhas de dados e 1 MiB, com as opções padrão, ela grava na hora e devolve 200 com o resumo. Acima disso, ou se você mandar qualquer opção diferente do padrão, ela cria um job e devolve 202. Veja Importar produtos.
Jobs
Um job tem os status pending, processing, completed e failed. Você acompanha pelo andamento, pode cancelar e baixa um CSV com os erros por linha. Veja Jobs de importação.
Datas e filtros de data
date_from e date_to usam YYYY-MM-DD. Se date_from for maior que date_to, a resposta é 400 invalid_date_range.
Endpoints
| Método | Caminho | Para que serve | Auth |
|---|---|---|---|
| GET | /api/v1/admin/export/products | Exporta produtos | admin |
| GET | /api/v1/admin/export/categories | Exporta categorias | admin |
| GET | /api/v1/admin/export/features | Exporta características | admin |
| GET | /api/v1/admin/export/brands | Exporta marcas | admin |
| GET | /api/v1/admin/export/qty-discounts | Exporta preços por quantidade | admin |
| GET | /api/v1/admin/export/users | Exporta usuários | admin |
| GET | /api/v1/admin/export/orders | Exporta pedidos | admin |
| GET | /api/v1/admin/export/pages | Exporta páginas de conteúdo | admin |
| GET | /api/v1/admin/export/promotions | Exporta promoções | admin |
| GET | /api/v1/admin/export/products/template | Baixa o modelo de produtos | admin |
| GET | /api/v1/admin/export/categories/template | Baixa o modelo de categorias | admin |
| GET | /api/v1/admin/export/features/template | Baixa o modelo de características | admin |
| GET | /api/v1/admin/export/brands/template | Baixa o modelo de marcas | admin |
| GET | /api/v1/admin/export/qty-discounts/template | Baixa o modelo de preços por quantidade | admin |
| GET | /api/v1/admin/import/products/template | Baixa o modelo de importação de produtos | admin |
| POST | /api/v1/admin/import/products/preview | Simula a importação sem gravar produtos | admin |
| POST | /api/v1/admin/import/products | Importa produtos de um arquivo ou de uma URL | admin |
| GET | /api/v1/admin/import/jobs/{id} | Consulta um job de importação | admin |
| GET | /api/v1/admin/import/jobs/{id}/progress | Andamento resumido do job | admin |
| POST | /api/v1/admin/import/jobs/{id}/cancel | Pede o cancelamento do job | admin |
| GET | /api/v1/admin/import/jobs/{id}/errors.csv | Baixa os erros por linha | admin |
| POST | /api/v1/admin/import/categories | Importa categorias | admin |
| POST | /api/v1/admin/import/features | Importa características | admin |
| POST | /api/v1/admin/import/brands | Importa marcas | admin |
| POST | /api/v1/admin/import/users | Importa usuários | admin |
| POST | /api/v1/admin/import/qty-discounts | Importa preços por quantidade (assíncrono) | admin |
| POST | /api/v1/admin/import/product-images-zip | Importa imagens de produtos de um ZIP | admin |
| POST | /api/v1/admin/import/xml | Envia um XML para o assistente de importação | admin |
| POST | /api/v1/admin/import/from-url | Baixa um arquivo de uma URL para o assistente | admin |
Erros comuns
- Mandar o arquivo no campo errado: o campo precisa se chamar
file. Qualquer outro nome volta 400missing file field in form. - Mandar preço em centavos numa planilha:
4990é lido como R$ 4.990,00. Planilhas usam reais (49,90). - Importar produto sem
vendor_id: produto novo exige o seller. Sem ele, a linha é recusada. - Esperar arquivo vazio de uma exportação filtrada por uma palavra de status inventada: a API recusa com 400, mas uma letra solta (
Z) passa direto e devolve um arquivo só com o cabeçalho. - Tratar 202 como "terminou": 202 só diz que o job começou. Consulte o job até
completedoufailed. - Ler o corpo de um erro de exportação como arquivo: quando falha antes de escrever, o corpo é JSON (
{"error", "detail"}). - Reenviar a mesma planilha de preços por quantidade esperando duplicar: o modo padrão (
merge) atualiza as faixas existentes.