Importação de produtos por planilha

POST /products/import

Importa produtos a partir de arquivo CSV

Descrição

Endpoint responsável por processar um arquivo CSV e importar produtos na loja 📄.

Atua em contexto administrativo, com escopo PRODUCT_WRITE. A requisição é multipart/form-data: arquivo CSV, política comercial (tradePolicyId) e modo de atualização (replaceData).

Fluxo recomendado

1. GET /products/import/example — obter o cabeçalho oficial (nomes das colunas da sua loja). 2. Montar o CSV: primeira linha = cabeçalho retornado; demais linhas = produtos. 3. POST /products/import — enviar o arquivo preenchido.

A estrutura das colunas e o significado de cada campo estão documentados em Exemplo de planilha (GET /products/import/example). Esta rota apenas recebe o arquivo já montado.

O lojista pode:

Incluir ou atualizar produtos em lote, conforme replaceData
Aplicar preços da política comercial indicada em tradePolicyId
Consultar o resultado por linha em data[] (id, error, storageMap, attributeMap, entre outros)

Atenção: HTTP 200 com status: true não significa que todas as linhas foram gravadas. Cada item pode trazer error preenchido e id nulo quando a linha falhou (marca inexistente, SKU duplicado, etc.).

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação

Não defina Content-Type manualmente: o cliente envia multipart/form-data com boundary automático.

Parâmetros do Corpo (multipart/form-data)

Parâmetro	Tipo	Obrigatório	Descrição
`file`	file	✅	CSV (`text/csv`, até 4 MB)
`tradePolicyId`	integer	✅	Política comercial usada na importação (preços de comparação/venda e vínculos)
`replaceData`	boolean	✅	`true` / `1`: atualiza registros existentes; `false` / `0`: ignora linhas cujo SKU já existe

Requisitos do arquivo CSV

Regra	Detalhe
Cabeçalho	Igual ao retorno de `GET /products/import/example` (mesmos nomes, ordem e acentuação)
Dados	Uma linha por produto (ou variação), alinhada às colunas do cabeçalho
Marca e categoria	`Brand code` e `Main category code` devem existir na loja antes da importação
Colunas dinâmicas	`Storage …` e `Attribute …` variam por loja — use somente as do seu `GET /products/import/example`

Cabeçalho divergente → 400 com UAPPI_STORE_IMPORT_FILE_REQUIRED_FIELDS (a mensagem lista as colunas faltantes).

Exemplo de Requisição

1curl --request POST \
2  --url https://sua-loja-uappi.com.br/api/v3/products/import \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --form 'file=@/caminho/para/produtos.csv' \
5  --form 'tradePolicyId=1' \
6  --form 'replaceData=1'
curl --request POST \
  --url https://sua-loja-uappi.com.br/api/v3/products/import \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --form 'file=@/caminho/para/produtos.csv' \
  --form 'tradePolicyId=1' \
  --form 'replaceData=1'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": [
4		{
5			"id": null,
6			"externalId": "IMP-DOC-EX-001",
7			"error": "The requested brand was not found.",
8			"name": "Produto exemplo importacao documentacao",
9			"active": true,
10			"uri": "produto-exemplo-importacao-doc",
11			"shortDescription": "",
12			"videoUrl": "",
13			"searchDescription": "",
14			"seoTitle": "",
15			"seoKeywords": "",
16			"seoCanonical": "",
17			"seoSocialTitle": "",
18			"seoTwitterImageUrl": "",
19			"seoGraphImageUrl": "",
20			"seoGoogleCategoryId": 0,
21			"seoIndexOnGoogle": false,
22			"seoGoogleCondition": "",
23			"seoGoogleAgeGroup": "",
24			"seoGoogleGender": "",
25			"parentProductExternalId": "",
26			"basePrice": 99.9,
27			"brandCode": "SUBSTITUA_CODIGO_MARCA",
28			"mainCategoryCode": "SUBSTITUA_CODIGO_CATEGORIA",
29			"comparisonPrice": 119.9,
30			"salePrice": 99.9,
31			"width": 10,
32			"height": 20,
33			"length": 30,
34			"weight": 0,
35			"additionalTime": 0,
36			"image1": "",
37			"image2": "",
38			"image3": "",
39			"image4": "",
40			"image5": "",
41			"mpn": "",
42			"ean": "",
43			"ncm": "",
44			"storageMap": {
45				"0001": 10,
46				"armazem-week": 5
47			},
48			"attributeMap": {
49				"Capacidade": "",
50				"Cor": "Azul",
51				"Cores": "",
52				"logia": "",
53				"Material": "",
54				"Paramêcia": "",
55				"Quantidade": "",
56				"Tamanho": "",
57				"teste": "",
58				"Teste": "",
59				"Tipo": "",
60				"Voltagem": "",
61				"zoan": ""
62			}
63		}
64	]
65}
{
	"status": true,
	"data": [
		{
			"id": null,
			"externalId": "IMP-DOC-EX-001",
			"error": "The requested brand was not found.",
			"name": "Produto exemplo importacao documentacao",
			"active": true,
			"uri": "produto-exemplo-importacao-doc",
			"shortDescription": "",
			"videoUrl": "",
			"searchDescription": "",
			"seoTitle": "",
			"seoKeywords": "",
			"seoCanonical": "",
			"seoSocialTitle": "",
			"seoTwitterImageUrl": "",
			"seoGraphImageUrl": "",
			"seoGoogleCategoryId": 0,
			"seoIndexOnGoogle": false,
			"seoGoogleCondition": "",
			"seoGoogleAgeGroup": "",
			"seoGoogleGender": "",
			"parentProductExternalId": "",
			"basePrice": 99.9,
			"brandCode": "SUBSTITUA_CODIGO_MARCA",
			"mainCategoryCode": "SUBSTITUA_CODIGO_CATEGORIA",
			"comparisonPrice": 119.9,
			"salePrice": 99.9,
			"width": 10,
			"height": 20,
			"length": 30,
			"weight": 0,
			"additionalTime": 0,
			"image1": "",
			"image2": "",
			"image3": "",
			"image4": "",
			"image5": "",
			"mpn": "",
			"ean": "",
			"ncm": "",
			"storageMap": {
				"0001": 10,
				"armazem-week": 5
			},
			"attributeMap": {
				"Capacidade": "",
				"Cor": "Azul",
				"Cores": "",
				"logia": "",
				"Material": "",
				"Paramêcia": "",
				"Quantidade": "",
				"Tamanho": "",
				"teste": "",
				"Teste": "",
				"Tipo": "",
				"Voltagem": "",
				"zoan": ""
			}
		}
	]
}

Cada objeto em data representa uma linha do CSV. Use externalId como referência ao SKU enviado na planilha.

Como interpretar cada linha

Campo	Sucesso	Falha na linha
`id`	Preenchido com o ID do produto	`null`
`error`	`null`	Mensagem em inglês (ex.: marca não encontrada)
`brandCode` / `mainCategoryCode`	Valores lidos do CSV	Idem
`storageMap`	Estoque por armazém (chave = sufixo de `Storage …` no cabeçalho)	Idem
`attributeMap`	Atributos por nome (chave = sufixo de `Attribute …` no cabeçalho)	Idem

Demais campos (name, uri, basePrice, salePrice, dimensões, SEO, imagens, mpn, ean, ncm, etc.) ecoam os valores processados da linha.

Exemplo — linha com erro de negócio

Arquivo com cabeçalho válido, mas Brand code inexistente na loja:

1{
2  "status": true,
3  "data": [
4    {
5      "id": null,
6      "externalId": "IMP-DOC-EX-001",
7      "error": "The requested brand was not found.",
8      "name": "Produto exemplo importacao documentacao",
9      "active": true,
10      "brandCode": "CODIGO_MARCA_INEXISTENTE",
11      "mainCategoryCode": "CODIGO_CATEGORIA",
12      "basePrice": 99.9,
13      "salePrice": 99.9,
14      "storageMap": { "0001": 10, "armazem-week": 5 },
15      "attributeMap": { "Cor": "Azul" }
16    }
17  ]
18}
{
  "status": true,
  "data": [
    {
      "id": null,
      "externalId": "IMP-DOC-EX-001",
      "error": "The requested brand was not found.",
      "name": "Produto exemplo importacao documentacao",
      "active": true,
      "brandCode": "CODIGO_MARCA_INEXISTENTE",
      "mainCategoryCode": "CODIGO_CATEGORIA",
      "basePrice": 99.9,
      "salePrice": 99.9,
      "storageMap": { "0001": 10, "armazem-week": 5 },
      "attributeMap": { "Cor": "Azul" }
    }
  ]
}

Com marca e categoria válidas, a mesma estrutura retorna error: null e id com o identificador do produto criado ou atualizado.

⚠️ Possíveis erros

Atenção: erros de arquivo ou requisição interrompem a importação inteira (400/401/403). Erros de negócio por linha aparecem em data[].error com HTTP 200.

errorCode	HTTP	Descrição
`UAPPI_STORE_IMPORT_FILE_HEADER_REQUIRED`	400	Cabeçalho do CSV ausente
`UAPPI_STORE_IMPORT_FILE_REQUIRED_FIELDS`	400	Colunas do cabeçalho não conferem com o modelo da loja
`UAPPI_STORE_IMPORT_FILE_LINE_LIMIT`	400	Excesso de linhas no arquivo
`UAPPI_CORE_INVALID_TRADE_POLICY_ID`	400	Os ids solicitados de política comercial não são permitidos.
`UAPPI_STORE_BRAND_NOT_FOUND`	404	A marca solicitada não foi encontrada
`UAPPI_STORE_CATEGORY_NOT_FOUND`	404	A categoria solicitada não foi encontrada
`UAPPI_STORE_PRODUCT_DUPLICATED_SKU`	400	O SKU solicitado já em uso por outro produto
`UAPPI_STORE_DUPLICATED_URL`	400	A Uri solicitada já em uso por outra entidade.
`UAPPI_STORE_STORAGE_NOT_FOUND`	404	O armazém solicitado não foi encontrado.
`UAPPI_STORE_IMPORT_ENTITY_SKIPPED`	400	A entidade solicitada foi ignorada porque já existe e não pode ser atualizada.

Exemplo de planilha para importação de produtos

GET /products/import/example

Retorna o cabeçalho CSV de referência para importação de produtos por planilha

Descrição

Endpoint responsável por retornar o cabeçalho oficial do CSV usado na importação de produtos 📄.

Atua em contexto administrativo, com escopo PRODUCT_WRITE. A resposta é texto plano (uma linha com nomes de colunas separados por vírgula), pronta para ser a primeira linha da planilha que será enviada em POST /products/import.

O cabeçalho reflete a configuração da loja autenticada: colunas de estoque (Storage …) e atributos (Attribute …) mudam conforme armazéns e atributos cadastrados. Sempre use o retorno desta rota na sua instância — não reutilize cabeçalho de outro ambiente.

Como usar o retorno

1. Salve a resposta como primeira linha de um arquivo .csv (ou copie para a planilha). 2. Inclua as linhas de produtos abaixo do cabeçalho, na mesma ordem de colunas. 3. Envie o arquivo em POST /products/import.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/import/example \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  -o product-example-header.csv
curl --request GET \
  --url {{MAIN_URL}}/products/import/example \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  -o product-example-header.csv

✅ Resposta de Sucesso

HTTP Status: 200 OK

Header de resposta	Valor
`Content-Type`	`application/octet-stream`
`Content-Disposition`	`attachment; filename="product-example.csv"`

O corpo não usa envelope JSON (status / data): é somente a linha de cabeçalho CSV.

Exemplo ilustrativo (ambiente de testes — o seu pode diferir):

1SKU,Parent product SKU,Name,Active,Base price,Brand code,Main category code,...
SKU,Parent product SKU,Name,Active,Base price,Brand code,Main category code,...

Descrição das colunas fixas

Identificação e cadastro

Coluna	Tipo	Descrição
SKU	string	Código único do produto ou da variação
Parent product SKU	string	SKU do produto pai (variação); vazio se produto simples
Name	string	Nome exibido no catálogo
Active	boolean	`true` ou `false`
Brand code	string	Código da marca já cadastrada
Main category code	string	Código da categoria principal já cadastrada

Preços

Coluna	Tipo	Descrição
Base price	decimal	Preço base
Comparison price	decimal	Preço de comparação na política da importação
Sale price	decimal	Preço de venda na política da importação

Dimensões e logística

Coluna	Tipo	Descrição
Width, Height, Length, Weight	decimal	Dimensões do produto
Additional time	integer	Tempo adicional de preparação/envio

Conteúdo e URL

Coluna	Tipo	Descrição
Uri	string	Slug/identificador de URL
Short description	string	Descrição curta
Video url	string (URL)	URL de vídeo
Search description	string	Texto para busca interna

SEO

Coluna	Tipo	Descrição
Seo title, Seo keywords, Seo canonical	string	Metadados SEO
Seo social title	string	Título para redes sociais
Seo twitter image url, Seo graph image url	string (URL)	Imagens para compartilhamento
Seo google category id	string	Categoria Google Merchant
Seo index on google	boolean	Permite indexação
Seo google condition, Seo google age group, Seo google gender	string	Atributos Google Merchant

Imagens e fiscal

Coluna	Tipo	Descrição
Image 1 … Image 5	string (URL)	URLs de imagens (até cinco)
MPN, EAN, NCM	string	Identificadores fiscais/comerciais

Colunas dinâmicas (por loja)

Presentes apenas se configuradas na loja. Os nomes devem coincidir exatamente com o retorno deste endpoint.

Padrão	Tipo	Descrição
`Storage {identificador}`	integer	Estoque no armazém (ex.: `Storage 0001`)
`Attribute {nome}`	string	Valor do atributo (ex.: `Attribute Cor`, `Attribute Paramêcia`)

Erro comum: trocar caractere no cabeçalho (ex.: Storage @0001 em vez de Storage 0001, ou Paramécia em vez de Paramêcia) → falha na importação com UAPPI_STORE_IMPORT_FILE_REQUIRED_FIELDS.

⚠️ Possíveis erros

errorCode	HTTP	Descrição
`UAPPI_STORE_IMPORT_MODEL_NOT_FOUND`	404	Modelo de importação `product` indisponível

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Importação de produtos por planilha

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo (multipart/form-data)

Requisitos do arquivo CSV

Exemplo de Requisição

✅ Resposta de Sucesso

Como interpretar cada linha

Exemplo — linha com erro de negócio

⚠️ Possíveis erros

Exemplo de planilha para importação de produtos

Descrição

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

✅ Resposta de Sucesso

Descrição das colunas fixas

Identificação e cadastro

Preços

Dimensões e logística

Conteúdo e URL

SEO

Imagens e fiscal

Colunas dinâmicas (por loja)

⚠️ Possíveis erros

Nesta página

Institucional