Produtos (products)

O recurso products expõe os itens do catálogo da sua conta: produtos e serviços com preço de venda e de custo, unidade, códigos EAN e interno, categorização, saldo de estoque e disponibilidade no catálogo público. Itens excluídos no aplicativo nunca aparecem nas respostas.

Acesso


Módulo	`catalogo`
Escopos	`products:read` (também concedido por `:read` e por `:write`)
Operações	somente leitura

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/products`	Lista produtos, com paginação por cursor
`GET`	`/v1/products/{id}`	Retorna um produto pelo `id`

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do produto
`name`	`string`	Nome do produto ou serviço
`description`	`string \| null`	Descrição livre
`unit`	`string`	Unidade de venda, por exemplo `un`, `kg` ou `h`
`selling_price`	`number`	Preço de venda
`cost_price`	`number`	Preço de custo
`is_variable_price`	`boolean \| null`	Se o preço é definido no momento da venda
`min_price`	`number \| null`	Preço mínimo, quando o preço é variável
`max_price`	`number \| null`	Preço máximo, quando o preço é variável
`ean_code`	`string \| null`	Código de barras EAN
`internal_code`	`string \| null`	Código interno ou SKU
`category_id`	`uuid \| null`	Categoria do catálogo
`subcategory_id`	`uuid \| null`	Subcategoria do catálogo
`current_stock`	`number \| null`	Saldo atual em estoque
`min_stock_alert`	`number \| null`	Saldo que dispara o alerta de reposição
`manages_stock`	`boolean \| null`	Se o item controla estoque
`is_in_catalog`	`boolean \| null`	Se o item aparece no catálogo público
`allows_appointments`	`boolean \| null`	Se o item pode ser agendado
`image_url`	`string \| null`	Endereço da imagem do produto
`is_active`	`boolean \| null`	Se o item está ativo
`created_at`	`string (ISO 8601) \| null`	Data de criação
`updated_at`	`string (ISO 8601) \| null`	Data da última atualização

Use fields para receber só um subconjunto das colunas: ?fields=id,name,selling_price.

Filtros e ordenação

A sintaxe do filtro é filter[campo][operador]=valor. Os campos filtráveis de products são:

Campo	Exemplo
`name`	`filter[name][ilike]=%shampoo%`
`is_active`	`filter[is_active][eq]=true`
`category_id`	`filter[category_id][eq]=6f2c9d10-3b4a-4c5d-8e7f-0a1b2c3d4e5f`
`ean_code`	`filter[ean_code][eq]=7891234567895`
`is_in_catalog`	`filter[is_in_catalog][eq]=true`

Os operadores aceitos são eq, neq, gt, gte, lt, lte, in, nin, ilike e is_null. Um campo fora da lista acima responde 422 validation.

A ordenação usa sort=campo para crescente e sort=-campo para decrescente. Os campos ordenáveis são created_at, updated_at e name. O padrão é -created_at.

A listagem também aceita limit (de 1 a 100, padrão 20) e cursor. Veja Paginação, filtros e ordenação.

Exemplos

Listar

Produtos ativos cujo nome contém shampoo:

curl -G "$LIGGA_BASE/v1/products" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "limit=2" \
  --data-urlencode "filter[is_active][eq]=true" \
  --data-urlencode "filter[name][ilike]=%shampoo%" \
  --data-urlencode "sort=-created_at"

{
  "data": [
    {
      "id": "b7e1f3a2-8c4d-4e5f-9a6b-1c2d3e4f5a6b",
      "name": "Shampoo Hidratante 300ml",
      "description": "Linha profissional para cabelos secos",
      "unit": "un",
      "selling_price": 49.9,
      "cost_price": 22.5,
      "is_variable_price": false,
      "min_price": null,
      "max_price": null,
      "ean_code": "7891234567895",
      "internal_code": "SHP-300",
      "category_id": "6f2c9d10-3b4a-4c5d-8e7f-0a1b2c3d4e5f",
      "subcategory_id": null,
      "current_stock": 34,
      "min_stock_alert": 5,
      "manages_stock": true,
      "is_in_catalog": true,
      "allows_appointments": false,
      "image_url": "https://cdn.exemplo.com/produtos/shp-300.jpg",
      "is_active": true,
      "created_at": "2026-05-18T12:34:56Z",
      "updated_at": "2026-06-02T09:10:11Z"
    },
    {
      "id": "0d9e8f7a-6b5c-4d3e-2f1a-9b8c7d6e5f4a",
      "name": "Shampoo Antiqueda 250ml",
      "description": null,
      "unit": "un",
      "selling_price": 39.9,
      "cost_price": 18,
      "is_variable_price": false,
      "min_price": null,
      "max_price": null,
      "ean_code": "7899876543210",
      "internal_code": "SHP-250",
      "category_id": "6f2c9d10-3b4a-4c5d-8e7f-0a1b2c3d4e5f",
      "subcategory_id": null,
      "current_stock": 12,
      "min_stock_alert": 5,
      "manages_stock": true,
      "is_in_catalog": true,
      "allows_appointments": false,
      "image_url": null,
      "is_active": true,
      "created_at": "2026-04-30T08:00:00Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjBkOWU4ZjdhLi4uIiwidiI6IjIwMjYtMDQtMzBUMDg6MDA6MDBaIn0",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Enquanto pagination.has_more for true, repita a chamada passando cursor=<pagination.next_cursor>.

Uma leitura por código de barras devolve zero ou um item:

curl -G "$LIGGA_BASE/v1/products" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "filter[ean_code][eq]=7891234567895"

Buscar por id

curl "$LIGGA_BASE/v1/products/b7e1f3a2-8c4d-4e5f-9a6b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "b7e1f3a2-8c4d-4e5f-9a6b-1c2d3e4f5a6b",
    "name": "Shampoo Hidratante 300ml",
    "description": "Linha profissional para cabelos secos",
    "unit": "un",
    "selling_price": 49.9,
    "cost_price": 22.5,
    "is_variable_price": false,
    "min_price": null,
    "max_price": null,
    "ean_code": "7891234567895",
    "internal_code": "SHP-300",
    "category_id": "6f2c9d10-3b4a-4c5d-8e7f-0a1b2c3d4e5f",
    "subcategory_id": null,
    "current_stock": 34,
    "min_stock_alert": 5,
    "manages_stock": true,
    "is_in_catalog": true,
    "allows_appointments": false,
    "image_url": "https://cdn.exemplo.com/produtos/shp-300.jpg",
    "is_active": true,
    "created_at": "2026-05-18T12:34:56Z",
    "updated_at": "2026-06-02T09:10:11Z"
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`api_disabled`	A conta ainda não tem a API habilitada
403	`module_not_enabled`	Módulo `catalogo` fora do contrato
403	`insufficient_scope`	Chave sem `products:read`
404	`not_found`	`id` inexistente ou pertencente a outra conta
422	`validation`	Campo de filtro, operador, `sort` ou `cursor` não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

Veja também

Estoque (inventory) — os itens de estoque por trás de current_stock
Vendas (sales) — onde os produtos viram itens de venda
Paginação, filtros e ordenação — cursor, sort e fields
Módulos e escopos — por que um 403 acontece