# Listar saldos de insumos

> Escopo: estoque_insumos:ler. Sem custo. GET /estoque-insumos na API do Precificador 3D.

URL: https://precificador3d.com.br/docs/api/referencia/listar-estoque-insumos

`GET https://api.precificador3d.com.br/v1/estoque-insumos`

Escopo: `estoque_insumos:ler`. Sem custo.

Escopo: `estoque_insumos:ler`.

## Parâmetros

| Nome | Onde | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `limite` | query | integer | não | Itens por página, de 1 a 100. Acima de 25 conta como operação cara. (de 1 a 100; padrão 25) |
| `cursor` | query | string | não | Valor de `proximo_cursor` da página anterior. Opaco. (até 200 caracteres) |
| `If-None-Match` | header | string | não | ETag recebida antes. Se nada mudou, a resposta é `304` e não gasta a cota mensal. (até 100 caracteres) |
| `tipo` | query | string | não | Valores: `material_cor`, `adicional`, `embalagem`. |
| `abaixo_do_minimo` | query | boolean | não |  |

## Resposta 200

Página de saldos de insumos.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `dados` | array de SaldoInsumo | sim | (0 a 100 itens) |
| `dados[].insumo` | object | sim |  |
| `dados[].insumo.tipo` | string | sim | Valores: `material_cor`, `adicional`, `embalagem`. |
| `dados[].insumo.id` | string (uuid) | sim |  |
| `dados[].insumo.nome` | string | sim |  |
| `dados[].saldo` | number | sim |  |
| `dados[].unidade` | string | sim | Valores: `g`, `un`. |
| `dados[].minimo` | number \| null | sim |  |
| `dados[].abaixo_do_minimo` | boolean | sim |  |
| `dados[].atualizado_em` | string (date-time) | sim |  |
| `proximo_cursor` | string \| null | sim | Cursor da próxima página, ou `null` no fim. |

```json
{
  "dados": [
    {
      "insumo": {
        "tipo": "material_cor",
        "id": "4f5a6b7c-8d9e-4f0a-1b2c-3d4e5f6a7b8c",
        "nome": "PLA Silk · #015 Dourado"
      },
      "saldo": 320,
      "unidade": "g",
      "minimo": 500,
      "abaixo_do_minimo": true,
      "atualizado_em": "2026-10-03T11:40:00-03:00"
    }
  ],
  "proximo_cursor": null
}
```

## Outras respostas

- **304**: Nada mudou desde a ETag informada.
- **400** (`dados_invalidos`): Dados, filtro, cursor ou cabeçalho inválido.
- **401** (`nao_autenticado`): Chave ausente, malformada, desconhecida, revogada ou expirada (a resposta é a mesma para todos os casos).
- **403** (`escopo_insuficiente`): Escopo insuficiente, conta bloqueada, módulo desligado ou chave suspensa.
- **429** (`limite_excedido`): Limite de uso excedido (rajada, minuto, mês ou requisições simultâneas).
- **500** (`erro_interno`): Erro interno. O detalhe fica no log, ligado ao requisicao_id.
- **503** (`indisponivel`): API desligada, sob pressão (disjuntor aberto) ou no limite global da plataforma.

## Exemplos

**cURL**

```bash
curl "https://api.precificador3d.com.br/v1/estoque-insumos?limite=25" \
  -H "Authorization: Bearer $PC3D_CHAVE"
```

**JavaScript**

```js
const resposta = await fetch('https://api.precificador3d.com.br/v1/estoque-insumos?limite=25', {
  headers: {
    Authorization: `Bearer ${process.env.PC3D_CHAVE}`,
  },
});
if (!resposta.ok) {
  const erro = await resposta.json(); // application/problem+json
  throw new Error(`${erro.codigo}: ${erro.detail} (${erro.requisicao_id})`);
}
const dados = await resposta.json();
```

**Python**

```python
import os

import requests

resposta = requests.get(
    "https://api.precificador3d.com.br/v1/estoque-insumos",
    params={
        "limite": 25,
    },
    headers={
        "Authorization": f"Bearer {os.environ['PC3D_CHAVE']}",
    },
    timeout=10,
)
resposta.raise_for_status()
dados = resposta.json()
```