VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Guia rápido/Categorias

Listar categorias

Retorna as categorias da loja em lista plana, com paginação e filtros.

Use esta operação para ler o catálogo de categorias: carregar a árvore em um PIM, montar o menu de outro canal ou conferir se uma categoria já existe antes de criá-la. A lista não inclui categorias na lixeira (T), mas inclui as ativas, desativadas e ocultas.

A API devolve uma lista plana com paginação. Para montar a árvore, veja a dica no fim da página.

GET/api/v1.0/categoriesAdmin

Listar categorias

Autenticação: HTTP Basic com e-mail:chave_de_api, ou Authorization: Bearer <JWT>. A leitura aceita qualquer credencial válida da loja. Os ids saem como UUID. A ordem é a do cadastro; a API não tem parâmetro de ordenação.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1. Valor inválido é ignorado.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 250. Texto, zero ou valor acima de 250 são ignorados e valem 10.
parent_idstring
Somente as filhas diretas desta categoria (UUID). Use 0 para listar só as categorias de topo.
statusstring
Filtro por status. Não use: esta API trata toda categoria como A, então A devolve todas e H ou D não devolvem nenhuma.
category_ids[]string
Repetível. Restringe a lista a estes ids (UUID ou slug). Ex.: category_ids[]=escritorio&category_ids[]=informatica.
item_idsstring
Mesmo efeito de category_ids[], em uma lista separada por vírgulas.
GET/api/categoriesAdmin

Listar categorias (rota sem /v1.0)

A mesma operação sem o /v1.0. Aceita os mesmos parâmetros. A diferença está na resposta: category_id e parent_id saem como números decimais em string ("878363454"), e o id_path continua sendo a cadeia de UUIDs. Esses números não podem ser usados de volta no caminho de GET /api/categories/{id}.

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/categories?parent_id=0&items_per_page=50"

Resposta

200Categorias retornadas
json
{
  "categories": [
    {
      "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
      "category": "Escritório",
      "parent_id": "0",
      "id_path": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
      "status": "A",
      "position": 0,
      "product_count": 303,
      "company_id": "0",
      "description": "",
      "seo_name": "escritorio",
      "page_title": "",
      "meta_description": "",
      "meta_keywords": "",
      "timestamp": 1788959480,
      "updated_timestamp": 1788959480
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 15 }
}

Campos da resposta

categoriesarray
Categorias da página.
categories[].category_idstring
Id da categoria. UUID em /api/v1.0; decimal em string em /api/.
categories[].categorystring
Nome.
categories[].parent_idstring
Id da categoria-mãe, ou "0" nas categorias de topo.
categories[].id_pathstring
Cadeia de ids da raiz até a categoria, separados por /. Sempre em UUID, mesmo em /api/.
categories[].statusstring
A
Sempre A (limitação desta API, veja a home da seção).
categories[].positioninteger
Posição entre as irmãs.
categories[].product_countinteger
Quantidade de produtos contados na categoria, pelas regras de visibilidade da loja.
categories[].company_idstring
Sempre "0". A categoria pertence à loja, não a um seller.
categories[].descriptionstring
Descrição (pode conter HTML). Vazia quando não há.
categories[].seo_namestring
Slug da página.
categories[].page_titlestring
Título de SEO. Vazio quando não definido.
categories[].meta_descriptionstring
Descrição de SEO. Vazia quando não definida.
categories[].meta_keywordsstring
Palavras-chave de SEO. Vazio quando não definido.
categories[].timestampinteger
Criação, Unix timestamp em segundos (UTC).
categories[].updated_timestampinteger
Última alteração, Unix timestamp em segundos.
categories[].main_pairobject
Só aparece quando a categoria tem imagem: pair_id, image_id (o id da categoria) e detailed com image_path e https_image_path, ambos com o mesmo endereço da imagem.
paramsobject
Paginação: page, items_per_page e total_items (total depois dos filtros, em todas as páginas).

Erros

StatusQuandoCorpo
401Sem credenciais, chave inválida ou token expirado{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
429Limite de requisições (por exemplo, login repetido){"error":"rate limit exceeded","detail":"too many requests, please try again later"}
500Falha interna{"message":"...","status":500}
Como montar a árvore

Para obter a árvore, leia primeiro as categorias de topo com parent_id=0 e, para cada uma, chame de novo com parent_id={id}. Como alternativa, leia todas com items_per_page=250 e use parent_id e id_path para montar a árvore do seu lado.

Veja também

  • Consultar categoria
  • Criar categoria
  • Produtos da categoria
  • Alterar categoria
Anterior
Categorias
Próxima
Consultar categoria
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também