Anúncios · Categorias

Todo anúncio nasce em uma categoria folha — o último nível da árvore. É a categoria que define quais 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

GET/api/categories/departaments

Retorna os departamentos ativos, ordenados por nome:

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

Navegar nível a nível

GET/api/categories/browse

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

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

{
  "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

GET/api/categories/search

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

{
  "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:

GET/api/categories/{id}/attributes

Os atributos retornados — obrigatórios, de variação, combináveis — estão explicados no guia de Atributos e variações.