rev1-2026-05-07 Protheus 12.1.33

SaldosIniciais

CRUD de saldos iniciais de estoque (tabela SB9) via rotina automática MATA220 encapsulada em MsExecAuto. Identificador externo é a chave composta B9_COD + B9_LOCAL (produto + armazém); como MATA220 não tem MVC público, o caminho oficial é MsExecAuto puro embrulhado em U_MT220Exc.

Bloqueio TOTVS: tabela SB9 — saldo inicial, sem MSBLQL.

Base URL https://erpapi.jetme.com.br/api/99/01 Empresa 99 · Filial 01

Convenções

Chave externa composta. Todas as rotas /WsSB9/{produto}/{local} exigem os dois segmentos (produto + armazém). A chave é lida pelos dois últimos segmentos de aURLParms — penúltimo é B9_COD, último é B9_LOCAL. Campos omitidos no path retornam 400.

Whitelist de payload. POST/PUT aceitam apenas os campos de CAMPOS_ALLOW: B9_QINI, B9_VINI1..5, B9_DATA, B9_LOTECTL, B9_NUMLOTE, B9_DTVALID. B9_COD e B9_LOCAL vêm sempre do path — se enviados no body são ignorados silenciosamente.

Formato de datas. B9_DATA e B9_DTVALID usam string AAAAMMDD (ex: "20260507"). Não é ISO YYYY-MM-DD; o MsExecAuto do MATA220 espera o formato compactado.

Tipagem do payload. Quantidades e valores (B9_QINI, B9_VINI1..5) viajam como número no JSON; o wrapper preserva o tipo numérico no array do MsExecAuto. No GET, são retornados como string via cValToChar — clientes que consomem o GET devem fazer parseFloat antes de exibir.

Listagem e paginação. /_list usa page/pageSize (default 50, máx 500). Aceita filtros opcionais cod (prefix de B9_COD) e loc (prefix de B9_LOCAL, válido somente quando cod também é informado).

Lote (B9_LOTECTL) fora da chave. Na revisão rev1, o lote é aceito no payload mas não compõe o path. Endpoints filhos com rastro ativo (produto controlado por lote) devem usar a mesma combinação B9_COD + B9_LOCAL e diferenciar pelo conteúdo do B9_LOTECTL. Expansão do path para incluir o lote ficou fora do escopo desta revisão.

SaldoInicial

CRUD por (B9_COD, B9_LOCAL)

GET /WsSB9/{produto}/{local} Consulta saldo inicial por chave composta

Descrição

Retorna o saldo inicial pesquisado pela chave composta B9_COD + B9_LOCAL. Aplica filtro de filial (xFilial("SB9")) e respeita o whitelist CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto de campos retornados.

Path parameters

produto string · path · obrigatório SB9.B9_COD

Código do produto (tamanho conforme TamSx3("B9_COD"), geralmente 15).

local string · path · obrigatório SB9.B9_LOCAL

Código do armazém (2 caracteres, deve existir em SBE).

Query parameters

fields string · query · opcional

Lista de campos separados por vírgula. Validados contra CAMPOS_GET; campo não permitido devolve 400.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · com fieldsHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01?fields=B9_COD,B9_LOCAL,B9_QINI,B9_VINI1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

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

400

Produto ou armazém vazio / fora do tamanho de TamSx3. Tier: validation-error.

404

Saldo inicial inexistente para o par produto/armazém. Tier: not-found.

500

Erro interno (DbSeek, serialização). Tier: business-error.

POST /WsSB9/{produto}/{local} Inclui saldo inicial (MATA220 modo 3)

Descrição

Inclui um saldo inicial via MATA220 em modo 3 (inclusão). Antes da execução, o endpoint faz DbSeek defensivo para impedir reinclusão: se a combinação já existe, retorna 409.

B9_COD e B9_LOCAL vêm do path; o payload só carrega quantidade, valor e atributos opcionais.
Whitelist completa em SaldoPayload.
Pré-requisito: produto existe em SB1 e armazém existe em SBE.

Path parameters

produto string · path · obrigatório SB9.B9_COD

Código do produto.

local string · path · obrigatório SB9.B9_LOCAL

Código do armazém.

Request body

application/json SaldoPayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em SaldoPayload.

Saldo inicial mínimo — quantidade + valor unitário moeda 1 + data. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B9_QINI": 30,
  "B9_VINI1": 1500.00,
  "B9_DATA": "20260507"
}

Saldo inicial com lote e validade — produto rastreado por lote (B1_RASTRO="L"). B9_LOTECTL é aceito no payload; B9_DTVALID usa AAAAMMDD.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B9_QINI": 120,
  "B9_VINI1": 8400.50,
  "B9_DATA": "20260507",
  "B9_LOTECTL": "LOTE_2026A",
  "B9_NUMLOTE": "001",
  "B9_DTVALID": "20271231"
}

Respostas

201

Saldo incluído. Envelope CrudResponse com data contendo a chave composta gravada (B9_COD/B9_LOCAL).

400

Produto/armazém fora do tamanho de TamSx3 ou body JSON vazio/ausente. Tier: validation-error.

409

Já existe saldo inicial para esse produto/armazém — endpoint não sobrescreve, use PUT. Tier: business-error.

422

Payload rejeitado por MATA220 (produto inexistente em SB1, armazém inexistente em SBE, data fora de domínio, etc). Tier: business-error.

500

Erro interno.

PUT /WsSB9/{produto}/{local} Altera saldo inicial existente (MATA220 modo 4)

Descrição

Altera campos do saldo inicial via MATA220 em modo 4 (alteração). Antes da execução, o endpoint posiciona a tabela SB9 com DbSeek no par B9_COD/B9_LOCAL — sem isso o MsExecAuto rejeita.

Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW.
Não há semântica de bloqueio na SB9 — o cadastro de saldos iniciais é técnico, não administrativo.

Path parameters

produto string · path · obrigatório SB9.B9_COD

Código do produto.

local string · path · obrigatório SB9.B9_LOCAL

Código do armazém.

Request body

application/json SaldoPayload · obrigatório

Subconjunto do whitelist CAMPOS_ALLOW. Campos omitidos preservam o valor atual.

Ajuste de quantidade e valor — caso mais comum. Fixture: fixtures/update.json.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B9_QINI": 50,
  "B9_VINI1": 2750.50,
  "B9_DATA": "20260507"
}

Ajuste com moedas adicionais — alimenta B9_VINI2..5 em ambientes com mais de uma moeda de custo. Apenas B9_VINI1 volta no GET default; moedas adicionais ficam gravadas na tabela mas precisam ser pedidas explicitamente no fields caso o endpoint as exponha futuramente.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B9_VINI1": 2800.00,
  "B9_VINI2": 560.00,
  "B9_VINI3": 3200.00
}

Respostas

200

Saldo alterado. Envelope CrudResponse.

400

Produto/armazém fora do tamanho ou body JSON inválido. Tier: validation-error.

404

Saldo inexistente para o par produto/armazém. Tier: not-found.

422

Validação do MsExecAuto (campos fora do whitelist, valores fora de domínio). Tier: business-error.

500

Erro interno.

DEL /WsSB9/{produto}/{local} Exclui saldo inicial (MATA220 modo 5)

Descrição

Exclui o saldo inicial via MATA220 em modo 5 (exclusão). O endpoint posiciona a tabela com DbSeek antes da chamada e devolve 404 se a chave não existir.

Atenção operacional. Exclusão de saldo inicial em produção pode invalidar o cálculo de custo médio histórico — use com cautela. Em ambientes de homologação, o cleanup pelo smoke test é seguro.

Path parameters

produto string · path · obrigatório SB9.B9_COD

Código do produto.

local string · path · obrigatório SB9.B9_LOCAL

Código do armazém.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSB9/ZZ_TEST_001/01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Saldo excluído. Envelope CrudResponse com mensagem editorial.

400

Produto/armazém fora do tamanho. Tier: validation-error.

404

Saldo inexistente. Tier: not-found.

422

MATA220 rejeitou a exclusão (existem movimentos posteriores, regra interna). Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada e typeahead

GET /WsSB9/_list Lista saldos iniciais com filtros e paginação

Descrição

Lista saldos iniciais com filtros opcionais por cod (prefix de B9_COD) e loc (prefix de B9_LOCAL, válido somente quando cod também é informado). Usa o índice 1 (B9_FILIAL + B9_COD + B9_LOCAL) e paginação por page/pageSize.

Sem filtro: percorre toda a SB9 a partir do início — use pageSize baixo.
Com cod e loc: cod aplica via seek/exit; loc filtra na varredura.

Query parameters

cod string · query · opcional SB9.B9_COD

Prefix de B9_COD (índice 1).

loc string · query · opcional SB9.B9_LOCAL

Prefix de B9_LOCAL. Só faz sentido com cod informado.

fields string · query · opcional

Lista de campos validados contra CAMPOS_GET.

page integer · query · opcional

Página (default 1, mínimo 1).

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

Chamada de exemplo

Request · sem filtroHTTP/1.1 · sem body

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

Request · filtrando por produto e armazémHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB9/_list?cod=ZZ_TEST&loc=01&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de saldos. Envelope com data (array de Saldo), page, pageSize, count.

400

Parâmetro inválido (ex: campo fora do whitelist em fields).

500

Erro interno.

GET /WsSB9/_search Typeahead por B9_COD (prefix)

Descrição

Busca rápida (typeahead) por prefix de B9_COD para autocomplete de UI. Retorna uma lista enxuta (cod, local, qini) — não devolve o schema completo de Saldo. Tem limite de varredura interno (SEARCH_SCAN_CAP = 2000) para impedir degradação em buckets grandes.

Query parameters

q string · query · obrigatório

Prefix de B9_COD. Mínimo 2 caracteres.

limit integer · query · opcional

Quantidade máxima (default 10, máx 25).

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB9/_search?q=ZZ&limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista enxuta. Envelope: success, count, data[] com cod/local/qini.

400

q ausente ou < 2 caracteres.

500

Erro interno.

Schemas

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

Saldo

object

Representação retornada nos GETs (/{produto}/{local} e /_list). Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields. Valores numéricos vêm serializados como string (cValToChar).

B9_CODstring · opcionalSB9.B9_COD

Código do produto (parte 1 da chave).

B9_LOCALstring · opcionalSB9.B9_LOCAL

Código do armazém (parte 2 da chave).

B9_QINIstring · opcionalSB9.B9_QINI

Quantidade inicial, serializada via cValToChar.

B9_VINI1string · opcionalSB9.B9_VINI1

Valor inicial em moeda 1, serializado via cValToChar.

B9_DATAstring · opcionalSB9.B9_DATA

Data do saldo inicial, formato AAAAMMDD.

B9_LOTECTLstring · opcionalSB9.B9_LOTECTL

Lote (rastro), quando o produto é controlado por lote.

B9_NUMLOTEstring · opcionalSB9.B9_NUMLOTE

Sublote do controle de rastro.

B9_DTVALIDstring · opcionalSB9.B9_DTVALID

Data de validade do lote, formato AAAAMMDD.

SaldoPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. Os campos de chave (B9_COD, B9_LOCAL) vêm do path e são ignorados se vierem no body. Valores monetários e quantidades viajam como número JSON; datas como string AAAAMMDD.

B9_QINInumber · opcionalSB9.B9_QINI

Quantidade inicial em estoque.

B9_VINI1number · opcionalSB9.B9_VINI1

Valor inicial em moeda 1 (moeda padrão da empresa).

B9_VINI2number · opcionalSB9.B9_VINI2

Valor inicial em moeda 2 (quando aplicável).

B9_VINI3number · opcionalSB9.B9_VINI3

Valor inicial em moeda 3.

B9_VINI4number · opcionalSB9.B9_VINI4

Valor inicial em moeda 4.

B9_VINI5number · opcionalSB9.B9_VINI5

Valor inicial em moeda 5.

B9_DATAstring · opcionalSB9.B9_DATA

Data do saldo inicial. Formato AAAAMMDD (ex: "20260507").

B9_LOTECTLstring · opcionalSB9.B9_LOTECTL

Lote (rastro). Obrigatório se o produto tem B1_RASTRO="L".

B9_NUMLOTEstring · opcionalSB9.B9_NUMLOTE

Sublote.

B9_DTVALIDstring · opcionalSB9.B9_DTVALID

Data de validade do lote. Formato AAAAMMDD.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave composta gravada (POST/PUT) ou string vazia (DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso (ex: "Saldo inicial incluido com sucesso.").

datastring | object · opcional

Em POST/PUT, contém objeto com B9_COD + B9_LOCAL + opcionalmente B9_QINI. Em DELETE, string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: log do NomeAutoLog do MATA220) para tratamento programático, quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final).

datastring · opcional

Token interno / detalhe técnico (ex: log do MsExecAuto do MATA220).