rev4-2026-05-14 Protheus 12.1.33

SaldoLote

Consulta read-only de saldo por lote (tabela SB8). Útil para FIFO/FEFO — a chave inclui produto, lote, opcionalmente subLote, e armazém. Saldo disponível = B8_SALDO - B8_EMPENHO - B8_QEMPPRE (quando o campo existir no dicionário). Não há POST/PUT/DELETE: rastreabilidade de lote é gerada/baixada via documentos fiscais e produção.

Vinculação com o ERP

Tabela mestre SB8 Saldo por lote (FIFO/FEFO)

Acesso Leitura direta SB8 Sem função agregadora nativa

Origem do dado SB8 + SB1 SB1 = descrição/unidade do produto

Operações & modos

GET read-only sem POST/PUT/DELETE

Dependências de ambiente

Cadastro

Produto (SB1)

B1_RASTRO=L ou S obriga rastreabilidade por lote/sublote para o produto aparecer em SB8.

Campos opcionais

B8_QEMPPRE / B8_DTVALID / B8_DFABRIC / B8_DTREFER

endpoint testa via FieldPos() e só inclui processo, dataValidade, dataFabricacao, dataReferencia se existirem

Índice

SB8 índice 1

B8_FILIAL+B8_PRODUTO+B8_LOTECTL+B8_NUMLOTE+B8_LOCAL+B8_DTVALID — usado por fGetSaldo e fGetListagem

Convenções

Endpoint read-only. Saldo de lote é gerado por NF de entrada (informando B8_LOTECTL) e baixado por NF de saída, requisição ou produção. Esta API não escreve em SB8.

Chave composta extensa. A rota canônica é /WsSB8/{produto}/{lote}/{armazem} (3 segmentos). Sub-lote (B8_NUMLOTE) é opcional via query string (?subLote=) — quando ausente, faz prefix-seek e devolve o primeiro registro do lote+armazém. Aceita também o atalho /WsSB8/{produto}/{lote} (armazém default "01").

Bloqueio TOTVS não se aplica. A SB8 não tem o par *_MSBLQL/*_MSBLQD no dicionário — saldo de lote não é cadastro. Bloqueio de produto vive em SB1/SB5.

Filtros de listagem. validadeAte (formato YYYYMMDD) corta lotes com B8_DTVALID maior que a data; somenteComSaldo=true filtra disponível (saldo - empenho - processo) maior que zero. Combinados são úteis para FEFO: lotes vencendo logo com saldo disponível.

Paginação e delta-sync. /_list e os atalhos /porProduto, /porLote, /porArmazem compartilham o mesmo motor: orderBy=chave (default) ou orderBy=recno com cursor.

Saldo

Consulta consolidada por lote

GET /WsSB8/{produto}/{lote}/{armazem} Saldo de um lote específico

Descrição

Retorna o saldo de um lote específico. A chave full inclui produto+lote+armazém; sub-lote (B8_NUMLOTE) é opcional via ?subLote=. Sem sub-lote, o endpoint faz prefix-seek e devolve o primeiro match de produto+lote+armazém.

O disponivel é calculado: B8_SALDO − B8_EMPENHO − B8_QEMPPRE (este último só quando o dicionário tem o campo).

Path parameters

produtostring · path · obrigatórioSB8.B8_PRODUTO

Código do produto.

lotestring · path · obrigatórioSB8.B8_LOTECTL

Código do lote (B8_LOTECTL).

armazemstring · path · opcionalSB8.B8_LOCAL

Armazém (default "01").

Cenário

Query parameters

subLotestring · query · opcionalSB8.B8_NUMLOTE

Sub-lote (B8_NUMLOTE). Sem este parâmetro, o endpoint pega o primeiro match.

Exemplo da requisição (cenário ativo)

Saldo do lote — chave full produto/lote/armazém.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/MP001/LOTE001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Saldo encontrado. Envelope { success: true, data: SaldoSB8 }.

400

Produto/lote ausentes. Tier: validation-error.

404

Saldo de lote não localizado. Tier: not-found.

500

Erro interno.

GET /WsSB8/_byid Consulta saldo por id técnico (recno)

Descrição

Busca o registro de saldo de lote por id técnico. Útil para integrações que persistem o recno retornado em /_list e querem reconfirmar sem refazer o seek pela chave composta de 5 partes.

Cenário

Query parameters

tipostring · query · obrigatório

Tipo do id técnico. Apenas recno.

recno

valorstring · query · obrigatório

Inteiro positivo. RecNo do registro em SB8.

Exemplo da requisição (cenário ativo)

Busca por RecNo — sempre disponível em qualquer base.

Request · por recnoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/_byid?tipo=recno&valor=5678
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Saldo encontrado.

400

tipo ausente / fora do enum, ou valor não-positivo.

404

RecNo inexistente ou registro de filial diferente.

500

Erro interno.

Listagem

Listagem paginada + filtros pré-definidos

GET /WsSB8/_list Lista saldos por lote com filtros e paginação

Descrição

Lista registros de SB8 com filtros opcionais por produto, lote, armazem, validadeAte e somenteComSaldo. Retorna campos crus + colunas calculadas (processo, disponivel, datas opcionais).

Dois modos de ordenação: orderBy=chave (default; índice 1) ou orderBy=recno (delta-sync com cursor).

Cenário

Query parameters

produtostring · opcionalSB8.B8_PRODUTO

Filtro exato em B8_PRODUTO — também serve de prefix-seek no índice 1.

lotestring · opcionalSB8.B8_LOTECTL

Filtro exato em B8_LOTECTL.

armazemstring · opcionalSB8.B8_LOCAL

Filtro exato em B8_LOCAL.

validadeAtestring · opcional

YYYYMMDD. Lotes com B8_DTVALID maior que essa data são descartados (útil para FEFO).

somenteComSaldoboolean · opcional

Filtra lotes com saldo - empenho - processo > 0. Default false.

fieldsstring · opcional

CSV de campos a retornar; validado contra CAMPOS_GET.

pageinteger · opcional

Default 1.

pageSizeinteger · opcional

Default 50, máx 500.

orderBystring · opcional

Default chave.

chaverecno

sinceinteger · opcional

RecNo mínimo (delta).

cursorinteger · opcional

Cursor de nextCursor da página anterior.

Exemplo da requisição (cenário ativo)

Paginação por chave — produto+lote+armazém combinados.

Request · paginadoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/_list?produto=MP001&armazem=01&page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

FEFO operacional — só lotes com saldo, validade até o corte; útil para sugestão de separação.

Request · FEFOHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/_list?produto=MP001&somenteComSaldo=true&validadeAte=20271231
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Delta-sync — sincronização incremental.

Request · delta-syncHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/_list?orderBy=recno&cursor=5678&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página. Envelope ListResponse.

400

fields com campo fora de CAMPOS_GET.

500

Erro interno.

GET /WsSB8/porProduto/{produto} Lista lotes filtrados por produto

Descrição

Atalho semântico — equivale a /_list?produto={produto}.

Path parameter

produtostring · path · obrigatórioSB8.B8_PRODUTO

Código do produto.

Cenário

Exemplo da requisição (cenário ativo)

Lista por produto — todos lotes (qualquer armazém).

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/porProduto/MP001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Página de lotes do produto. Quando não há lotes, data=[].

500

Erro interno.

GET /WsSB8/porLote/{lote} Lista por código de lote (B8_LOTECTL)

Descrição

Filtra todos os registros que compartilham o mesmo B8_LOTECTL — útil para rastreabilidade reversa (qual produto compõe esse lote, em quais armazéns está distribuído).

Atenção a custo. Lote sem produto faz scan-full do índice; prefira orderBy=recno em bases grandes.

Path parameter

lotestring · path · obrigatórioSB8.B8_LOTECTL

Código do lote.

Cenário

Exemplo da requisição (cenário ativo)

Rastreabilidade do lote — onde esse código de lote aparece.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/porLote/LOTE001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Página de registros com aquele lote.

500

Erro interno.

GET /WsSB8/porArmazem/{armazem} Lista lotes filtrados por armazém

Descrição

Atalho — equivale a /_list?armazem={armazem}. Inventário de lotes do armazém.

Path parameter

armazemstring · path · obrigatórioSB8.B8_LOCAL

Código do armazém.

Cenário

Exemplo da requisição (cenário ativo)

Inventário do armazém — todos lotes; usar orderBy=recno em base grande.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB8/porArmazem/01?orderBy=recno&pageSize=500
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Página.

500

Erro interno.

Schemas

Definições canônicas — campos com origem SX3 rastreável

SaldoSB8

object

Resposta de GET /WsSB8/{produto}/{lote}/{armazem}. Campos datas (dataValidade, dataFabricacao, dataReferencia) só aparecem se o dicionário tiver B8_DTVALID/B8_DFABRIC/B8_DTREFER.

produtostringSB8.B8_PRODUTO

Código do produto.

lotestringSB8.B8_LOTECTL

Código do lote.

subLotestringSB8.B8_NUMLOTE

Sub-lote (B8_NUMLOTE), trimado.

localstringSB8.B8_LOCAL

Armazém.

saldonumberSB8.B8_SALDO

Saldo bruto do lote.

empenhadonumberSB8.B8_EMPENHO

Empenho do lote.

processonumberSB8.B8_QEMPPRE

Empenho pré-empenhado (processo). Só aparece se o campo existir.

disponivelnumber

Calculado: saldo - empenhado - processo.

dataValidadestring · opcionalSB8.B8_DTVALID

YYYYMMDD. Só aparece se o campo existir no dicionário.

dataFabricacaostring · opcionalSB8.B8_DFABRIC

YYYYMMDD.

dataReferenciastring · opcionalSB8.B8_DTREFER

YYYYMMDD.

recnointeger

Id técnico (RecNo).

SaldoLinha

object

Linha retornada em /_list, atalhos e /_byid. Conjunto efetivo depende de ?fields=.

B8_PRODUTOstring · opcional

Código do produto.

B8_LOTECTLstring · opcional

Código do lote.

B8_NUMLOTEstring · opcional

Sub-lote.

B8_LOCALstring · opcional

Armazém.

B8_SALDOnumber · opcional

Saldo bruto.

B8_EMPENHOnumber · opcional

Empenho.

processonumber

Calculado a partir de B8_QEMPPRE.

disponivelnumber

Calculado.

recnointeger

RecNo.

ListResponse

object · envelope

Envelope das listagens. page só em orderBy=chave; nextCursor só em orderBy=recno.

successboolean

true.

dataarray<SaldoLinha>

Itens.

pageinteger · opcional

Em orderBy=chave.

pageSizeinteger

Aplicado.

countinteger

Tamanho efetivo.

orderBystring

Modo aplicado.

chaverecno

nextCursorinteger · opcional

RecNo da próxima página em delta-sync.

Erro

object · envelope

Envelope padrão de erros.

successboolean

false em erros.

messagestring

Mensagem editorial.

datastring · opcional

Detalhe técnico.

Cenários

Catálogo de combinações reconhecidas. Endpoint read-only — todos os cenários usam GET.

consulta-direta

GET /WsSB8/{produto}/{lote}/{armazem}

Saldo de um lote específico. Sub-lote opcional via query. Quando usar: conferência pontual de saldo de lote.

byid-recno

GET /WsSB8/_byid

Busca por RecNo(). Não há byid-msuid: B8_MSUID ausente no dicionário desta base — ver Pendências.

listagem-paginada

GET /WsSB8/_list

Default orderBy=chave + page/pageSize. Filtros opcionais de produto/lote/armazém.

listagem-somente-com-saldo

GET /WsSB8/_list

somenteComSaldo=true + validadeAte. Lista para FEFO operacional — só lotes com disponível e vencendo até a data.

delta-sync

GET /WsSB8/_list

orderBy=recno + cursor; sincronização incremental.

por-produto

GET /WsSB8/porProduto/{produto}

Atalho — todos os lotes do produto.

por-lote

GET /WsSB8/porLote/{lote}

Rastreabilidade reversa — onde aparece esse código de lote.

por-armazem

GET /WsSB8/porArmazem/{armazem}

Inventário de lotes do armazém.

Pendências conhecidas (rev3)

B8_MSUID ausente nesta base. O dicionário padrão TOTVS de SB8 não traz B8_MSUID nesta instalação. _byid só aceita tipo=recno; tentativas com tipo=msuid retornariam 501 se a opção fosse exposta. Implementação requer UPDDISTR no dicionário e revisão da rota _byid?tipo=msuid.

Volumetria alta em SB8. Bases com rastreabilidade ativa por anos podem ter centenas de milhares de registros em SB8 — uma linha por produto+lote+sublote+armazém+validade. PAGE_SIZE_MAX=500 evita OOM, mas listagem total exige orderBy=recno + cursor em iterações. Para reports analíticos prefira o DW (src/dw/).

Sub-lote ambíguo sem produto. A rota /porLote/{lote} filtra por B8_LOTECTL, não por sub-lote (B8_NUMLOTE). Quando o mesmo código de lote é usado em produtos diferentes (raro, mas válido), o resultado mistura todos. Refinar por ?produto= se necessário.

Bloqueio MSBLQL/MSBLQD não aplicável. Saldo de lote é resultado de movimentação, não cadastro. Bloqueio comercial vive em SB1/SB5; bloqueio de qualidade típico (lote em quarentena) é controlado por outro fluxo (CQ — controle de qualidade), fora do escopo deste endpoint.

Sem _search. Autocomplete de lote ainda não é exposto. Quando necessário, listar por /porProduto e filtrar no consumer.

Concorrência com movimento. Snapshot do instante do DbSeek. Para alocação de lote em separação, prefira chamar a função nativa diretamente no mesmo processo do movimento.