> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.mgnsystem.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Estoque Geral

> https://[url.projeto]/wms/v1/consultar-estoque

## **Visão Geral**

A API de Consulta de Estoque do WMS foi desenvolvida para permitir que sistemas externos consultem a \*\*posição atual de estoque \*\*de forma **padronizada**, segura e **performática**.

Seu objetivo é disponibilizar uma visão consolidada ou detalhada do estoque da empresa autenticada, respeitando o contexto multi-tenant do WMS e aplicando os filtros informados na requisição.

A consulta pode ser realizada com base em diferentes critérios, como:

* `código do produto`
* `lote`
* `endereço`
* `etiqueta`

Dessa forma, a API de Consulta de Estoque permite integrar o WMS com ERPs, portais, sistemas legados ou outras aplicações externas, oferecendo uma **visão confiável** e atualizada do estoque armazenado.

Método HTTP: POST `/v1/estoque-geral`

## Headers

| Nome          | Valor              |
| :------------ | :----------------- |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

## Campos

### Produto

| Nome              | Tipo   | Descrição                                     |
| :---------------- | :----- | :-------------------------------------------- |
| `produto_codigo`  | string | Código do produto                             |
| `lote`            | string | Lote do produto                               |
| `endereco_codigo` | string | Exemplo: A-01-B-001                           |
| `etiqueta_codigo` | string | Código da etiqueta                            |
| `agrupar_por`     | string | Aceita: `produtoproduto_loteenderecoetiqueta` |

## **Exemplo**

<RequestExample>
  ```json body theme={null}
  {
    "produto_codigo": "AGUA001",
    "lote": "AGA0919",
    "agrupar_por": "produto_lote"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
  	"ok": true,
  	"status": 200,
  	"message": "Consulta de estoque realizada com sucesso",
  	"request_id": "ID REQUEST",
  	"data": {
  		"filtros": {
  			"lote": null,
  			"agrupar_por": "produto_lote",
  			"produto_codigo": null,
  			"endereco_codigo": null,
  			"etiqueta_codigo": null
  		},
  		"resultado": [
  			{
  				"lote": "1738/18",
  				"produto_id": "ID PRODUTO",
  				"total_linhas": 4,
  				"data_validade": "2029-01-01",
  				"produto_codigo": "AGUA001",
  				"unidade_medida": "UN",
  				"total_enderecos": 3,
  				"total_etiquetas": 4,
  				"peso_bruto_total": 0,
  				"quantidade_total": 1000,
  				"produto_descricao": "Água Mineral sem Gás 1,5L",
  				"peso_liquido_total": 0,
  				"quantidade_bloqueada": 0,
  				"quantidade_reservada": 0,
  				"quantidade_disponivel": 1000
  			}
  		]
  	}
  }
  ```
</ResponseExample>

## Erros comuns

| **Código** | **Mensagem**                            | **Causa Provável**                                                                                                                                        |
| :--------- | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400        | Parâmetro `agrupar_por` inválido        | Valor diferente dos aceitos pela API. Valores permitidos: <br />`produto`, `produto_lote`, `endereco`, `etiqueta`                                         |
| 401        | Sessão inválida                         | Token Bearer ausente, inválido, expirado ou não reconhecido.                                                                                              |
| 400        | Parâmetros enviados em formato inválido | Algum campo de filtro foi enviado em formato incompatível com o esperado                                                                                  |
| 400        | Filtro de consulta inválido             | Um ou mais filtros informados não puderam ser processados corretamente                                                                                    |
| 500        | Erro interno ao processar entrada       | Falha inesperada no processamento da RPC, normalmente causada por inconsistência de dados, <br />relacionamento inválido ou estrutura incompleta no banco |

<Note>
  * Se nenhum parâmetro for enviado na requisição, o sistema aplicará automaticamente o filtro `"agrupar_por": "produto_lote"`.
  * A função respeita as **RLS policies** para garantir que o usuário só altere dados da empresa à qual está vinculado.
</Note>