Guia de Categorias e Atributos

BETA

Introdução

Antes de cadastrar seus produtos na plataforma, é fundamental entender como funcionam as categorias e seus atributos. Este documento explica como consultar a árvore de categorias e seus respectivos atributos, assim como estruturar seus produtos corretamente.

Por que entender categorias é importante?

Categorizar corretamente o produto garantirá que ele contenha as informações necessárias para garantir uma boa experiência de compra.

Cada produto na Plataforma Seller precisa estar associado a uma categoria específica. E cada categoria pode possuir:

• Atributos de variação (attributes): Características que diferenciam as variações de um produto, também conhecidos como seletores, como cor, tamanho, voltagem, etc.
• Atributos de ficha técnica (datasheet): Informações técnicas do produto que suportam a tomada de decisão do comprador, como modelo, linha, prazo de garantia, etc.
• Regras de obrigatoriedade: Alguns atributos são obrigatórios de acordo com a categoria, outros recomendados e outros opcionais.

Conhecer essas informações antes de cadastrar seus produtos evita erros e retrabalho.

IMPORTANTE! Estabeleça um fluxo periódico de atualização da árvore de categorias e atributos para garantir que os dados disponibilizados para o lojistas estejam atualizados. Nossos times estão trabalhando para garantir a melhor estrutura de cadastro de produto.

Conceitos Básicos

1 - O que é uma categoria?

Uma categoria é uma classificação hierárquica que organiza produtos similares. Por exemplo:

Eletrônicos (categoria raiz)
  └── Celulares (subcategoria)
      └── Smartphones (subcategoria de Celulares)

2 - O que são atributos?

Atributos são características que descrevem um produto. Existem dois tipos principais:

1. Atributos de Variação: Usados para criar diferentes versões do mesmo produto

   • Exemplo: Cor, Tamanho, Voltagem
   • Um tênis pode ter variações de cor (Preto, Branco) e tamanho (40, 41, 42)

2. Atributos de Ficha Técnica (Datasheet): Informações técnicas do produto

   • Exemplo: Material, Modelo, Linha, Prazo de garantia
   • Aparecem na página do produto para informar o cliente

2.1 - Classificação dos atributos

Cada atributo pode ter um dos seguintes classificações:

• required (obrigatório): Deve ser informado para a categoria em referência. Caso não seja, o produto será bloqueado ou a atualização será reprovada.
• recommended (recomendado) e optional (opcional): Não é obrigatório, mas ajuda a melhorar a qualidade do cadastro do produto.

Fluxo de Trabalho Recomendado

1. Identifique a categoria do seu produto

Antes de cadastrar um produto, você precisa saber em qual categoria ele se encaixa. Existem duas formas de fazer isso:

Opção A: Navegar pela hierarquia completa

Se você não tem certeza do nome exato ou quer explorar as categorias disponíveis, pode listar a hierarquia completa:

# Listar apenas categorias raiz (primeiro nível)
curl --location 'https://api.magalu.com/seller/v1/portfolios/category/hierarchy?root_only=true&_limit=50' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Resposta de exemplo:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 50,
      "count": 2
    },
    "links": {
      "self": "/seller/v1/portfolios/category/hierarchy?_offset=0&_limit=50",
      "next": null
    }
  },
  "results": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Eletrônicos",
      "path": "/eletronicos",
      "parent_id": null,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "a47ac10b-58cc-4372-a567-0e02b2c3d478",
      "name": "Moda",
      "path": "/moda",
      "parent_id": null,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Para explorar as subcategorias de "Eletrônicos", por exemplo, use o parent_id:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category/hierarchy?parent_id=f47ac10b-58cc-4372-a567-0e02b2c3d479' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

IMPORTANTE: para cadastrar produtos sempre utilize a categoria mais específica (último item de categoria retornado) da hierarquia. Apenas a categoria final do caminho possui os atributos e configurações de ficha técnica necessários. Categorias intermediárias (como "Eletrônicos" ou "Celulares") não devem ser usadas diretamente no cadastro de produtos.

Opção B: Buscar por nome da categoria

Se você já sabe o nome da categoria (por exemplo, "Kit"), pode buscá-la diretamente:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category?name=Kit' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Resposta de exemplo:

[
  {
    "id": "cdf35f80-0426-4769-88b8-24d4c8f9d788",
    "created_at": "2025-11-19T11:59:30.643000Z",
    "updated_at": null,
    "created_by": "system@dump-import.com",
    "updated_by": null,
    "name": "Kit DVR",
    "parent_id": "71e4b93f-a265-4399-af04-15dbb5304fdf",
    "path": "Casa e Jardim/Segurança Residencial/Kit DVR"
  },
  {
    "id": "4bdea4b9-0550-4f87-8919-a595203ae199",
    "created_at": "2025-11-19T11:58:29.097000Z",
    "updated_at": null,
    "created_by": "system@dump-import.com",
    "updated_by": null,
    "name": "Kit Perfuração",
    "parent_id": "38f0f38d-c3c2-42f4-9a8f-90a8fedfa5e7",
    "path": "Ferragens/Peças e Acessórios para Ferramentas/Kit Perfuração"
  },
  {
    "id": "cec66c91-d750-442b-b78b-99ed82c2383e",
    "created_at": "2025-11-19T12:01:30.521000Z",
    "updated_at": null,
    "created_by": "system@dump-import.com",
    "updated_by": null,
    "name": "Kit Dispenser",
    "parent_id": "ee52ca6a-29f1-4cb9-8508-f9899e09b88a",
    "path": "Comercial e Industrial/Limpeza e Organização Industrial/Kit Dispenser"
  }
]

Busca por Similaridade

Este endpoint utiliza um mecanismo de busca que retorna uma lista de categorias ordenadas por relevância. O sistema calcula um score de similaridade que indica o quão próximo o nome buscado está das categorias encontradas no banco de dados.

Como funciona:

• Categorias com nomes que correspondem exatamente à busca aparecem primeiro (score mais alto)
• Categorias com nomes parcialmente correspondentes aparecem em seguida
• Quanto maior o score, mais relevante é o resultado para sua busca

Exemplo: Ao buscar por "Kit", você pode obter:

1. "Kit" (score alto - correspondência quase exata)
2. "Kit DVR" (score médio - contém o termo)
3. "Kit de Peças e Acessórios para Cama Elástica e Trampolim" (score menor - termo presente mas não prioritário)

O que você precisa guardar:

• id: O identificador único da categoria (UUID)
• path: O caminho completo na hierarquia
• name: O nome da categoria

Opção C: Buscar por id da categoria

Se você já sabe o id da categoria específica que você procura, pode buscá-la diretamente:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category?id=b9f8988c-3287-4311-b1ac-bc2715d0194c' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Resposta de exemplo:

{
  "id": "b9f8988c-3287-4311-b1ac-bc2715d0194c",
  "created_at": "2025-11-19T11:58:09.189000Z",
  "updated_at": null,
  "created_by": "system@dump-import.com",
  "updated_by": null,
  "name": "Painel para Eletrodomésticos",
  "parent_id": "35629f1d-1dfd-45b7-9e6e-2b8804849a90",
  "path": "Casa e Jardim/Peças e Acessórios para Eletrodomésticos/Painel para Eletrodomésticos"
}

2. Consulte os atributos de variação da categoria

Depois de identificar a categoria, você precisa saber quais atributos de variação ela possui. Esses atributos serão usados para criar diferentes versões do produto (como cores e tamanhos).

curl --location 'https://api.magalu.com/seller/v1/portfolios/category{category_id}/attributes' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Substitua {category_id} pelo UUID da categoria que você encontrou no passo anterior.

Exemplo de resposta:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 50,
      "count": 2
    }
  },
  "results": [
    {
      "id": "b0b3c4c8-0f13-4808-aa61-da5e87927e3d",
      "name": "cor",
      "display_name": "Cor",
      "type": "choice",
      "required": "required",
      "variation": true,
      "choices": ["Preto", "Branco", "Azul"],
      "example": "Preto",
    },
    {
      "id": "c1c3d5d9-1f14-4909-bb62-eb6f88938f4e",
      "name": "tamanho",
      "display_name": "Tamanho",
      "type": "choice",
      "required": "required",
      "variation": true,
      "choices": ["38", "39", "40", "41", "42"],
      "example": "42",
    }
  ]
}

Campos importantes:

• name: Nome interno do atributo (use este no campo attributes do produto)
• display_name: Nome amigável para exibição
• type: Tipo do atributo (choice, text, number, etc.)
• required: Classificação dos atributos (required, recommended, optional)
• variation: Se true, este atributo é usado para criar variações
• choices: Opções disponíveis (quando type é choice)
• example: Exemplo de preenchimento

Dica: Se você quiser ver apenas os atributos obrigatórios, adicione o parâmetro required:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category/{category_id}/attributes?required=required' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

3. Consulte os atributos de ficha técnica (datasheet)

Os atributos de ficha técnica são as informações técnicas que aparecem na página do produto. Para consultá-los:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category/{category_id}/datasheet' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Exemplo de resposta:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 50,
      "count": 3
    }
  },
  "results": [
    {
      "id": "d2d4e6e0-2f25-5a1a-cc73-fc7g99049g5f",
      "name": "material",
      "display_name": "Material",
      "type": "text",
      "required": "required",
      "variation": false,
      "example": "Sintético",
    },
    {
      "id": "e3e5f7f1-3g36-6b2b-dd84-gd8h00150h6g",
      "name": "modelo",
      "display_name": "modelo",
      "type": "text",
      "required": "recommended",
      "variation": false,
      "example": "BRE15",
    },
    {
      "id": "f4f6g8g2-4h47-7c3c-ee95-he9i11261i7h",
      "name": "garantia",
      "display_name": "Garantia",
      "type": "text",
      "required": "optional",
      "variation": false,
      "example": "12 meses",
    }
  ]
}

Exemplo Prático: Cadastrando um Tênis

Vamos seguir um exemplo completo de como usar as informações de categorias e atributos para cadastrar um tênis corretamente.

Passo 1: Identificar a categoria

Primeiro, buscamos a categoria "Calçados Esportivos":

curl --location 'https://api.magalu.com/seller/v1/portfolios/category?name=Calçados%20Esportivos' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Com isso, a API retornará a seguinte resposta:

[
  {
    "id": "019e59f3-643e-470b-bd66-1e00820dfc5a",
    "created_at": "2025-11-19T12:02:40.728000Z",
    "updated_at": null,
    "created_by": "system@dump-import.com",
    "updated_by": null,
    "name": "Calçados Esportivos",
    "parent_id": "28aecc48-945f-4b77-9e4a-3822379ce81e",
    "path": "Vestuário e Acessórios/Calçados Esportivos"
  },
  {
    "id": "efbeaba0-a998-4d07-a0ca-5b30192dc2d6",
    "created_at": "2025-11-19T12:02:40.740000Z",
    "updated_at": null,
    "created_by": "system@dump-import.com",
    "updated_by": null,
    "name": "Kit de Calçados Esportivos",
    "parent_id": "019e59f3-643e-470b-bd66-1e00820dfc5a",
    "path": "Vestuário e Acessórios/Calçados Esportivos/Kit de Calçados Esportivos"
  },
  {
    "id": "6a3c915a-6e36-404c-a091-d5180808a23e",
    "created_at": "2025-11-19T12:02:37.501000Z",
    "updated_at": null,
    "created_by": "system@dump-import.com",
    "updated_by": null,
    "name": "Calçados",
    "parent_id": "28aecc48-945f-4b77-9e4a-3822379ce81e",
    "path": "Vestuário e Acessórios/Calçados"
  },
  {...}
]

Resultado: Com os resultados encontrados, deve-se escolher o valor que mais se assemelha a sua busca. Nesse exemplo, a categoria mais adequada é o primeiro resultado retornado, o Calçados Esportivos de ID 019e59f3-643e-470b-bd66-1e00820dfc5a

• ID da categoria: 019e59f3-643e-470b-bd66-1e00820dfc5a
• Path: /Vestuário e Acessórios/Calçados Esportivos

Passo 2: Consultar atributos de variação

Para consultar os atributos de variação dessa categoria, basta informar o ID obtido no exemplo anterior e usá-lo como parâmetro no endpoint abaixo:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category/019e59f3-643e-470b-bd66-1e00820dfc5a/attributes' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

E terá como resposta o seguinte retorno:

{
  "meta": {
    "page": {
      "limit": 50,
      "offset": 0,
      "count": 2,
      "max_limit": 100
    },
    "links": {
      "previous": "/seller/v1/portfolios/category/0925274e-5266-48f4-9364-87d419586d90/attributes?_offset=0&_limit=50",
      "self": "/seller/v1/portfolios/category/0925274e-5266-48f4-9364-87d419586d90/attributes?_offset=0&_limit=50",
      "next": null
    }
  },
  "results": [
    {
      "id": "dc82d24e-aca1-41ca-9a3f-312824cdb14b",
      "name": "Tamanho",
      "display_name": "Tamanho",
      "type": "text",
      "required": "required",
      "example": "P, M, G, 25mm, 90cm, 30x15cm, N1, 23x8x15cm, 36, 10\", 8/16\", Grande, A4, AAA, Único, 10oz",
      "choices": null,
      "required_is_default": false,
      "required_matching": false,
      "variation": true,
      "is_inherited": false,
      "position": 7
    },
    {
      "id": "d251a56e-b7ba-4651-9280-de3dcf85016e",
      "name": "Cor",
      "display_name": "Cor",
      "type": "text",
      "required": "required",
      "example": "Preto, Branco, Vermelho, Amarelo",
      "choices": [],
      "required_is_default": false,
      "required_matching": false,
      "variation": true,
      "is_inherited": false,
      "position": 9
    }
  ]
}

Atributos encontrados:

• Tamanho (obrigatório, tipo texto com valores de exemplo como P, M, G, 25mm, 90cm, 30x15cm, N1, 23x8x15cm, 36, 10\", 8/16\", Grande, A4, AAA, Único, 10oz)
• Cor (obrigatório, tipo texto com valores de exemplo como Preto, Branco, Vermelho, Amarelo)

Passo 3: Consultar atributos de ficha técnica

Para consultar os atributos de ficha técnica dessa categoria, deve-se repetir o mesmo processo dos atributos de variação. Ou seja, basta inserir o ID obtido no exemplo anterior e usá-lo como parâmetro no endpoint abaixo:

curl --location 'https://api.magalu.com/seller/v1/portfolios/category/0925274e-5266-48f4-9364-87d419586d90/datasheet' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Obtendo como resposta:

{
  "meta": {
    "page": {
      "limit": 50,
      "offset": 0,
      "count": 29,
      "max_limit": 100
    },
    "links": {
      "previous": "/seller/v1/portfolios/category/0925274e-5266-48f4-9364-87d419586d90/datasheet?_offset=0&_limit=50",
      "self": "/seller/v1/portfolios/category/0925274e-5266-48f4-9364-87d419586d90/datasheet?_offset=0&_limit=50",
      "next": null
    }
  },
  "results": [
    {
      "id": "accc775a-b944-44bf-9449-ae90513a2030",
      "name": "Modelo",
      "display_name": "Modelo",
      "type": "text",
      "required": "required",
      "example": "Insira um código único do fabricante que identifique o produto. Esse código pode ser alfanumérico e deve ser utilizado consistentemente em todos os documentos relacionados ao produto. Ex.: BRE15, CVU20GB, XPTO56",
      "choices": null,
      "required_is_default": true,
      "required_matching": false,
      "variation": false,
      "is_inherited": true,
      "position": 2
    },
    {
      "id": "b07865c3-ddd4-467f-bba5-a95295dbeeeb",
      "name": "Linha",
      "display_name": "Linha",
      "type": "text",
      "required": "recommended",
      "example": "Preencha esse campo caso o item faça parte de uma linha de produtos. Linha é um termo utilizado para definir um grupo de produtos relacionados. Ex.: Galaxy. É uma linha da marca Samsung.",
      "choices": null,
      "required_is_default": true,
      "required_matching": false,
      "variation": false,
      "is_inherited": true,
      "position": 3
    },
    {
      "id": "1c173448-9994-47ca-a59f-eded31ec863a",
      "name": "Prazo de Garantia",
      "display_name": "Prazo de Garantia",
      "type": "text",
      "required": "required",
      "example": "1 ano (3 meses de garantia legal e mais 9 meses de garantia especial concedida pelo fabricante).",
      "choices": null,
      "required_is_default": true,
      "required_matching": false,
      "variation": false,
      "is_inherited": true,
      "position": 9
    },
    {
      "id": "a8cec342-60b0-4d31-a879-1377531f6d8e",
      "name": "Material",
      "display_name": "Material",
      "type": "text",
      "required": "recommended",
      "example": "Aço, Algodão, Alumínio, Bambu, Cerâmica, Elastano, Ferro, Inox, MDF, Poliéster, PVC, Seda, Silicone",
      "choices": null,
      "required_is_default": true,
      "required_matching": false,
      "variation": false,
      "is_inherited": false,
      "position": 10
    }
  ]
}

Atributos de ficha encontrados:

• Modelo (obrigatório, tipo text)
• Linha (recomendado, tipo text)
• Prazo de Garantia (obrigatório, tipo text)
• Material (recomendado, tipo text)

Passo 4: Estruturar o produto com as informações

Agora que você conhece os atributos obrigatórios e recomendados, pode estruturar seus produtos corretamente.

Para um tênis com variações de cor e tamanho, você precisará:

1. Informar a categoria

   • category.id: '3015d136-e96b-49ee-acbd-65bde9bd98a4'

2. Criar um grupo de variação único

   • group.id: "tenis-corrida-modelo-x"

3. Cadastrar cada variação como um SKU separado

   • SKU 1: Tênis Preto, Tamanho 42
   • SKU 2: Tênis Branco, Tamanho 40
   • SKU 3: Tênis Azul, Tamanho 42
   • etc.

4. Preencher os campos obrigatórios de cada SKU:

   Campos de variação (attributes):

   "attributes": [
     {"name": "Cor", "value": "Preto"},
     {"name": "Tamanho", "value": "42"}
   ]

   Campos de ficha técnica (datasheet):

   "datasheet": [
     {"name": "Modelo", "value": "BRE15"},
     {"name": "Prazo de Garantia", "value": "3 meses"}
   ]

   Campos do grupo:

   "group": {
     "id": "tenis-corrida-modelo-x",
     "main_variation": true
   }

Tabela de Referência: Headers e Ambientes

Headers Obrigatórios

Header	Descrição	Exemplo
Authorization	Token de autenticação Bearer	Bearer SEU_TOKEN_AQUI

URLs por Ambiente

Ambiente	Base URL
Sandbox (Homologação)	https://api-sandbox.magalu.com
Produção	https://api.magalu.com

Boas Práticas

1. Sempre consulte as categorias e seus respectivos atributos antes de cadastrar produtos

   • Isso evita erros de validação e retrabalho

2. Respeite a classificação dos atributos (níveis de obrigatoriedade)

   • Atributos required devem sempre ser preenchidos
   • Atributos recommended melhoram a qualidade do cadastro
   • Atributos optional podem ser preenchidos quando relevantes

3. Use o tipo correto para cada atributo

   • Se o tipo é choice, use um dos valores da lista choices
   • Se o tipo é text, envie uma string

4. Planeje suas variações com antecedência

   • Defina o group.id antes de cadastrar os produtos
   • Garanta que cada combinação de atributos de variação seja única

5. Guarde os IDs das categorias que você usa frequentemente

   • Isso agiliza o processo de cadastro de novos produtos

Como funciona a paginação

Os endpoints que retornam listas de categorias utilizam paginação para dividir os resultados em páginas menores. A estrutura de resposta inclui:

• count: Total de elementos retornados na página atual
• offset: Posição inicial da página (começa em 0)
• limit: Quantidade máxima de elementos por página (padrão: 50)
• links: URLs prontas para navegar entre as páginas
  • self: URL da página atual
  • next: URL da próxima página (ou null se for a última)
  • previous: URL da página anterior (quando disponível)

Exemplo de navegação:

Para listar as categorias de 50 em 50:

# Primeira página (elementos 0-49)
curl --location 'https://api.magalu.com/seller/v1/portfolios/categoryhierarchy?_offset=0&_limit=50' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

# Segunda página (elementos 50-99)
curl --location 'https://api.magalu.com/seller/v1/portfolios/categoryhierarchy?_offset=50&_limit=50' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

# Terceira página (elementos 100-149)
curl --location 'https://api.magalu.com/seller/v1/portfolios/categoryhierarchy?_offset=100&_limit=50' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'

Dica: Você pode usar diretamente as URLs fornecidas no campo links.next para navegar automaticamente para a próxima página, sem precisar calcular o offset manualmente.

Perguntas Frequentes

Posso cadastrar produtos sem informar a categoria e os seus respectivos atributos?

As integradoras terão um período para adaptar sua integração. Nesse período será permitido cadastrar/editar produtos sem informar a categoria e os seus respectivos atributos.

Como sei se preciso preencher um atributo?

Verifique o campo required na resposta da API:

• required: Obrigatório (o cadastro falhará sem ele)
• recommended: Recomendado (melhora a qualidade, mas não é obrigatório)
• optional: Opcional (use se for relevante para seu produto)

O que ocorrerá no cadastro do produto caso preencha com uma categoria incorreta ou os atributos obrigatórios da categoria não sejam informados?

O produto será bloqueado. Para corrigí-lo e prosseguir com seu cadastro será necessário realizar atualização informando os dados corretos/obrigatórios. Use o endpoint de atualização parcial (PATCH)

Posso ignorar atributos recomendadose opcionais?

Sim, mas não é recomendado. Tais atributos melhoram a qualidade da informação do produto, ajudando o cliente na tomada de decisão, assim como evitando possíveis devoluções/cancelamentos:

Atributos recomendados melhoram:

• A qualidade da página do produto
• A experiência do cliente no ecommerce (busca, filtros, etc)
• A relevância do produto nos resultados de busca

O que fazer se a categoria do meu produto não existir?

Sugerimos analisar a hierarquia completa de categorias disponíveis. Caso não encontre, entre em contato com o suporte através do canal de atendimento. A equipe poderá:

• Sugerir uma categoria existente adequada
• Avaliar a criação de uma nova categoria, se necessário

Posso usar atributos personalizados?

Sim, tanto para atributo de variação como de ficha técnica você poderá usar os seus próprios atributos para informações adicionais, caso não existam no nosso sistema.

Como atualizar os atributos de um produto já cadastrado?

Use o endpoint de atualização parcial (PATCH) do SKU para modificar os atributos de um produto já cadastrado.

O que ocorrerá na edição de produto caso preencha com uma categoria incorreta ou os atributos obrigatórios da categoria não sejam informados?

A atualização do produto será reprovada, mantendo o produto com o dados e status que se encontrava. Para corrigi-lo e prosseguir com a edição será necessário realizar atualização informando os dados corretos/obrigatórios. Use o endpoint de atualização parcial (PATCH)

---