rev4-2026-05-14 Protheus 12.1.33

SaldoEndereco

Consulta read-only de saldo por endereço (tabela SBF, família WMS). Chave inclui produto + armazém + endereço (BF_LOCALIZ), com lote/sub-lote/série opcionais via query. Saldo disponível = BF_QUANT - BF_EMPENHO (quando o campo existir). Não há POST/PUT/DELETE: movimentação em endereço é gerada por documentos WMS (acerto, transferência, separação).

Vinculação com o ERP

Tabela mestre SBF Saldo por endereço (WMS)

Acesso Leitura direta SBF Sem função agregadora nativa

Índice padrão SBF índice 2 (SBF9902) BF_FILIAL+BF_PRODUTO+BF_LOCAL+BF_LOTECTL+BF_NUMLOTE+BF_PRIOR+BF_LOCALIZ+BF_NUMSERI

Operações & modos

GET read-only sem POST/PUT/DELETE

Dependências de ambiente

Configuração WMS

Endereço habilitado para o armazém

Endereçamento (BF_LOCALIZ) só faz sentido quando o armazém tem WMS ativo; em ambientes sem WMS, SBF fica vazio (saldo agregado vive em SB2/SB8).

Campos opcionais

BF_EMPENHO / BF_DATAVEN / BF_DINVENT

testados via FieldPos(); só aparecem empenhada, dataValidade e dataInventario se existirem.

Rastreabilidade

BF_LOTECTL / BF_NUMLOTE / BF_NUMSERI

preenchidos quando o produto controla lote (B1_RASTRO=L) ou série (B1_RASTRO=S). Sem rastreabilidade, vazios.

Convenções

Endpoint read-only. Movimentação em endereço acontece por documentos WMS (acerto, transferência interna, separação). Esta API não escreve em SBF.

Chave composta extensa. Rota canônica /WsSBF/{produto}/{armazem}/{endereco} (3 segmentos obrigatórios). lote, subLote e serie são opcionais via query string. Sem eles, faz prefix-seek pelo endereço e devolve o primeiro match.

Endereçamento exige WMS. Em armazéns sem WMS, SBF tipicamente fica vazio — o saldo agregado é o de SB2 (sem endereço). Esta API só faz sentido em filiais com endereçamento ativo.

Bloqueio TOTVS não se aplica. Sem *_MSBLQL/*_MSBLQD em SBF. Bloqueio de endereço (manutenção, quarentena WMS) é controlado em outras tabelas (SBJ, etc.), fora do escopo deste endpoint.

Paginação e delta-sync. /_list + atalhos compartilham orderBy=chave (default; índice 2) ou orderBy=recno com cursor.

Saldo

Consulta por endereço específico

GET /WsSBF/{produto}/{armazem}/{endereco} Saldo de um produto em um endereço específico

Descrição

Saldo de um produto em um endereço específico. Lote, sub-lote e série são opcionais via query — sem eles, faz prefix-seek pelo endereço e retorna o primeiro registro.

disponivel = BF_QUANT − BF_EMPENHO (este último só quando o campo existir no dicionário).

Path parameters

produtostring · path · obrigatórioSBF.BF_PRODUTO

Código do produto.

armazemstring · path · obrigatórioSBF.BF_LOCAL

Armazém.

enderecostring · path · obrigatórioSBF.BF_LOCALIZ

Endereço WMS.

Cenário

Query parameters

lotestring · opcionalSBF.BF_LOTECTL

Lote (B8_LOTECTL).

subLotestring · opcionalSBF.BF_NUMLOTE

Sub-lote.

seriestring · opcionalSBF.BF_NUMSERI

Número de série (rastreabilidade tipo S).

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

Saldo do endereço — chave full produto/armazém/endereço.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSBF/MP001/01/A01-01-001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Saldo encontrado. Envelope { success, data: SaldoSBF }.

400

Produto/armazém/endereço ausentes. Tier: validation-error.

404

Saldo de endereço não localizado.

500

Erro interno.

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

Descrição

Busca o registro por RecNo(). Útil para consumers que persistem o id técnico após uma listagem.

Cenário

Query parameters

tipostring · obrigatório

Apenas recno.

recno

valorstring · obrigatório

Inteiro positivo.

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

Busca por RecNo — sempre disponível.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSBF/_byid?tipo=recno&valor=9012
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Encontrado.

400

Parâmetros inválidos.

404

RecNo inexistente / filial diferente.

500

Erro interno.

Listagem

Paginação e filtros pré-definidos

GET /WsSBF/_list Lista saldos por endereço com filtros

Descrição

Lista registros de SBF com filtros opcionais por produto, armazem, endereco, lote e somenteComSaldo.

Particularidade do índice. O índice 2 da SBF tem BF_LOCALIZ em posição não-prefixa (vem após lote/sub-lote/prior). Por isso filtro por endereço sem produto faz scan-full com check em memória.

Cenário

Query parameters

produtostring · opcionalSBF.BF_PRODUTO

Prefix-seek pelo índice 2.

armazemstring · opcionalSBF.BF_LOCAL

Match exato em BF_LOCAL.

enderecostring · opcionalSBF.BF_LOCALIZ

Match exato em BF_LOCALIZ. Sem prefixo no índice — filtra em memória.

lotestring · opcionalSBF.BF_LOTECTL

Match exato.

somenteComSaldoboolean · opcional

Filtra BF_QUANT - BF_EMPENHO > 0.

fieldsstring · opcional

CSV; 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 da página anterior.

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

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

RequestHTTP/1.1 · sem body

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

Endereços com saldo — separação WMS / inventário ativo.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSBF/_list?produto=MP001&somenteComSaldo=true
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Delta-sync — sincronização incremental para DW / cache.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSBF/_list?orderBy=recno&cursor=9012&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Página. Envelope ListResponse.

400

fields com campo fora de CAMPOS_GET.

500

Erro interno.

GET /WsSBF/porProduto/{produto} Lista endereços filtrados por produto

Descrição

Atalho — todos endereços que têm saldo do produto. Equivale a /_list?produto={produto}.

Path parameter

produtostring · obrigatório

Código do produto.

Cenário

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

Lista por produto.

RequestHTTP/1.1 · sem body

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

Respostas

200

Página.

500

Erro interno.

GET /WsSBF/porLote/{lote} Lista endereços por código de lote

Descrição

Rastreabilidade física do lote — onde fisicamente esse BF_LOTECTL está. Custo de scan-full sem produto.

Path parameter

lotestring · obrigatório

Código do lote.

Cenário

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

Rastreabilidade reversa.

RequestHTTP/1.1 · sem body

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

Respostas

200

Página.

500

Erro interno.

GET /WsSBF/porArmazem/{armazem} Lista endereços filtrados por armazém

Descrição

Inventário completo de endereços do armazém. Pesado em ambientes grandes; usar orderBy=recno.

Path parameter

armazemstring · obrigatório

Código do armazém.

Cenário

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

Inventário do armazém.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSBF/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

SaldoSBF

object

Resposta de GET /WsSBF/{produto}/{armazem}/{endereco}. Campos data e empenho são opcionais (FieldPos defensivo).

produtostringSBF.BF_PRODUTO

Código do produto.

localstringSBF.BF_LOCAL

Armazém.

enderecostringSBF.BF_LOCALIZ

Endereço WMS.

lotestringSBF.BF_LOTECTL

Lote.

subLotestringSBF.BF_NUMLOTE

Sub-lote.

seriestringSBF.BF_NUMSERI

Número de série.

quantidadenumberSBF.BF_QUANT

Quantidade no endereço.

empenhadanumberSBF.BF_EMPENHO

Empenho. Só se o campo existir.

disponivelnumber

Calculado: quantidade - empenhada.

dataValidadestring · opcionalSBF.BF_DATAVEN

YYYYMMDD.

dataInventariostring · opcionalSBF.BF_DINVENT

YYYYMMDD.

recnointeger

Id técnico (RecNo).

SaldoLinha

object

Linha retornada em listagens / /_byid. Inclui empenhada e disponivel calculados.

BF_PRODUTOstring

Produto.

BF_LOCALstring

Armazém.

BF_LOCALIZstring

Endereço.

BF_LOTECTLstring

Lote.

BF_NUMLOTEstring

Sub-lote.

BF_NUMSERIstring

Série.

BF_QUANTnumber

Quantidade.

empenhadanumber

Calculado de BF_EMPENHO.

disponivelnumber

Calculado.

recnointeger

RecNo.

ListResponse

object · envelope

Envelope padrão. page só em orderBy=chave; nextCursor só em orderBy=recno.

successboolean

true.

dataarray<SaldoLinha>

Itens.

pageinteger · opcional

Em orderBy=chave.

pageSizeinteger

Aplicado.

countinteger

Itens nesta página.

orderBystring

Modo aplicado.

chaverecno

nextCursorinteger · opcional

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.

consulta-direta

GET /WsSBF/{produto}/{armazem}/{endereco}

Saldo de um produto em um endereço específico. Lote/sub-lote/série opcionais via query. Quando usar: conferência pontual de WMS.

byid-recno

GET /WsSBF/_byid

Busca por RecNo. BF_MSUID ausente no dicionário desta base — tipo=msuid não suportado (ver Pendências).

listagem-paginada

GET /WsSBF/_list

Default orderBy=chave + page/pageSize. Filtros opcionais; endereço sem produto faz scan-full.

listagem-somente-com-saldo

GET /WsSBF/_list

Apenas endereços com BF_QUANT - BF_EMPENHO > 0. Útil para separação WMS.

delta-sync

GET /WsSBF/_list

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

por-produto

GET /WsSBF/porProduto/{produto}

Endereços que têm saldo do produto.

por-lote

GET /WsSBF/porLote/{lote}

Rastreabilidade física do lote — onde o lote está nas estantes WMS.

por-armazem

GET /WsSBF/porArmazem/{armazem}

Inventário completo de endereços do armazém.

Pendências conhecidas (rev3)

BF_MSUID ausente nesta base. Dicionário padrão TOTVS de SBF não traz BF_MSUID. _byid só aceita tipo=recno; tipo=msuid retornaria 501 se exposto. Requer UPDDISTR + nova rota para implementar a busca via MSUID.

Volumetria muito alta em SBF. Em armazéns com endereçamento granular (porta-pallet, picking, gôndola), SBF pode ter milhões de linhas (uma por produto × endereço × lote × série). PAGE_SIZE_MAX=500 evita OOM mas listagens totais exigem paginação cuidadosa por orderBy=recno + cursor. Reports analíticos: usar DW (src/dw/).

Endereço fora do prefixo do índice. O índice 2 da SBF tem BF_LOCALIZ após lote/sublote/prior — filtro por endereço sem produto faz scan-full filtrando em memória. Para consultas frequentes por endereço, considerar a criação de índice adicional BF_FILIAL+BF_LOCAL+BF_LOCALIZ (não-padrão).

Bloqueio MSBLQL/MSBLQD não aplicável. Saldo em endereço é resultado de movimentação WMS. Bloqueio de endereço (manutenção, quarentena, inventário rolando) vive em outras tabelas WMS (SBJ, etc.), fora do escopo deste endpoint.

Sem _search. Autocomplete de endereço não exposto. Quando necessário, listar por /porArmazem e filtrar no front.

Concorrência com movimento WMS. Snapshot do DbSeek; operações concorrentes (separação, acerto, transferência interna) podem alterar BF_QUANT entre a leitura e o uso pelo consumer. Para alocação crítica, ler dentro do mesmo processo do movimento.