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.0/productsAutenticada

Listar produtos

A ordem padrão é da criação mais recente para a mais antiga. Autenticação: HTTP Basic com e-mail:chave_de_api, ou Authorization: Bearer <JWT>; a leitura aceita qualquer usuário autenticado. A rota também responde em /api/products (sem /v1.0); nessa forma os ids saem como números decimais em string (veja a home da seção).

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 100. Valores de 101 a 250 não são limitados a 100: voltam ao padrão da plataforma (20). 0, texto ou mais de 250 são ignorados e valem 10.

statusstring

ADH

Filtra pelo status (A ativo, D desativado, H oculto). Sem este filtro a lista traz todos os status. Os produtos aguardando aprovação (R) e rejeitados (X) não têm filtro: qualquer outro valor vira A.

qstring

Busca por texto: todas as palavras precisam aparecer em algum destes campos: nome, descrição, descrição curta, código, palavras-chave e código de barras. Sem diferenciar maiúsculas e acentos. Colar um UUID ou o número curto do produto também o encontra.

product_codestring

Código do produto. Contém o texto, sem diferenciar maiúsculas (ZZ encontra ZZ-001 e AZZ9); não é igualdade.

company_idstring

Somente produtos deste seller (UUID; na rota /api/products, o id decimal). Um UUID malformado devolve 500.

category_idstring

Somente produtos desta categoria (UUID; na rota /api/products, o id decimal). Casa pelo vínculo de categoria, principal ou adicional, e é exato: não inclui as subcategorias.

price_fromstring

Preço mínimo, em decimal ("49.90" ou "49,90").

price_tostring

Preço máximo, em decimal.

sort_bystring

productpricelist_pricecodetimestampamountstatusposition

Campo de ordenação. product ordena por nome, price e list_price por preço, timestamp e position por data de criação, amount por estoque. code e status não ordenam por código nem por status: caem na ordenação por nome. Outro valor é ignorado (data de criação).

sort_orderstringpadrão: desc

ascdesc

Direção da ordenação.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/products?status=A&q=caneca&sort_by=price&sort_order=asc&items_per_page=50"

Resposta

200Produtos retornados

json

{
  "products": [
    {
      "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
      "product": "Caneca Esmaltada 350 ml",
      "product_code": "CAN-350-AZ",
      "product_type": "P",
      "status": "A",
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "price": "49.90",
      "list_price": "59.90",
      "amount": 12,
      "tracking": "Y",
      "weight": "0.350",
      "length": "12.00",
      "width": "9.00",
      "height": "9.00",
      "free_shipping": "N",
      "min_qty": 0,
      "max_qty": 0,
      "qty_step": 1,
      "full_description": "<p>Caneca esmaltada azul.</p>",
      "short_description": "",
      "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "category_ids": ["7ebc648d-6091-4511-8ea2-f86f7b3b4dd9"],
      "seo_name": "caneca-esmaltada-350-ml",
      "page_title": "",
      "meta_description": "",
      "meta_keywords": "",
      "search_words": "",
      "promo_text": "",
      "popularity": 0,
      "position": 0,
      "master_product_id": "",
      "zero_price_action": "R",
      "shipping_freight": 0,
      "timestamp": 1791751867,
      "updated_timestamp": 1791752114,
      "main_pair": {
        "pair_id": "acd51513-0264-46c7-a667-504e3ec77e19",
        "image_id": "acd51513-0264-46c7-a667-504e3ec77e19",
        "detailed": { "image_path": "/uploads/caneca-azul.png", "alt": "" },
        "icons": { "image_path": "/uploads/caneca-azul.png?w=100", "alt": "" }
      },
      "image_pairs": {},
      "product_features": [],
      "product_options": [],
      "prices": [],
      "brand": "",
      "tax_ids": [],
      "category_names": [],
      "variation_features": {}
    }
  ],
  "params": { "page": 1, "items_per_page": 50, "total_items": 142 }
}

Campos da resposta

productsarray

Produtos da página. Cada item é o produto completo, com os campos descritos em Consultar produto. Sem resultados, vem [].

paramsobject

Paginação: page, items_per_page (valor aplicado) e total_items (total de produtos que atendem ao filtro, em todas as páginas).

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
404	(rota `/api/products`) `company_id` ou `category_id` decimal que não corresponde a nenhum registro	`{"message":"Not found","status":404}`
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, `company_id`/`category_id` com formato inválido	`{"message":"Failed to retrieve products","status":500}`

Veja também

Listar produtos

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

GET/api/v1.0/productsAutenticada

Listar produtos

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 100. Valores de 101 a 250 não são limitados a 100: voltam ao padrão da plataforma (20). 0, texto ou mais de 250 são ignorados e valem 10.

statusstring

ADH

qstring

product_codestring

Código do produto. Contém o texto, sem diferenciar maiúsculas (ZZ encontra ZZ-001 e AZZ9); não é igualdade.

company_idstring

Somente produtos deste seller (UUID; na rota /api/products, o id decimal). Um UUID malformado devolve 500.

category_idstring

Somente produtos desta categoria (UUID; na rota /api/products, o id decimal). Casa pelo vínculo de categoria, principal ou adicional, e é exato: não inclui as subcategorias.

price_fromstring

Preço mínimo, em decimal ("49.90" ou "49,90").

price_tostring

Preço máximo, em decimal.

sort_bystring

productpricelist_pricecodetimestampamountstatusposition

sort_orderstringpadrão: desc

ascdesc

Direção da ordenação.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/products?status=A&q=caneca&sort_by=price&sort_order=asc&items_per_page=50"

Resposta

200Produtos retornados

json

{
  "products": [
    {
      "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
      "product": "Caneca Esmaltada 350 ml",
      "product_code": "CAN-350-AZ",
      "product_type": "P",
      "status": "A",
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "price": "49.90",
      "list_price": "59.90",
      "amount": 12,
      "tracking": "Y",
      "weight": "0.350",
      "length": "12.00",
      "width": "9.00",
      "height": "9.00",
      "free_shipping": "N",
      "min_qty": 0,
      "max_qty": 0,
      "qty_step": 1,
      "full_description": "<p>Caneca esmaltada azul.</p>",
      "short_description": "",
      "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "category_ids": ["7ebc648d-6091-4511-8ea2-f86f7b3b4dd9"],
      "seo_name": "caneca-esmaltada-350-ml",
      "page_title": "",
      "meta_description": "",
      "meta_keywords": "",
      "search_words": "",
      "promo_text": "",
      "popularity": 0,
      "position": 0,
      "master_product_id": "",
      "zero_price_action": "R",
      "shipping_freight": 0,
      "timestamp": 1791751867,
      "updated_timestamp": 1791752114,
      "main_pair": {
        "pair_id": "acd51513-0264-46c7-a667-504e3ec77e19",
        "image_id": "acd51513-0264-46c7-a667-504e3ec77e19",
        "detailed": { "image_path": "/uploads/caneca-azul.png", "alt": "" },
        "icons": { "image_path": "/uploads/caneca-azul.png?w=100", "alt": "" }
      },
      "image_pairs": {},
      "product_features": [],
      "product_options": [],
      "prices": [],
      "brand": "",
      "tax_ids": [],
      "category_names": [],
      "variation_features": {}
    }
  ],
  "params": { "page": 1, "items_per_page": 50, "total_items": 142 }
}

Campos da resposta

productsarray

Produtos da página. Cada item é o produto completo, com os campos descritos em Consultar produto. Sem resultados, vem [].

paramsobject

Paginação: page, items_per_page (valor aplicado) e total_items (total de produtos que atendem ao filtro, em todas as páginas).

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
404	(rota `/api/products`) `company_id` ou `category_id` decimal que não corresponde a nenhum registro	`{"message":"Not found","status":404}`
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, `company_id`/`category_id` com formato inválido	`{"message":"Failed to retrieve products","status":500}`