API de Categorias

Gerencie suas categorias de produtos com suporte para hierarquias aninhadas.

Endpoints

GET

/categories

categories:read

Obter uma lista plana de todas as categorias.

GET

/categories/tree

categories:read

Obter a arvore completa de categorias com subcategorias aninhadas.

GET

/categories/:id

categories:read

Obter uma categoria pelo ID.

POST

/categories

categories:write

Criar uma nova categoria. Defina parentId para criar uma subcategoria.

PUT

/categories/:id

categories:write

Atualizar uma categoria existente. Atualizacoes parciais sao suportadas.

DELETE

/categories/:id

categories:write

Exclusao suave de uma categoria. Os produtos desta categoria nao sao afetados.

Referencia de Campos

Campo	Tipo	Obrigatorio	Descricao
id	string	Nao	Identificador unico da categoria (somente leitura)
name	string	Sim	Nome da categoria
slug	string	Nao	Slug amigavel para URL (gerado automaticamente se omitido)
description	string	Nao	Descricao da categoria
parentId	string	Nao	ID da categoria pai para aninhamento
imageUrl	string	Nao	URL da imagem da categoria
sortOrder	integer	Nao	Ordem de exibicao (menor = primeiro)
isActive	boolean	Nao	Se a categoria esta ativa (padrao: true)
children	Category[]	Nao	Subcategorias aninhadas (apenas no endpoint de arvore)
createdAt	datetime	Nao	Timestamp ISO 8601 (somente leitura)
updatedAt	datetime	Nao	Timestamp ISO 8601 (somente leitura)

Exemplo

Obter arvore de categorias

bash

curl "https://api.mercozy.com/api/v1/external/categories/tree" \
  -H "X-API-Key: mk_live_xxxxx"

Criar uma categoria

bash

curl -X POST "https://api.mercozy.com/api/v1/external/categories" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electronics",
    "description": "Electronic devices and accessories",
    "sortOrder": 1,
    "isActive": true
  }'

Exemplo de Resposta (Arvore)

json

{
  "data": [
    {
      "id": "cat_abc123",
      "name": "Electronics",
      "slug": "electronics",
      "description": "Electronic devices and accessories",
      "parentId": null,
      "imageUrl": null,
      "sortOrder": 1,
      "isActive": true,
      "children": [
        {
          "id": "cat_def456",
          "name": "Smartphones",
          "slug": "smartphones",
          "description": "Mobile phones",
          "parentId": "cat_abc123",
          "imageUrl": null,
          "sortOrder": 1,
          "isActive": true,
          "children": []
        }
      ],
      "createdAt": "2025-12-15T10:30:00Z",
      "updatedAt": "2025-12-15T10:30:00Z"
    }
  ]
}