Consulta de Saldo dos Itens

Este manual descreve a melhoria implementada na API que permite consultar as quantidades em estoque de um item. O objetivo é orientar o usuário, de forma clara e didática, sobre como utilizar o endpoint, quais parâmetros são necessários e como interpretar os resultados.

🎯 Objetivo da Melhoria

Foi criado um endpoint GET na API que possibilita ao usuário consultar, em tempo real:

📌 Quantidade confirmada

📌 Quantidade em pedido

📌 Quantidade em estoque

📌 Quantidade disponível

Esse recurso auxilia na tomada de decisões relacionadas a consumo, compras e disponibilidade de materiais.

🔗 Endpoint GET /api/v1/itens/consulta ⚙️ Parâmetros da Consulta

Obrigatório:

codigoItem (string) → Código do item a ser consultado.

Importante

Caso o usuário não preencha o campo codigoItem, a consulta será bloqueada e uma mensagem de erro será exibida.

Opcional:

deposito (string) → Código do depósito.

Se informado: retorna apenas os dados do depósito especificado.

Se não informado: traz os dados de todos os depósitos vinculados ao item.

📦 Dados Retornados

A consulta retorna um objeto JSON com as seguintes informações:

quantidadeConfirmada → Quantidade já confirmada em processos.

quantidadeEmPedido → Quantidade em aberto em pedidos.

quantidadeEmEstoque → Quantidade total em estoque.

quantidadeDisponivel → Quantidade livre para uso (considera reservas e confirmações).

📝 Exemplos de Retorno

❌ Erro (parâmetro obrigatório ausente):

{ "erro": "O campo 'codigoItem' é obrigatório para realizar a consulta." }

✅ Exemplo de retorno válido (com depósito):

{
    "codigoItem": "MPBV044",
    "deposito": "01",
    "quantidadeConfirmada": 15,
    "quantidadeEmPedido": 30,
    "quantidadeEmEstoque": 120,
    "quantidadeDisponivel": 75
}

🧪 Como Realizar os Testes

Passo 1: Validar campo obrigatório

Executar a consulta sem informar codigoItem.

Esperado: O sistema retorna mensagem de erro informando que o campo é obrigatório.

Passo 2: Consulta básica

Informar apenas codigoItem.

Esperado: Retorno com todas as quantidades do item em todos os depósitos.

Passo 3: Consulta filtrada

Informar codigoItem + deposito.

Esperado: Retorno apenas com os dados do depósito informado.

Passo 4: Conferência de valores

Validar se os valores retornados (confirmada, em pedido, em estoque e disponível) correspondem aos dados reais do sistema.

📋 Checklist de Testes

💡 Considerações Finais

Este endpoint é essencial para oferecer visibilidade em tempo real das quantidades em estoque, permitindo maior precisão na gestão de pedidos, reservas e consumo de materiais.