Categorias

Gerencie a árvore de categorias da loja. Categorias suportam hierarquia (pai → filhos).

Listar categorias

GET /api/v1/categories

Query parameters

Parâmetro	Tipo	Descrição
search	string	Busca por nome
parent_id	integer	Filtrar por categoria pai
tree	boolean	true para retornar hierarquia completa (apenas raízes com filhos aninhados)
sort	string	Campo de ordenação (padrão: order)
direction	string	asc ou desc (padrão: asc)
per_page	integer	Itens por página (máx: 100, padrão: 25)

Exemplo — lista plana

curl -X GET "https://sualoja.com.br/api/v1/categories" \
  -H "X-API-Key: SUA_CHAVE"

Exemplo — árvore hierárquica

curl -X GET "https://sualoja.com.br/api/v1/categories?tree=true" \
  -H "X-API-Key: SUA_CHAVE"

Resposta

{
  "data": [
    {
      "id": 1,
      "parent_id": null,
      "name": "Roupas",
      "slug": "roupas",
      "description": "Roupas masculinas e femininas",
      "order": 1,
      "show_on_home": true,
      "icon": "https://sualoja.com.br/storage/.../icon.webp",
      "children_count": 3,
      "products_count": 45,
      "children": [
        {
          "id": 2,
          "parent_id": 1,
          "name": "Camisetas",
          "slug": "camisetas",
          "children_count": 0,
          "products_count": 20
        }
      ],
      "seo": {
        "title": "Roupas | Minha Loja",
        "description": "Encontre as melhores roupas...",
        "keywords": "roupas, moda"
      },
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-03-05T12:00:00Z"
    }
  ]
}

Buscar categoria

GET /api/v1/categories/{id}

Retorna a categoria com suas subcategorias carregadas.

Criar categoria

POST /api/v1/categories

Campos

Campo	Tipo	Obrigatório	Descrição
name	string	✅	Nome da categoria
parent_id	integer		ID da categoria pai (para subcategorias)
description	string		Descrição da categoria
order	integer		Ordem de exibição
show_on_home	boolean		Exibir na home
seo_title	string		Título para SEO
seo_description	string		Meta description
seo_keywords	string		Palavras-chave

Exemplo

curl -X POST https://sualoja.com.br/api/v1/categories \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calçados",
    "parent_id": null,
    "order": 3,
    "show_on_home": true
  }'

Atualizar categoria

PUT /api/v1/categories/{id}

Aceita os mesmos campos do POST, todos opcionais.

Excluir categoria

DELETE /api/v1/categories/{id}

Restrição

Não é possível excluir uma categoria que possui produtos vinculados. A API retorna 422:

{
  "message": "Não é possível excluir: 15 produto(s) vinculado(s)."
}

Mova os produtos para outra categoria antes de excluir.