API atual/Referência completa/Importação e exportação

Importar outros cadastros

Importa categorias, características, marcas, usuários e preços por quantidade a partir de planilha, com o resumo de criados, atualizados e erros.

Além de produtos, a plataforma importa os cadastros que o catálogo e a base de clientes usam. Todas as rotas desta página recebem multipart/form-data com a planilha no campo file (.csv, .txt, .xml, .xlsx ou .xlsm), detectam o separador e respondem com o mesmo resumo de importação (ImportResult). A exceção é a de preços por quantidade, que sempre roda em segundo plano.

O resumo tem este formato, e os campos errors e warnings estão sempre presentes (vazios quando não há problema):

200Resumo de importação

json

{
  "total": 3,
  "created": 2,
  "imported": 2,
  "updated": 1,
  "skipped": 0,
  "errors": [],
  "warnings": []
}

Campos do resumo

totalinteger

Linhas de dados lidas.

createdinteger

Registros criados. imported repete o mesmo valor (nome antigo).

updatedinteger

Registros atualizados.

skippedinteger

Linhas puladas, por erro ou por já existirem (usuários).

errorsarray

Problemas por linha: row (a linha da planilha, o cabeçalho é a 1), field (opcional) e message.

warningsarray

Linhas gravadas, mas não exatamente como escritas.

POST/api/v1/admin/import/categoriesAdmin

Importa categorias

Privilégio manage_categories. A importação é um upsert pelo slug: slug novo cria a categoria, slug existente atualiza. As colunas são lidas por posição, e o cabeçalho é descartado: mantenha a ordem do modelo.

Colunas, na ordem

idstring

Ignorada na importação. Pode ficar vazia.

namestringobrigatório

Nome da categoria.

parent_idstring

Categoria pai: um UUID, o slug de outra categoria ou - para mover para a raiz. O pai precisa existir antes da linha do filho: coloque os pais primeiro no arquivo.

slugstringobrigatório

Trecho da URL e chave do upsert.

descriptionstring

Descrição.

statusstring

AHD

Status da categoria.

positioninteger

Ordem de exibição.

meta_titlestring

Título de SEO.

meta_keywordsstring

Palavras-chave de SEO.

POST/api/v1/admin/import/featuresAdmin

Importa características

Privilégio manage_features. Característica (feature) é um atributo de produto, como Cor ou Voltagem. As colunas são lidas pelo nome do cabeçalho.

Campos do formulário

filefileobrigatório

A planilha.

update_existingbooleanpadrão: true

Quando false, características que já existem não são alteradas.

skip_errorsbooleanpadrão: true

Quando false, a importação para na primeira linha com erro.

Colunas

namestringobrigatório

Nome da característica.

feature_typestringobrigatório

textnumberselectmulti_selectdateboolgroupbrandauthorcolor

Tipo. Outro valor recusa a linha.

group_namestring

Grupo de características; criado se não existir.

descriptionstring

Descrição.

statusstring

AHD

Status.

positioninteger

Ordem.

variantsstring

Valores possíveis, separados por |. Só tem efeito nos tipos de lista (select, multi_select, brand, author, color).

categoriesstring

Categorias onde a característica se aplica.

POST/api/v1/admin/import/brandsAdmin

Importa marcas

Privilégio manage_features. Marca é um valor de uma característica do tipo marca. Colunas do modelo: brand_id, feature_id, name, code, description, position, image_url, slug_url, page_title, meta_description, meta_keywords.

Campos do formulário

filefileobrigatório

A planilha. A coluna name é obrigatória.

update_existingbooleanpadrão: true

Quando false, marcas que já existem não são alteradas.

skip_errorsbooleanpadrão: true

Quando false, a importação para na primeira linha com erro.

A coluna feature_id aponta a característica do tipo marca. Se ela não existir, ou se a característica indicada não for do tipo marca, a linha é recusada com uma mensagem no campo feature_id.

POST/api/v1/admin/import/usersAdmin

Importa usuários

Privilégio manage_users. Cria usuários, não atualiza: um e-mail que já existe é pulado em silêncio (conta em skipped, sem mensagem). Os usuários criados ficam sem senha utilizável e com e-mail não verificado: eles entram pelo fluxo "esqueci a senha".

Campos do formulário

filefileobrigatório

A planilha.

skip_errorsbooleanpadrão: true

Quando false, a importação para na primeira linha com erro de gravação.

Colunas

emailstringobrigatório

E-mail, com formato válido e até 255 caracteres.

first_namestring

Nome (também vale firstname).

last_namestring

Sobrenome (também vale lastname).

user_typestringpadrão: customer

customervendoradminroot_admin

Tipo de usuário. As letras c, v e a também valem.

statusstringpadrão: active

activedisabledunapproved

Status. As letras A, D e U também valem.

cpfstring

CPF, só dígitos ou com máscara.

cnpjstring

CNPJ.

person_typestring

FJ

Pessoa física ou jurídica.

legal_namestring

Razão social (pessoa jurídica).

trade_namestring

Nome fantasia.

state_regstring

Inscrição estadual.

responsible_namestring

Nome do responsável (pessoa jurídica).

POST/api/v1/admin/import/qty-discountsAdmin

Importa preços por quantidade (assíncrono)

Privilégio manage_catalog. Preço por quantidade é a faixa de preço que vale a partir de um número de unidades. Esta importação sempre roda em segundo plano: um arquivo válido recebe 202 e um job_id, e você acompanha em Jobs de importação. Problemas de estrutura (arquivo vazio, falta de colunas) falham logo, com 400.

Campos do formulário

filefileobrigatório

A planilha.

modestringpadrão: merge

mergereplace

Também pode ir na query string. merge atualiza cada faixa pela chave produto + quantidade mínima + grupo de usuários e mantém as demais faixas do produto. replace troca todas as faixas de cada produto listado pelas do arquivo.

Colunas (aceitam nomes em português e em inglês)

Product codestringobrigatório

SKU, código de barras ou EAN do produto. Também vale product_code, sku.

Lower limitintegerobrigatório

Quantidade mínima da faixa (inteiro, 1 ou mais).

Pricestring

Preço unitário da faixa em reais (39,90 ou 39.00).

Percentage discountstring

Desconto percentual. A linha precisa ter preço ou desconto (pode ter os dois; vale o desconto quando maior que zero).

User groupstring

Grupo de usuários a que a faixa se aplica (nome ou id). Vazio vale para todos.

Value per Kgstring

Preço de referência por quilo, só para exibição. 0 ou vazio guarda "não definido".

Value per Unitstring

Preço de referência por unidade, só para exibição.

Exemplo de requisição

bash

# categorias
curl "$BASE_URL/api/v1/admin/import/categories" \
  -H "Authorization: Bearer $TOKEN" -F "file=@categorias.csv"

# usuários, parando no primeiro erro
curl "$BASE_URL/api/v1/admin/import/users" \
  -H "Authorization: Bearer $TOKEN" -F "file=@clientes.csv" -F "skip_errors=false"

# preços por quantidade, substituindo as faixas
curl "$BASE_URL/api/v1/admin/import/qty-discounts?mode=replace" \
  -H "Authorization: Bearer $TOKEN" -F "file=@faixas.csv"

Resposta

202Preços por quantidade: job criado

json

{
  "job_id": "3f2b8c0e-7d41-4a5e-9a0c-1b6f2d9e4a77",
  "status": "processing",
  "status_url": "/admin/import/jobs/3f2b8c0e-7d41-4a5e-9a0c-1b6f2d9e4a77",
  "total_rows": 48
}

status_url vem sem o prefixo /api/v1; use /api/v1 + status_url.

Erros

Status	Quando	Corpo de exemplo
400	Campo `file` ausente	`{"error":"missing file field in form","detail":"http: no such file"}`
400	Arquivo vazio	`{"error":"csv_empty","detail":"uploaded file is empty"}`
400	Falta uma coluna obrigatória (características: `name`, `feature_type`)	`{"error":"missing_required_column","detail":"missing required column: feature_type"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta o privilégio da rota	`{"error":"insufficient privileges","required":"manage_features"}`
415	Extensão não aceita	`{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}`
500	Falha ao importar	`{"error":"import categories failed","detail":"..."}`

Erros por linha (slug is required, invalid feature type "x", invalid user_type, product not found: "SKU-9"...) vêm dentro do resumo ou do job, não como status HTTP.

Veja também

Importar outros cadastros

Importa categorias, características, marcas, usuários e preços por quantidade a partir de planilha, com o resumo de criados, atualizados e erros.

O resumo tem este formato, e os campos errors e warnings estão sempre presentes (vazios quando não há problema):

200Resumo de importação

json

{
  "total": 3,
  "created": 2,
  "imported": 2,
  "updated": 1,
  "skipped": 0,
  "errors": [],
  "warnings": []
}

Campos do resumo

totalinteger

Linhas de dados lidas.

createdinteger

Registros criados. imported repete o mesmo valor (nome antigo).

updatedinteger

Registros atualizados.

skippedinteger

Linhas puladas, por erro ou por já existirem (usuários).

errorsarray

Problemas por linha: row (a linha da planilha, o cabeçalho é a 1), field (opcional) e message.

warningsarray

Linhas gravadas, mas não exatamente como escritas.

POST/api/v1/admin/import/categoriesAdmin

Importa categorias

Colunas, na ordem

idstring

Ignorada na importação. Pode ficar vazia.

namestringobrigatório

Nome da categoria.

parent_idstring

Categoria pai: um UUID, o slug de outra categoria ou - para mover para a raiz. O pai precisa existir antes da linha do filho: coloque os pais primeiro no arquivo.

slugstringobrigatório

Trecho da URL e chave do upsert.

descriptionstring

Descrição.

statusstring

AHD

Status da categoria.

positioninteger

Ordem de exibição.

meta_titlestring

Título de SEO.

meta_keywordsstring

Palavras-chave de SEO.

POST/api/v1/admin/import/featuresAdmin

Importa características

Privilégio manage_features. Característica (feature) é um atributo de produto, como Cor ou Voltagem. As colunas são lidas pelo nome do cabeçalho.

Campos do formulário

filefileobrigatório

A planilha.

update_existingbooleanpadrão: true

Quando false, características que já existem não são alteradas.

skip_errorsbooleanpadrão: true

Quando false, a importação para na primeira linha com erro.

Colunas

namestringobrigatório

Nome da característica.

feature_typestringobrigatório

textnumberselectmulti_selectdateboolgroupbrandauthorcolor

Tipo. Outro valor recusa a linha.

group_namestring

Grupo de características; criado se não existir.

descriptionstring

Descrição.

statusstring

AHD

Status.

positioninteger

Ordem.

variantsstring

Valores possíveis, separados por |. Só tem efeito nos tipos de lista (select, multi_select, brand, author, color).

categoriesstring

Categorias onde a característica se aplica.

POST/api/v1/admin/import/brandsAdmin

Importa marcas

Campos do formulário

filefileobrigatório

A planilha. A coluna name é obrigatória.

update_existingbooleanpadrão: true

Quando false, marcas que já existem não são alteradas.

skip_errorsbooleanpadrão: true

Quando false, a importação para na primeira linha com erro.

A coluna feature_id aponta a característica do tipo marca. Se ela não existir, ou se a característica indicada não for do tipo marca, a linha é recusada com uma mensagem no campo feature_id.

POST/api/v1/admin/import/usersAdmin

Importa usuários

Campos do formulário

filefileobrigatório

A planilha.

skip_errorsbooleanpadrão: true

Quando false, a importação para na primeira linha com erro de gravação.

Colunas

emailstringobrigatório

E-mail, com formato válido e até 255 caracteres.

first_namestring

Nome (também vale firstname).

last_namestring

Sobrenome (também vale lastname).

user_typestringpadrão: customer

customervendoradminroot_admin

Tipo de usuário. As letras c, v e a também valem.

statusstringpadrão: active

activedisabledunapproved

Status. As letras A, D e U também valem.

cpfstring

CPF, só dígitos ou com máscara.

cnpjstring

CNPJ.

person_typestring

FJ

Pessoa física ou jurídica.

legal_namestring

Razão social (pessoa jurídica).

trade_namestring

Nome fantasia.

state_regstring

Inscrição estadual.

responsible_namestring

Nome do responsável (pessoa jurídica).

POST/api/v1/admin/import/qty-discountsAdmin

Importa preços por quantidade (assíncrono)

Campos do formulário

filefileobrigatório

A planilha.

modestringpadrão: merge

mergereplace

Colunas (aceitam nomes em português e em inglês)

Product codestringobrigatório

SKU, código de barras ou EAN do produto. Também vale product_code, sku.

Lower limitintegerobrigatório

Quantidade mínima da faixa (inteiro, 1 ou mais).

Pricestring

Preço unitário da faixa em reais (39,90 ou 39.00).

Percentage discountstring

Desconto percentual. A linha precisa ter preço ou desconto (pode ter os dois; vale o desconto quando maior que zero).

User groupstring

Grupo de usuários a que a faixa se aplica (nome ou id). Vazio vale para todos.

Value per Kgstring

Preço de referência por quilo, só para exibição. 0 ou vazio guarda "não definido".

Value per Unitstring

Preço de referência por unidade, só para exibição.

Exemplo de requisição

bash

# categorias
curl "$BASE_URL/api/v1/admin/import/categories" \
  -H "Authorization: Bearer $TOKEN" -F "file=@categorias.csv"

# usuários, parando no primeiro erro
curl "$BASE_URL/api/v1/admin/import/users" \
  -H "Authorization: Bearer $TOKEN" -F "file=@clientes.csv" -F "skip_errors=false"

# preços por quantidade, substituindo as faixas
curl "$BASE_URL/api/v1/admin/import/qty-discounts?mode=replace" \
  -H "Authorization: Bearer $TOKEN" -F "file=@faixas.csv"

Resposta

202Preços por quantidade: job criado

json

{
  "job_id": "3f2b8c0e-7d41-4a5e-9a0c-1b6f2d9e4a77",
  "status": "processing",
  "status_url": "/admin/import/jobs/3f2b8c0e-7d41-4a5e-9a0c-1b6f2d9e4a77",
  "total_rows": 48
}

status_url vem sem o prefixo /api/v1; use /api/v1 + status_url.

Erros

Status	Quando	Corpo de exemplo
400	Campo `file` ausente	`{"error":"missing file field in form","detail":"http: no such file"}`
400	Arquivo vazio	`{"error":"csv_empty","detail":"uploaded file is empty"}`
400	Falta uma coluna obrigatória (características: `name`, `feature_type`)	`{"error":"missing_required_column","detail":"missing required column: feature_type"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta o privilégio da rota	`{"error":"insufficient privileges","required":"manage_features"}`
415	Extensão não aceita	`{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}`
500	Falha ao importar	`{"error":"import categories failed","detail":"..."}`

Erros por linha (slug is required, invalid feature type "x", invalid user_type, product not found: "SKU-9"...) vêm dentro do resumo ou do job, não como status HTTP.