--- title: Categorias e Atributos --- # Guia de Categorias e Atributos ## 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. ## Escopos necessários Para utilizar as APIs de Categorias e Atributos, sua aplicação deve possuir os seguintes escopos: | Escopo | Descrição | |--------|-----------| | `open:portfolio-categories-seller:read` | Permite a leitura de categorias no contexto do seller | | `open:portfolio-categories-channel:read` | Permite a leitura de categorias por canal de vendas | :::info Como solicitar escopos Se sua aplicação ainda não possui esses escopos, consulte a documentação sobre [Como Criar e Configurar um Cliente](/docs/first-steps/create-an-application/create-application) para entender como adicioná-los à sua aplicação. Para clientes existentes, utilize o comando `./idm client add-scope` conforme descrito na documentação. ::: ## 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: ```bash # 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:** ```json { "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`: ```bash 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: ```bash curl --location 'https://api.magalu.com/seller/v1/portfolios/category?name=Kit' \ --header 'Authorization: Bearer SEU_TOKEN_AQUI' ``` **Resposta de exemplo:** ```json [ { "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: ```bash 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:** ```json { "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). ```bash 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:** ```json { "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`: ```bash 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: ```bash curl --location 'https://api.magalu.com/seller/v1/portfolios/category/{category_id}/datasheet' \ --header 'Authorization: Bearer SEU_TOKEN_AQUI' ``` **Exemplo de resposta:** ```json { "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": ```bash 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: ```json [ { "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: ```bash 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: ```json { "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: ```bash 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: ```json { "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):** ```json "attributes": [ {"name": "Cor", "value": "Preto"}, {"name": "Tamanho", "value": "42"} ] ``` **Campos de ficha técnica (datasheet):** ```json "datasheet": [ {"name": "Modelo", "value": "BRE15"}, {"name": "Prazo de Garantia", "value": "3 meses"} ] ``` **Campos do grupo:** ```json "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: ```bash # 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)](../products/ref/portfolios-v-1-patch-skus.api.mdx) ### 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)](../products/ref/portfolios-v-1-patch-skus.api.mdx) 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)](../products/ref/portfolios-v-1-patch-skus.api.mdx) ---