Listar produtos

Retorna os produtos da loja, do mais novo para o mais antigo, com busca, filtros, ordenação e paginação.

Use esta operação para varrer o catálogo: um ERP que compara o cadastro com o da loja, um marketplace que sincroniza preços, uma tela de busca ou um relatório. A lista traz o cadastro resumido de cada produto (nome, código, preço, estoque, status, categoria, imagens). Para um único produto, com todos os campos e idiomas, use Consultar produto.

A lista inclui todos os status e os produtos filhos de variação (is_variation: true), não só os ativos. Para a vitrine, filtre por status=A. Os produtos excluídos (na lixeira) nunca aparecem.

GET/api/v1/admin/productsAdmin

Lista os produtos

Autenticação: Authorization: Bearer <token> de um usuário administrador com o privilégio view_catalog ou manage_catalog. O token vem de POST /api/v1/auth/login (o login tem limite de requisições: guarde o token em vez de logar a cada chamada). A lista mostra as ofertas dos sellers e os produtos sem seller; os cadastros mestres ficam de fora.

Query parameters

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Valor fora desse intervalo volta ao padrão (20), não é limitado.

sort_bystringpadrão: created_at

created_atupdated_atpricenamequantitystatussales_countrating_avgpopularitycategory

Campo de ordenação. category ordena pelo nome da categoria principal. Outro valor cai em created_at. Empates são desfeitos pelo id, então a paginação é estável.

sort_dirstringpadrão: desc

ascdesc

Direção da ordenação.

searchstring

Busca por texto: todas as palavras precisam aparecer em algum campo de busca (nome, descrição, descrição curta, SKU, palavras-chave, código de barras, termos de busca). Sem diferenciar maiúsculas e acentos. Colar o UUID ou o display_id também encontra o produto. Se nada for encontrado, a plataforma amplia a busca por semelhança (erros de digitação e sinônimos); desligue com semantic=false.

search_fieldsstring

Restringe a busca a alguns campos, separados por vírgula. Valores: name, description, short_description, sku (ou product_code), meta_keywords, barcode, search_words. Nenhum campo válido: busca em todos. Útil em seletores de produto (por exemplo search_fields=name,sku).

semanticbooleanpadrão: true

Com false (ou 0) a busca é literal: não amplia por semelhança quando o resultado é vazio.

statusstring

ADHRXactivedisabledhiddenpendingrejected

Status do produto, pela letra ou pelo nome. Um valor desconhecido devolve lista vazia.

approval_statusstring

pendingapprovedrejected

Atalho antigo para o status de moderação (pending = R, rejected = X, approved = A). Só vale quando status não foi enviado.

category_iduuid

Somente produtos desta categoria (principal ou adicional), exato: não inclui as subcategorias. UUID malformado causa erro 500.

vendor_iduuid

Somente produtos deste seller. UUID malformado causa erro 500.

vendor_idsstring

Vários sellers, UUIDs separados por vírgula.

skustring

SKU. Contém o texto, sem diferenciar maiúsculas.

min_priceinteger

Preço mínimo em centavos. Texto não numérico é ignorado.

max_priceinteger

Preço máximo em centavos.

free_shippingboolean

true ou 1: somente produtos com frete grátis.

has_imagesboolean

true ou 1: somente com imagem. false: somente sem imagem.

low_stockboolean

true ou 1: produtos com controle de estoque, estoque maior que zero e menor ou igual ao low_stock_alert.

out_of_stockboolean

true ou 1: produtos com quantidade igual a zero.

min_quantityinteger

Estoque mínimo (inclusive).

max_quantityinteger

Estoque máximo (inclusive).

created_fromstring

Criados a partir desta data, YYYY-MM-DD. Data inválida causa erro 500.

created_tostring

Criados até esta data (o dia inteiro entra).

updated_fromstring

Alterados a partir desta data, YYYY-MM-DD.

updated_tostring

Alterados até esta data (o dia inteiro entra).

include_imagesbooleanpadrão: true

Com false a resposta não traz o vetor images, o que deixa a lista mais rápida.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products?status=A&search=caneca&min_price=2000&sort_by=price&sort_dir=asc&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos retornados

json

{
  "products": [
    {
      "id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
      "display_id": 10643,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "name": "Caneca Esmaltada 350 ml",
      "slug": "caneca-esmaltada-350-ml",
      "sku": "CAN-350-AZ",
      "description": "<p>Caneca esmaltada azul.</p>",
      "short_description": "",
      "price": 4990,
      "list_price": 5990,
      "cost_price": 2000,
      "track_inventory": true,
      "quantity": 12,
      "low_stock_alert": 0,
      "min_quantity": 0,
      "max_quantity": 0,
      "quantity_step": 1,
      "sale_unit": "un",
      "zero_price_action": "R",
      "popularity": 0,
      "out_of_stock_action": "S",
      "weight": 0.35,
      "width": 9,
      "height": 9,
      "length": 12,
      "status": "A",
      "intended_status": "A",
      "approval_status": "approved",
      "view_count": 0,
      "sales_count": 0,
      "rating_avg": 0,
      "rating_count": 0,
      "free_shipping": false,
      "shipping_freight": 0,
      "requires_shipping": true,
      "vendor_name": "Loja Seller Teste",
      "vendor_slug": "loja-seller-teste",
      "is_variation": false,
      "has_unified_variations": false,
      "created_at": "2026-10-11T20:51:07.858767Z",
      "updated_at": "2026-10-11T20:55:14.612402Z",
      "images": [
        {
          "id": "acd51513-0264-46c7-a667-504e3ec77e19",
          "image_url": "/uploads/caneca-azul.png",
          "alt_text": "",
          "position": 0,
          "is_primary": true
        }
      ],
      "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
      "product": "Caneca Esmaltada 350 ml",
      "product_code": "CAN-350-AZ",
      "seo_name": "caneca-esmaltada-350-ml",
      "price_str": "49.90",
      "list_price_str": "59.90",
      "amount": 12,
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "company_name": "Loja Seller Teste",
      "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "timestamp": 1791751867,
      "updated_timestamp": 1791752114
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 50,
  "total_pages": 3
}

Campos da resposta

productsarray

Produtos da página. Cada item é um produto, com os campos descritos em Consultar produto; a lista não traz descriptions, videos nem linked_orders_count. Quando nada atende ao filtro o campo vem como null (e não []): trate os dois casos.

totalinteger

Total de produtos que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `view_catalog` nem `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna; ou, por limitação conhecida, `vendor_id`/`category_id`/datas com formato inválido	`{"error":"failed to list products","detail":"o valor \"abc\" não é um uuid válido. Corrija o campo e reenvie."}`

As mensagens de detail saem em português, como o servidor as devolve.

Veja também