Categorias de Produtos

Visão Geral

As categorias são responsáveis por organizar os produtos dentro da loja, criando uma estrutura hierárquica que facilita a navegação do catálogo 🗂️.

Elas permitem agrupar produtos por tipo, finalidade ou segmento, como por exemplo:

Eletrônicos

Celulares
Notebooks

Casa e Decoração

Móveis
Iluminação

No contexto administrativo, o lojista pode criar, atualizar, organizar e remover categorias, garantindo que a estrutura do catálogo reflita corretamente a organização desejada.

As categorias também podem possuir diferentes configurações dependendo da política comercial, permitindo comportamentos específicos conforme a regra aplicada.

Entidades Envolvidas

Categoria (Category)

Produto (Product)

Filtros (Filters)

Política Comercial (Trade Policy)

Notas e Considerações

Categorias podem possuir estrutura hierárquica, formando árvores de categorias.
Cada categoria pode possuir categorias pai e categorias filhas.
A organização correta das categorias melhora a navegação e descoberta de produtos dentro da loja.
Algumas configurações podem variar conforme a política comercial utilizada ⚙️.

Busca de exemplo de planilha para categoria

GET /products/categories/import/example

Retorna um exemplo de planilha sobre categoria

Descrição

Endpoint responsável por retornar um exemplo de planilha de categorias para uso em importação 📄.

O arquivo disponibilizado contém o cabeçalho com todos os campos permitidos, incluindo campos obrigatórios e opcionais, servindo como referência oficial para o preenchimento correto.

Esse modelo pode ser utilizado como base para estruturar e validar os dados antes do envio, garantindo maior conformidade com as regras da importação ✅.

Ao utilizar essa planilha como padrão, você reduz erros de formatação e evita inconsistências no processamento.

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/categories/import/example \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
curl --request GET \
  --url {{MAIN_URL}}/products/categories/import/example \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

Content-Type: application/octet-stream

Content-Disposition: attachment; filename="category-example.csv"

O arquivo retornado contém o seguinte cabeçalho:

1Name,Code,Parent category code,Active,Direct access,Uri,Short description,Video url,Search description,Seo title,Seo keywords,Seo canonical,Seo social title,Seo twitter image url,Seo graph image url,Seo google category id,Seo index on google,Seo google condition,Seo google age group,Seo google gender
Name,Code,Parent category code,Active,Direct access,Uri,Short description,Video url,Search description,Seo title,Seo keywords,Seo canonical,Seo social title,Seo twitter image url,Seo graph image url,Seo google category id,Seo index on google,Seo google condition,Seo google age group,Seo google gender

Descrição das Colunas

Coluna	Tipo	Descrição
Name	string	Nome oficial da categoria exibido no site
Code	string	Código interno identificador da categoria
Parent category code	string	Código interno identificador da categoria pai
Active	boolean	Indica se a categoria está ativa e visível no sistema (true/false)
Uri	string	Identificador amigável para URL (ex: nike, adidas-originals)
Short description	string	Descrição curta da categoria para exibição em listagens e destaques
Video url	string (URL)	URL de vídeo promocional ou institucional da categoria
Search description	string	Descrição otimizada para mecanismos de busca
Seo title	string	Título otimizado para SEO (tag title)
Seo keywords	string	Palavras-chave relacionadas à categoria e seus produtos
Seo canonical	string (URL)	URL canônica da página da categoria para evitar conteúdo duplicado
Seo social title	string	Título utilizado no compartilhamento social (og:title)
Seo twitter image url	string	Imagem específica para compartilhamento no Twitter (twitter:image)
Seo graph image url	string (URL)	Imagem utilizada no compartilhamento social (og:image)
Seo google category id	string	ID da categoria do Google Merchant Center associada aos produtos da categoria
Seo index on google	boolean	Define se a página da categoria pode ser indexada por mecanismos de busca (meta robots index/noindex)
Seo google condition	string	Condição do produto para Google Merchant (new, used, refurbished)
Seo google age group	string	Faixa etária para Google Merchant (newborn, infant, toddler, kids, adult)
Seo google gender	string	Público-alvo por gênero para Google Merchant (male, female, unisex)

⚠️ Possíveis erros:

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_IMPORT_MODEL_NOT_FOUND",
6    "message": "The requested import model was not found."
7  }
8}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_IMPORT_MODEL_NOT_FOUND",
    "message": "The requested import model was not found."
  }
}

Importação de categorias por planilha

POST /products/categories/import

Importa categorias a partir de planilhas

Descrição

Endpoint responsável por permitir que o lojista importe categorias para sua loja por meio de planilhas 📄.

O lojista pode consultar previamente os campos válidos no contexto V3, garantindo que a estrutura esteja adequada ao novo padrão de importação.

Com base nisso, é possível adaptar e organizar a planilha corretamente, evitando inconsistências no processamento.

Para realizar a importação, basta informar a planilha, a política comercial e o parâmetro replaceData, que definirá o comportamento da atualização das categorias no sistema ⚙️.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	multipart/form-data	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

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

Parâmetro	Tipo	Obrigatório	Descrição
file	file	✅	Arquivo CSV com as categorias (máximo 4MB, mimetype: text/csv)
tradePolicyId	integer	✅	Identificador de política comercial
replaceData	boolean	✅	Se deve substituir dados existentes

Estrutura do Arquivo CSV

O arquivo CSV deve conter as seguintes colunas:

Coluna	Tipo	Descrição
Name	string	Nome oficial da categoria exibido no site
Code	string	Código interno identificador da categoria
Parent category code	string	Código interno identificador da categoria pai
Active	boolean	Indica se a categoria está ativa e visível no sistema (true/false)
Uri	string	Identificador amigável para URL (ex: nike, adidas-originals)
Short description	string	Descrição curta da categoria para exibição em listagens e destaques
Video url	string (URL)	URL de vídeo promocional ou institucional da categoria
Search description	string	Descrição otimizada para mecanismos de busca
Seo title	string	Título otimizado para SEO (tag title)
Seo keywords	string	Palavras-chave relacionadas à categoria e seus produtos
Seo canonical	string (URL)	URL canônica da página da categoria para evitar conteúdo duplicado
Seo social title	string	Título utilizado no compartilhamento social (og:title)
Seo twitter image url	string	Imagem específica para compartilhamento no Twitter (twitter:image)
Seo graph image url	string (URL)	Imagem utilizada no compartilhamento social (og:image)
Seo google category id	string	ID da categoria do Google Merchant Center associada aos produtos da categoria
Seo index on google	boolean	Define se a página da categoria pode ser indexada por mecanismos de busca (meta robots index/noindex)
Seo google condition	string	Condição do produto para Google Merchant (new, used, refurbished)
Seo google age group	string	Faixa etária para Google Merchant (newborn, infant, toddler, kids, adult)
Seo google gender	string	Público-alvo por gênero para Google Merchant (male, female, unisex)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/categories/import \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header 'Content-Type: multipart/form-data' \
5  --form 'file=@categories.csv' \
6  --form 'tradePolicyId=1' \
7  --form 'replaceData=false'
curl --request POST \
  --url {{MAIN_URL}}/products/categories/import \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@categories.csv' \
  --form 'tradePolicyId=1' \
  --form 'replaceData=false'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "maps": [
3    1,
4    2,
5    3
6  ],
7  "entities": [
8    {
9      "id": 1,
10      "externalId": "654321",
11      "error": null,
12      "name": "smartphone",
13      "active": true,
14      "uri": "smartphone",
15      "shortDescription": null,
16      "videoUrl": null,
17      "searchDescription": "Encontre Smartphones aqui na TechBrand por excelentes preços e condições. Loja especializada em equipamentos de alta tecnologia.",
18      "seoTitle": "Compre Smartphones Por Excelentes Preços | TechBrand",
19      "seoKeywords": null,
20      "seoCanonical": null,
21      "seoSocialTitle": "Compre Smartphones Por Excelentes Preços | TechBrand",
22      "seoTwitterImageUrl": null,
23      "seoGraphImageUrl": null,
24      "seoGoogleCategoryId": null,
25      "seoIndexOnGoogle": null,
26      "seoGoogleCondition": null,
27      "seoGoogleAgeGroup": null,
28      "seoGoogleGender": null,
29      "seoStructuredData": null,
30      "parentCategoryExternalId": "987654",
31      "directAccess": false
32    }
33  ]
34}
{
  "maps": [
    1,
    2,
    3
  ],
  "entities": [
    {
      "id": 1,
      "externalId": "654321",
      "error": null,
      "name": "smartphone",
      "active": true,
      "uri": "smartphone",
      "shortDescription": null,
      "videoUrl": null,
      "searchDescription": "Encontre Smartphones aqui na TechBrand por excelentes preços e condições. Loja especializada em equipamentos de alta tecnologia.",
      "seoTitle": "Compre Smartphones Por Excelentes Preços | TechBrand",
      "seoKeywords": null,
      "seoCanonical": null,
      "seoSocialTitle": "Compre Smartphones Por Excelentes Preços | TechBrand",
      "seoTwitterImageUrl": null,
      "seoGraphImageUrl": null,
      "seoGoogleCategoryId": null,
      "seoIndexOnGoogle": null,
      "seoGoogleCondition": null,
      "seoGoogleAgeGroup": null,
      "seoGoogleGender": null,
      "seoStructuredData": null,
      "parentCategoryExternalId": "987654",
      "directAccess": false
    }
  ]
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_IMPORT_FILE_HEADER_REQUIRED	400	The header file is required.
UAPPI_STORE_IMPORT_FILE_REQUIRED_FIELDS	400	O arquivo requisitado não os campos obrigatórios.
UAPPI_STORE_IMPORT_FILE_LINE_LIMIT	400	A quantidade de linha dos arquivos é maior que o permitido.
UAPPI_CORE_INVALID_TRADE_POLICY_ID	400	Os ids de políticas comerciais solicitados não são permitidos.
UAPPI_STORE_IMPORT_INVALID_PARENT_ENTITY	400	A entidade não pode ser importada porque a entidade pai é inválida.
UAPPI_STORE_IMPORT_ENTITY_SKIPPED	200	A entidade foi pulada porque já está cadastrada e não pode ser atualizada.
UAPPI_STORE_DUPLICATED_URL	400	A url requisitada já está em uso.
UAPPI_STORE_IMPORT_CODE_REQUIRED	400	.
UAPPI_STORE_INVALID_DESCRIPTION_ENTITY	400	A entidade solicitada para criar a descrição não foi encontrada.
UAPPI_STORE_ENTITY_MAIN_URL_ALREADY_EXISTS	409	A url principal requisitada para a entidade já está em uso.

| UAPPI_STORE_INVALID_ENTITY_URL | 400 | A entidade solicitada para vincular à url não foi encontrada. |

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

Categorias de Produtos

Visão Geral

Entidades Envolvidas

Notas e Considerações

Busca de exemplo de planilha para categoria

Descrição

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

✅ Resposta de Sucesso

Descrição das Colunas

⚠️ Possíveis erros:

Importação de categorias por planilha

Descrição

Parâmetros

Headers Obrigatórios

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

Estrutura do Arquivo CSV

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Nesta página

Institucional