Listar produtos

Lista paginada do catálogo, com busca por nome, código (SKU) ou código de barras. Exporta CSV com ?format=csv.

GET https://app.salos.com.br/api/products products:read

Filtros

Parâmetro Tipo O que faz
search texto procura por nome, código (SKU) ou código de barras
type physical, digital ou service só produtos do tipo
status active ou inactive só ativos ou só inativos (produto excluído/arquivado nunca aparece)
category_id id só da categoria (ou subcategoria)
sort name, sku, type, category, subcategory, price, stock, total_sold, sales_count, status, created, cost ou margin coluna de ordenação no catálogo inteiro (padrão name). price é o preço que se vende; cost/margin só ordenam pra quem vê custo — os outros recebem por name
dir asc ou desc direção (padrão asc)
limit número de 1 a 100 (padrão 25; no CSV o padrão é 100)
cursor texto o next_cursor da página anterior. ⚠️ Não mude o limit no meio da paginação
format csv devolve CSV; a próxima página vem no cabeçalho x-salos-next-cursor

Resposta

{
  "data": [
    {
      "id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
      "name": "Camiseta Básica",
      "type": "physical",
      "status": "active",
      "unit": "UN",
      "track_stock": true,
      "base_price": 49.9,
      "effective_price": 49.9,
      "price_inherits": true,
      "category_id": null,
      "category_name": null,
      "subcategory_name": null,
      "sku": "CAM-1",
      "default_variant_id": "4e8b2f6d-7a1c-4d5e-9f4b-8a2c6e1d3b84",
      "variant_count": 1,
      "stock": 12,
      "total_sold": 1996,
      "sales_count": 0,
      "created_at": "2026-10-06T12:00:00.000Z",
      "custom_fields": {}
    }
  ],
  "pagination": { "next_cursor": null }
}

total_sold soma só os negócios ganhos que a chave enxerga ("Só o dele" vale). Chave sem deals:read não recebe total_sold (nem a coluna no CSV). sales_count vem sempre 0 por aqui — para vendas por período, use GET/api/reports/products. effective_price é o preço que se vende (o que a linha do negócio copia). Cada produto tem uma única variação: default_variant_id é o id que vai em variant_id na linha do negócio.

⛔ Custo, imposto, lucro e margem só aparecem se quem responde pela chave é dono ou administrador da conta (ou da equipe Salos), conferido a cada chamada. Para os outros, as chaves cost, tax_rate, tax_value, gross_profit e margin não existem na resposta.