# Anúncios · Categorias

Todo anúncio nasce em uma **categoria folha** — o último nível da árvore. É a categoria que define quais [atributos](/guia/anuncios-atributos) o anúncio precisa (e pode) ter, então acertar a categoria é o primeiro passo de qualquer publicação.

---

## Como a árvore é organizada

Dois níveis de organização:

- **Departamento** — o agrupamento de topo (Eletrônicos, Casa, Moda...). Tem `id`, `name` e `icon_svg`.
- **Categoria** — uma árvore de profundidade variável dentro do departamento. Cada categoria tem `parent_id` (null nas raízes), `level` e um `hierarchy`: o breadcrumb completo até ela, pronto pra exibir.

Uma categoria é **folha** quando não tem filhos. Só folhas recebem anúncios — e os endpoints já cuidam disso pra você: a busca retorna apenas folhas, e a navegação indica `has_children: false` quando você chegou ao fim do caminho.

> **Exceção à convenção de IDs:** categoria e departamento usam **ID inteiro** (ex.: `121`), diferente do resto da API, que usa IDs de 26 caracteres.

---

## Listar departamentos

<a class="api-route" href="/reference/anuncios#tag/categorias/GET/api/categories/departaments"><span class="api-method api-method-get">GET</span><span class="api-path">/api/categories/departaments</span></a>

Retorna os departamentos ativos, ordenados por nome:

```jsonc
{
  "data": [
    { "id": 3, "name": "Eletrônicos", "icon_svg": "<svg …>" },
    { "id": 7, "name": "Informática", "icon_svg": "<svg …>" }
  ]
}
```

---

## Navegar nível a nível

<a class="api-route" href="/reference/anuncios#tag/categorias/GET/api/categories/browse"><span class="api-method api-method-get">GET</span><span class="api-path">/api/categories/browse</span></a>

Um nível por vez — ideal pra montar uma interface de navegação em cascata:

| Parâmetro | Para quê |
|-----------|----------|
| `departament_id` | Limita ao departamento. |
| `parent_id` | Filhos dessa categoria. Sem ele, retorna as raízes. |

Cada item vem com `has_children`. Quando vier `false`, você chegou numa **folha** — pode usar o `id` no anúncio.

```jsonc
{
  "data": [
    {
      "id": 121,
      "name": "Caixas de Som",
      "has_children": false,            // folha: pronta pra receber anúncio
      "departament": { "id": 3, "name": "Eletrônicos" },
      "parent": { "id": 45, "name": "Áudio" }
    }
  ]
}
```

---

## Buscar direto

<a class="api-route" href="/reference/anuncios#tag/categorias/GET/api/categories/search"><span class="api-method api-method-get">GET</span><span class="api-path">/api/categories/search</span></a>

O caminho rápido: busca por termo e retorna **apenas folhas**, já com o breadcrumb completo.

| Parâmetro | Para quê |
|-----------|----------|
| `search` | Termo de busca (obrigatório — vazio retorna 422). |
| `departament_id` | Restringe ao departamento. |

```jsonc
{
  "data": [
    {
      "id": 121,
      "name": "Caixas de Som",
      "departament": { "id": 3, "name": "Eletrônicos", "icon_svg": "<svg …>" },
      "parent": { "id": 45, "name": "Áudio", "hierarchy": [ /* breadcrumb do pai */ ] },
      "hierarchy": [                     // breadcrumb completo, pronto pra exibir
        { "id": 12, "name": "Áudio e Vídeo" },
        { "id": 45, "name": "Áudio" },
        { "id": 121, "name": "Caixas de Som" }
      ],
      "level": 3
    }
  ]
}
```

---

## Qual usar?

- **Integração de ERP/hub** que já sabe o que vende: use o `search` — uma chamada e você tem a folha com breadcrumb.
- **Interface de cadastro** com navegação guiada: `departaments` → `browse` em cascata até `has_children: false`.
- **Breadcrumb na sua UI**: o campo `hierarchy` já vem montado — não precisa de chamadas extras pra subir a árvore.

## Da categoria pros atributos

Com a folha em mãos, o próximo passo é consultar o que ela exige:

<a class="api-route" href="/reference/anuncios#tag/publicacao/GET/api/categories/{category_id}/attributes"><span class="api-method api-method-get">GET</span><span class="api-path">/api/categories/{id}/attributes</span></a>

Os atributos retornados — obrigatórios, de variação, combináveis — estão explicados no guia de [Atributos e variações](/guia/anuncios-atributos).