SaldoEstoque

Endpoint read-only. Toda escrita em SB2 é consequência de outro processo do ERP (entrada/saída fiscal, requisição, produção, transferência). Esta API não inclui, altera ou exclui saldo — só consulta. Inexiste POST, PUT ou DELETE nesta rota.

Chave externa composta. A rota canônica /WsSB2/{produto}/{local} identifica o saldo por B2_COD + B2_LOCAL. O endpoint aceita também /WsSB2/{produto} sem o segundo segmento — nesse caso o armazém é assumido como "01" (padrão default Protheus).

Bloqueio TOTVS não se aplica. A tabela SB2 não possui o par *_MSBLQL/*_MSBLQD no dicionário padrão — bloqueio administrativo de saldo não faz sentido (o saldo é resultado da movimentação, não um cadastro). Bloqueio comercial, se houver, mora no produto (SB5) ou no cliente/fornecedor.

Cálculo de saldo via SaldoSB2(). A rota /WsSB2/{produto}/{local} compõe um envelope que mistura saldo físico (lido direto de B2_QATU) com saldo disponível (calculado por SaldoSB2() aplicando empenhos, reservas e terceiros conforme query params opcionais). Os modificadores subtrairEmpenho, dataEmpenho, consideraTerceirosNossoPoder, consideraNossoEmTerceiros e subtrairReserva mapeiam diretamente para os argumentos posicionais (2º, 3º, 4º, 5º e 9º) da função nativa.

Paginação e delta-sync. /_list, /porProduto/{produto} e /porArmazem/{armazem} compartilham o mesmo motor de paginação: page/pageSize (default 50, máx 500) em orderBy=chave, ou orderBy=recno com since/cursor para sincronização incremental seguindo o nextCursor.

Campos opcionais do dicionário. B2_DUM (data da última movimentação) e B2_VATU1 (custo médio) existem na maioria dos ambientes mas não em todos os dicionários customizados. O endpoint testa presença via FieldPos(); se ausentes, as propriedades atualizadoEm e custoMedio simplesmente não aparecem na resposta — nunca há erro 500 por causa disso.

B2_MSUID ausente nesta base. O dicionário padrão TOTVS de SB2 não traz a coluna B2_MSUID nesta instalação. Por isso o _byid só aceita tipo=recno; tentativas com tipo=msuid retornariam 501 Not Implemented se a opção fosse exposta. Quando o ambiente do cliente expuser o campo (via UPDDISTR), o payload de resposta já vai incluí-lo automaticamente (FieldPos defensivo); a rota _byid?tipo=msuid precisa de uma revisão futura para implementar a busca via índice MSUID.

Custo de varredura em ambientes grandes. A /porArmazem e /_list sem cod fazem scan-full do índice de chave; em bases com milhões de SKUs isso pode ser caro. Sempre que possível, combinar com orderBy=recno + cursor. O limite hard PAGE_SIZE_MAX=500 evita OOM, mas não evita latência alta em catálogos extensos. Para reports analíticos prefira o DW (src/dw/) em vez deste endpoint.

Bloqueio MSBLQL/MSBLQD não aplicável. Saldo é resultado de movimentação, não cadastro. A SB2 não tem o par B2_MSBLQL/B2_MSBLQD no dicionário, e o endpoint é read-only — não há fluxo de bloqueio a documentar. Bloqueio comercial mora no produto (SB5) ou cliente/fornecedor; consultar lá quando relevante.

Sem _search (suggestion endpoint). A família de saldos não expõe /_search para autocomplete — o autocomplete de produto vem do WsProduto (SB1) e o de armazém do WsNNR. Esta API só consulta saldo, assumindo que o consumer já tem o código do produto/armazém em mãos.

Concorrência com movimento. O saldo retornado é um snapshot do instante do DbSeek; movimentos em paralelo (NF de saída, requisição) podem alterar B2_QATU entre a leitura e o uso pelo consumer. Para fluxos críticos (separação, expedição) prefira SaldoSB2() dentro do mesmo processo do movimento, em vez de cachear a resposta deste endpoint.