# Guia: consultar o estoque de chapas

Como listar as chapas em estoque de um material, com dimensões, metragem e disponibilidade. Exemplo de pergunta que este guia resolve: *"quantas chapas de Verde Ubatuba eu tenho disponíveis, e com quais medidas?"*

Pré-requisitos: `userHash` e `Servidor` ([Autenticação](../autenticacao.md)). O usuário precisa ter a permissão de estoque de chapas no GransoftWeb.

## 1. Sequência

1. Autenticar (ou usar o `userHash` já obtido).
2. Chamar `ListaEstoqueChapas` com o filtro desejado.
3. Agrupar o resultado por material e somar os m², se precisar de totais.

## 2. Requisição

```
POST {Servidor}/API/ListaEstoqueChapas
Content-Type: application/json
```

```json
{
  "userHash": "aEJ6cG1oUjllOExOMXB2ay91TE5U...",
  "Search": {
    "Keyword": "verde ubatuba",
    "Status": 0,
    "Reserva": 0,
    "MaxResult": 2000
  }
}
```

Campos de `Search`. Informe pelo menos um filtro (`Keyword`, `Codigo`, `CodigoMaterial`, `NrLote` ou `NrRomaneio`):

| Campo | Tipo | Descrição |
|---|---|---|
| `Keyword` | texto | Parte do nome do material ou da observação. Remova aspas, `%` e `;` antes de enviar. |
| `Codigo` | inteiro | Código de uma chapa específica. `0` = não filtra. |
| `CodigoMaterial` | inteiro | Código do material (produto do tipo pedra). `0` = não filtra. |
| `NrLote` | texto | Número do lote. |
| `NrRomaneio` | texto | Número do romaneio de entrada. |
| `Status` | inteiro | `0` em estoque, `1` vendidas. |
| `Reserva` | inteiro | `0` sem reserva (**disponíveis**), `1` só reservadas, `2` todas. |
| `Filial` | inteiro | Código da filial. `0` = filial do usuário. |
| `MaxResult` | inteiro | Máximo de chapas devolvidas. Para totais exatos, use um valor alto (ex.: `2000`). |

"Disponível" = `Status: 0` e `Reserva: 0`: em estoque e sem reserva para algum cliente.

## 3. Resposta

Valores fictícios:

```json
{
  "Erro": "",
  "Chapas": [
    {
      "Codigo": 3512,
      "Material": { "Descricao": "GRANITO VERDE UBATUBA POLIDO" },
      "txtMedidas": "3,100 X 1,850",
      "Dimensoes": {
        "ComprLiq": 3.10, "AltLiq": 1.85, "QtdLiqM2": 5.735,
        "CompBruto": 3.15, "AltBruto": 1.90, "QtdBrutM2": 5.985,
        "xMedidas": "3,100 X 1,850"
      },
      "txtStatusChapa": "Em estoque",
      "Reservado": false,
      "ReservadoM2": 0,
      "Localizacao": { "txtNroLote": "L-0425", "Local1": "Pátio A", "Local2": "Cavalete 3", "Local3": "" },
      "InfoFilial": { "Descricao": "MATRIZ" },
      "Observacao": ""
    }
  ]
}
```

| Campo | Descrição |
|---|---|
| `Codigo` | Código da chapa. |
| `Material.Descricao` | Nome do material. |
| `Dimensoes.ComprLiq`, `Dimensoes.AltLiq` | Comprimento e altura líquidos (aproveitáveis), em **metros**. |
| `Dimensoes.QtdLiqM2` | Área líquida em m². Use este valor para somar a metragem disponível. |
| `Dimensoes.CompBruto`, `AltBruto`, `QtdBrutM2` | Medidas brutas (antes dos descontos de borda). |
| `txtMedidas` / `Dimensoes.xMedidas` | Medidas já formatadas para exibição. |
| `txtStatusChapa` | Situação da chapa, em texto. |
| `Reservado`, `ReservadoM2` | Se há reserva e quantos m² estão reservados. |
| `Localizacao` | Lote (`txtNroLote`) e locais no pátio (`Local1` a `Local3`). |
| `InfoFilial.Descricao` | Filial onde a chapa está. |

O objeto da chapa tem mais campos (compra, venda, custo). O custo só deve ser exibido a quem tem permissão para vê-lo no sistema.

## 4. Totais por material

Uma busca por texto ("branco") pode trazer vários materiais (polido, escovado, levigado). Agrupe antes de responder:

```js
const r = await gs.chamar("ListaEstoqueChapas", {
  Search: { Keyword: limparBusca("verde ubatuba"), Status: 0, Reserva: 0, MaxResult: 2000 },
});

const porMaterial = {};
for (const c of r.Chapas ?? []) {
  const nome = c.Material?.Descricao ?? "(sem material)";
  porMaterial[nome] ??= { chapas: 0, m2: 0 };
  porMaterial[nome].chapas++;
  porMaterial[nome].m2 += c.Dimensoes?.QtdLiqM2 ?? 0;
}
console.table(porMaterial);
```

Exemplo completo: [kit/exemplo-estoque.js](../kit/exemplo-estoque.js).

## 5. Falhas comuns

| Sintoma | Causa | Solução |
|---|---|---|
| `Erro` de permissão | O usuário não tem acesso ao estoque de chapas. | Ajuste as permissões do usuário no GransoftWeb. |
| Lista vazia | Texto muito específico ou material sem chapas disponíveis. | Use só parte do nome ("ubatuba") ou `Reserva: 2`. |
| Totais menores que na tela | `MaxResult` baixo cortou a lista. | Aumente `MaxResult` ou filtre por `CodigoMaterial`. |
| Erro inesperado com aspas no texto | O texto é usado na busca sem tratamento. | Remova `'`, `"`, `%` e `;` do texto. |

## 6. Métodos relacionados

- `ListaItensAlmoxarifado`: saldo de insumos e ferramentas.
- `ConsultarPreco`: preço de venda por m² do material na tabela de preços.
- Baixa, reserva e alteração de status de chapas existem na API (`BaixarEstoqueChapa`, `AlterarStatusChapas`), mas alteram o estoque real. Consulte o Swagger e teste só com dados de teste.