Categorias
Criação, atualização, listagem paginada, consulta por ID, movimentação na árvore e exclusão de categorias — com suporte a page, limit (até 200), store_id e metadados opcionais via include_pagination.
Visão geral
As rotas de categoria cobrem o ciclo completo: criar uma nova categoria na árvore, atualizar metadados, listar com paginação determinística, consultar por ID, mover dentro da hierarquia e excluir.
limit.limit é omitido ou inválido.total, last_page, has_next sob include_pagination=1.Criar nova categoria.
{
"parent_id": 2,
"name": "Especialidades",
"position": 5,
"is_active": 1,
"is_anchor": 1,
"include_in_menu": 1,
"description": "Categoria de especialidades odontológicas",
"display_mode": "PRODUCTS",
"url_key": "especialidades"
}Atualizar categoria existente.
{
"name": "Especialidades",
"categoria": {
"name": "Novo nome",
"description": "Nova descrição",
"is_anchor": 1
}
}Listar categorias com paginação determinística ou consultar uma categoria específica por id.
GET /api2/category
GET /api2/category?page=2
GET /api2/category?limit=50
GET /api2/category?include_pagination=1
GET /api2/category?store_id=1
GET /api2/category?id=61Mover categoria na árvore.
{
"name": "Especialidades",
"parent_name": "Produtos",
"after_id": null
}Excluir categoria.
{
"category_id": 546
}Novidades do GET /api2/category
O endpoint de listagem de categorias foi evoluído para oferecer paginação determinística, controle de tamanho de página, contexto multi-store explícito e metadados opcionais de paginação — alinhando o comportamento ao já adotado em GET /api2/products.
1) Listagem paginada Novo
Agora é possível percorrer todas as categorias com paginação previsível. Sem page, a rota devolve a primeira página; com page=N, devolve a página solicitada.
1.Exemplo
GET /api2/category?page=22) Suporte a limit opcional Novo
O endpoint aceita limit para definir a quantidade de registros por página. Valores inválidos (não numéricos, arrays, negativos, zero ou acima do máximo) são normalizados para o padrão, garantindo que nenhuma requisição quebre por entrada inesperada.
| Regra | Valor | Comportamento |
|---|---|---|
| Padrão | 20 | Aplicado quando limit é omitido. |
| Máximo | 200 | Teto rígido para proteger a rota em cenários de alta carga. |
| Inválido | — | Valores inválidos são normalizados para 20. |
Exemplos
GET /api2/category?limit=50
GET /api2/category?page=1&limit=2003) Suporte a store_id opcional Novo
Informe store_id para tornar o resultado explícito e determinístico em cenários multi-store. Sem o parâmetro, a seleção de store segue a regra default do ambiente; com ele, a integração assume o controle.
Exemplo
GET /api2/category?store_id=14) Metadados opcionais de paginação Novo
Foi adicionado suporte opcional a campos de paginação no corpo da resposta. Eles só são retornados quando for enviado include_pagination=1, evitando overhead em sincronizações que não precisam desses metadados.
1 habilita). Quando ativa, inclui na resposta os campos total, last_page e has_next.include_pagination=1).limit corrente.Exemplo
GET /api2/category?include_pagination=15) Consulta individual por id
Mantida e compatível: informe id para receber uma única categoria. Quando id é enviado, parâmetros de paginação são ignorados.
Exemplo
GET /api2/category?id=61Formas de uso suportadas
Referência rápida das combinações testadas e homologadas para o GET /api2/category.
GET /api2/category
GET /api2/category?page=2
GET /api2/category?limit=50
GET /api2/category?include_pagination=1
GET /api2/category?store_id=1
GET /api2/category?id=61
Recomendações para integração
Boas práticas para sincronização de árvore de categorias. Seguir essas diretrizes reduz retrabalho, evita paginação infinita e garante determinismo em ambientes multi-store.
Recomendado
- Enviar sempre
pageexplicitamente em rotinas de paginação. - Usar
store_idsempre que a integração precisar de resultado determinístico em ambiente multi-store. - Preferir
limit=50oulimit=100para sincronizações usuais. - Usar
limit=200apenas quando houver necessidade real de reduzir o número de chamadas. - Usar
include_pagination=1para controlar avanço de paginação com mais segurança (loop baseado emhas_next).
Evitar
- Enviar parâmetros como array em campos escalares — por exemplo
id[]oulimit[]. - Depender de ordenação implícita entre páginas em cenários multi-store sem
store_id. - Combinar
idcompage/limit: ao consultar por ID, parâmetros de paginação são ignorados.
Dica de sincronização
Para sincronizações periódicas da árvore, combine store_id + limit=100 + include_pagination=1. Você obtém determinismo, throughput equilibrado e um critério de parada confiável (has_next=false).