Estoque (inventory)

O recurso inventory expõe os itens de estoque da sua conta: nome, descrição, unidade de medida, saldo atual, alerta de reposição, código EAN e o vínculo com o item do catálogo, quando houver.

Acesso


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

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/inventory`	Lista itens de estoque, com paginação por cursor
`GET`	`/v1/inventory/{id}`	Retorna um item de estoque pelo `id`

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do item de estoque
`name`	`string`	Nome do item
`description`	`string \| null`	Descrição livre do item
`unit`	`string \| null`	Unidade de medida, por exemplo `un`, `kg`, `L` ou `cx`
`current_stock`	`number \| null`	Quantidade atual em estoque
`min_stock_alert`	`number \| null`	Quantidade que dispara o alerta de reposição
`ean_code`	`string \| null`	Código de barras EAN do item
`catalog_item_id`	`uuid \| null`	Item do catálogo vinculado, quando houver
`is_in_catalog`	`boolean \| null`	Se o item está publicado no catálogo
`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,current_stock,min_stock_alert.

Filtros e ordenação

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

Campo	Exemplo
`name`	`filter[name][ilike]=%parafuso%`
`is_active`	`filter[is_active][eq]=true`
`catalog_item_id`	`filter[catalog_item_id][eq]=6f1e2c3a-9b4d-4e5f-8a7b-1c2d3e4f5a6b`

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, com detail no formato filter_field_not_allowed:<campo>.

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

Itens ativos, do mais recente para o mais antigo:

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

{
  "data": [
    {
      "id": "b3f2a1d4-7c8e-4f5a-9b6c-2d1e0f9a8b7c",
      "name": "Cimento CP-II 50kg",
      "description": "Saco de cimento para obras em geral",
      "unit": "sc",
      "current_stock": 42,
      "min_stock_alert": 10,
      "ean_code": "7891234567895",
      "catalog_item_id": "6f1e2c3a-9b4d-4e5f-8a7b-1c2d3e4f5a6b",
      "is_in_catalog": true,
      "is_active": true,
      "created_at": "2026-06-28T14:03:22.481Z",
      "updated_at": "2026-07-05T09:41:10.207Z"
    },
    {
      "id": "a1c9e8d7-3b2f-4a6e-8c5d-4f3e2d1c0b9a",
      "name": "Luva nitrílica M",
      "description": null,
      "unit": "par",
      "current_stock": 7,
      "min_stock_alert": 15,
      "ean_code": null,
      "catalog_item_id": null,
      "is_in_catalog": false,
      "is_active": true,
      "created_at": "2026-06-12T08:15:44.902Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImExYzllOGQ3Li4uIiwidiI6IjIwMjYtMDYtMTJUMDg6MTU6NDQuOTAyWiJ9",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

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

A API não tem um filtro pronto para “abaixo do mínimo”: compare current_stock com min_stock_alert no seu lado, ou peça só as duas colunas com fields para reduzir o tráfego.

curl -G "$LIGGA_BASE/v1/inventory" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "fields=id,name,current_stock,min_stock_alert" \
  --data-urlencode "filter[is_active][eq]=true" \
  --data-urlencode "limit=100"

Buscar por id

curl "$LIGGA_BASE/v1/inventory/b3f2a1d4-7c8e-4f5a-9b6c-2d1e0f9a8b7c" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "b3f2a1d4-7c8e-4f5a-9b6c-2d1e0f9a8b7c",
    "name": "Cimento CP-II 50kg",
    "description": "Saco de cimento para obras em geral",
    "unit": "sc",
    "current_stock": 42,
    "min_stock_alert": 10,
    "ean_code": "7891234567895",
    "catalog_item_id": "6f1e2c3a-9b4d-4e5f-8a7b-1c2d3e4f5a6b",
    "is_in_catalog": true,
    "is_active": true,
    "created_at": "2026-06-28T14:03:22.481Z",
    "updated_at": "2026-07-05T09:41:10.207Z"
  },
  "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 `estoque` fora do contrato
403	`insufficient_scope`	Chave sem `inventory: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

Produtos (products) — o catálogo apontado por catalog_item_id
Paginação, filtros e ordenação — cursor, sort e fields
Módulos e escopos — por que um 403 acontece
Erros — o formato da resposta de erro