Categorias

As categorias organizam o catálogo da sua loja e ajudam os clientes a encontrar produtos com facilidade. Cada categoria pode ter uma imagem de capa e uma categoria pai, permitindo montar hierarquias com subcategorias.

Enquanto os endpoints públicos expõem a lista e a árvore de categorias para a vitrine, os endpoints administrativos permitem criar, editar e remover categorias do catálogo.

Headers obrigatórios

Todas as requisições (públicas ou administrativas) devem incluir o header X-Shop-Id (UUID) com o identificador da loja. Endpoints administrativos exigem também Authorization: Bearer {token}.

---

Estrutura de Dados Principal

Uma categoria contém as seguintes informações principais:

Campo	Tipo	Descrição
name	String	Nome da categoria (máx. 150 caracteres).
parentId	Number	ID da categoria pai (nulo para categorias raiz).
shopImageId	Number	ID da imagem de capa da categoria.
shopImage	Object	Dados da imagem vinculada (uri).
children	Array	Subcategorias (na árvore e no detalhe).

---

Endpoints Públicos

Estes endpoints são voltados para a vitrine da loja e não exigem autenticação de customer.

Listar Categorias (Lista Simples)

Retorna as categorias em formato simplificado (label/value), ideal para selects e filtros no frontend.

GET /v1/shop/customer/categories/public/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
limit	number	Não	Limite de itens retornados (máx. 300).
orderBy	enum	Não	Ordena por value ou label.
orderDirection	enum	Não	Direção da ordenação: asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/shop/customer/categories/public/list?orderBy=label&orderDirection=asc" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com as categorias em formato label/value.

[
  {
    "label": "Camisetas",
    "value": "1"
  },
  {
    "label": "Calçados",
    "value": "2"
  }
]

Obter Árvore de Categorias

Retorna a hierarquia completa de categorias, incluindo imagem e subcategorias aninhadas.

GET /v1/shop/customer/categories/public/tree

Parâmetros de Query

Aceita os mesmos parâmetros da listagem simples: search, limit, orderBy e orderDirection.

Exemplo de Requisição

fetch('https://api.us.basis.tavares.in/v1/shop/customer/categories/public/tree', {
  headers: {
    'X-Shop-Id': '3fa85f64-5717-4562-b3fc-2c963f66afa6'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas

200 OK

Retorna um array com as categorias raiz e suas subcategorias em children.

[
  {
    "id": "1",
    "shopImageId": "2",
    "parentId": null,
    "name": "Camisetas",
    "shopImage": {
      "id": "2",
      "uri": "https://cdn.exemplo.com/images/123e4567-e89b-42d3-a456-426614174000.jpg"
    },
    "children": [
      {
        "id": "3",
        "shopImageId": null,
        "parentId": "1",
        "name": "Camisetas Manga Longa",
        "shopImage": null,
        "children": []
      }
    ]
  }
]

---

Endpoints Administrativos

Endpoints protegidos para gerenciamento do catálogo. Requerem autenticação de usuário da loja (shopUser).

Listar Categorias

Lista todas as categorias da loja, com paginação e busca.

GET /v1/shop/user/categories

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100, padrão: 25).
search	string	Não	Busca por termo no nome.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/categories?page=1&perPage=25" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de categorias.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "1",
      "parentId": null,
      "shopImageId": null,
      "name": "Camisetas",
      "createdAt": "2026-06-17T15:12:20.765+00:00",
      "updatedAt": "2026-06-17T15:12:20.765+00:00",
      "shopImage": null,
      "parent": null
    },
    {
      "id": "3",
      "parentId": "1",
      "shopImageId": null,
      "name": "Camisetas Manga Longa",
      "createdAt": "2026-06-17T15:36:56.303+00:00",
      "updatedAt": "2026-06-17T15:36:56.303+00:00",
      "shopImage": null,
      "parent": {
        "id": "1",
        "shopImageId": null,
        "name": "Camisetas",
        "shopImage": null
      }
    }
  ]
}

Criar Nova Categoria

Cria uma nova categoria, opcionalmente vinculada a uma categoria pai e a uma imagem.

POST /v1/shop/user/categories

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da categoria (máx. 150 caracteres).
parentId	number	Não	ID da categoria pai (deve existir na loja).
shopImageId	number	Não	ID da imagem de capa (deve existir na loja).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/shop/user/categories" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "shopImageId": null,
    "parentId": null,
    "name": "Acessórios"
  }'

Respostas

201 Created

Retorna o ID da categoria criada.

{
  "id": "6"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "name"
    }
  ]
}

Obter Categoria por ID

Recupera os detalhes de uma categoria, incluindo a categoria pai e as subcategorias.

GET /v1/shop/user/categories/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da categoria.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/categories/1" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna a categoria com parent e children.

{
  "id": "1",
  "parentId": null,
  "shopImageId": null,
  "name": "Camisetas",
  "createdAt": "2026-06-17T15:12:20.765+00:00",
  "updatedAt": "2026-06-17T15:12:20.765+00:00",
  "shopImage": null,
  "parent": null,
  "children": [
    {
      "id": "3",
      "shopImageId": null,
      "name": "Camisetas Manga Longa",
      "parentId": "1",
      "shopImage": null
    }
  ]
}

404 Not Found

Ocorre quando a categoria não existe na loja.

Atualizar Categoria

Atualiza os dados de uma categoria existente.

PUT /v1/shop/user/categories/:id

Payload (Body)

Aceita os mesmos campos da criação: name, parentId e shopImageId.

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/shop/user/categories/3" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "shopImageId": null,
    "parentId": 1,
    "name": "Camisetas Manga Curta"
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Categoria

Exclui uma categoria da loja.

DELETE /v1/shop/user/categories/:id

Exemplo de Requisição

curl -X DELETE "https://api.us.basis.tavares.in/v1/shop/user/categories/6" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.