rev4-2026-05-14 Protheus 12.1.33 (build 240223P) Empresa 99 · Filial 01

Endereco

CRUD completo + consultas sobre endereços de estoque (tabela SBE). POST e DELETE passam pelo MATA015 (MsExecAuto); PUT trata exclusivamente bloqueio administrativo (BE_MSBLQL/BE_MSBLQD) via RecLock. GET é um dispatcher: por chave composta, listagem paginada por armazém, busca textual na descrição e consulta por id interno.

Vinculação com o ERP

Tabela mestre SBE Endereços de estoque

Rotina automática MATA015 TDN pageId=6087467

Wrapper AdvPL U_MT015Exc src/lib/MAT/MT015EXC.prw

Operações & modos

POST Op=3 · inclusão PUT RecLock direto DEL Op=5 · exclusão GET consulta direta SBE/SQL

Dependências de ambiente

Parâmetro · obrigatório

MV_LOCALIZ

controle de endereçamento físico ativo · valor esperado "S"
MATA015 rejeita com 422 quando desligado

Cadastro · pré-requisito

Armazém (NNR)

tabela NNR · NNR_CODIGO = BE_LOCAL
inclua via LocalEstoque antes

Padrão · bloqueio TOTVS

BE_MSBLQL / BE_MSBLQD

combobox pertence("12") (1=bloq, 2=ativo) + data ISO
helper U_C980Blq("SBE") em src/lib/CRM/CRM980EXC.prw

Integração

WMS / Logística

campos físicos (BE_ALTURLC/LARGLC/COMPRLC/CAPACID) alimentam alocação WMS quando SIGAWMS ativo

Convenções

Chave externa composta. O endereço é identificado pelo par BE_LOCAL (armazém, 2 chars) + BE_LOCALIZ (código, até 15 chars). No POST ambos vão no body (Armazem + Endereco). Em PUT/DELETE/GET-chave, o BE_LOCALIZ vai no path e BE_LOCAL vai como header HTTP local (mapeado para o WSDATA homônimo).

Filial fixa pela URL. /api/99/01 seta empresa 99 e filial 01 automaticamente. Não envie Filial no body do POST — o nome conflita com o WSDATA filial declarado no WSRESTFUL (case-insensitive shadow no build 240223P; ver ERROS.md#E13) e é ignorado.

Bloqueio TOTVS — gate de PUT. Em registro bloqueado (BE_MSBLQL="1" ou dDataBase > BE_MSBLQD), qualquer campo no payload PUT que não seja BE_MSBLQL ou BE_MSBLQD retorna 422 (caminho de desbloqueio). Desbloqueie primeiro setando BE_MSBLQL="2".

Defaults aplicados pelo endpoint. No POST, campos opcionais omitidos viram: Capacidade=0, Prioridade="ZZZ", Altura/Largura/Comprimento/Perda=0, Status="1".

Fixtures sentinela. Smoke usa Armazem="01", Endereco="TSTEND01", sufixo _TEST_ na descrição. Trap DELETE no test-endereco.sh limpa em caso de falha.

Endereco

CRUD + consultas sobre endereços físicos (SBE) com bloqueio TOTVS

POST /WsSBE/INCLUIR/{localiz} Cria endereço de estoque

Descrição

Inclui um endereço físico via MATA015 Op=3. O {localiz} no path é apenas o gatilho da WSSYNTAX (build 240223P exige {param} dinâmico — ver ERROS.md#E12/wssyntax-self); o valor efetivo vem do campo Endereco no body.

Cenários cobertos: cen-1 (POST mínimo).

Path parameter

localizstring · path · obrigatório

Gatilho da WSSYNTAX. Deve coincidir com Endereco do body. Até 15 chars.

Request body

application/jsonEnderecoRequest · obrigatório

Schema em EnderecoRequest.

Request · cen-1 (POST mínimo)HTTP/1.1

POST https://erpapi.jetme.com.br/api/99/01/WsSBE/INCLUIR/TSTEND01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json

{
  "Armazem": "01",
  "Endereco": "TSTEND01",
  "Descricao": "Doca de descarga DOCA-01",
  "Capacidade": 100,
  "Prioridade": "AAA",
  "Status": "1"
}

Respostas

201

Endereço criado. Envelope com data.armazem+data.endereco.

400

Body ausente/malformado ou campo obrigatório ausente.

422

MATA015 rejeitou (MV_LOCALIZ desligado, NNR ausente, endereço já existe).

500

Exceção não tratada.

PUT /WsSBE/ALTERAR/{localiz} Bloqueio / desbloqueio

Descrição

Atualiza somente o par de bloqueio TOTVS (BE_MSBLQL e/ou BE_MSBLQD). Não passa pelo MATA015: é RecLock direto na SBE — campos administrativos fora do escopo do MVC.

Gate de bloqueio: em registro já bloqueado, qualquer campo fora do par retorna 422. Desbloqueie primeiro com BE_MSBLQL="2".

Cenários cobertos: cen-6 (bloqueio normal), cen-7 (gate bloqueado), cen-8 (bloqueio por data), cen-9 (desbloqueio total).

Path & Headers

localizstring · path · obrigatórioSBE.BE_LOCALIZ

Código do endereço a alterar.

localstring · header · obrigatórioSBE.BE_LOCAL

Armazém do endereço.

Request body

application/jsonBloqueioRequest · obrigatório

Schema em BloqueioRequest.

Bloqueio normal. Trava o endereço por flag — independente da data base.

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSBE/ALTERAR/TSTEND01
Authorization: Bearer …
Content-Type: application/json
local: 01

{ "BE_MSBLQL": "1" }

Bloqueio por data. Aceita ISO YYYY-MM-DD; o endpoint converte para Date do AdvPL via sToD(StrTran(v,"-","")).

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSBE/ALTERAR/TSTEND01
Authorization: Bearer …
local: 01

{ "BE_MSBLQD": "2026-12-31" }

Desbloqueio total. Limpa flag e data num único PUT.

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSBE/ALTERAR/TSTEND01
Authorization: Bearer …
local: 01

{ "BE_MSBLQL": "2", "BE_MSBLQD": "" }

Respostas

200

Aplicado. data.bloqueio_flag/data.bloqueio_data ecoam estado final.

400

Header local ausente, body inválido ou nenhum dos campos de bloqueio no payload.

404

Endereço não localizado.

422

Registro bloqueado e payload tenta alterar outros campos; OU BE_MSBLQL fora de "12"; OU BE_MSBLQD com data ISO inválida.

500

Exceção não tratada.

DEL /WsSBE/{localiz} Exclui endereço de estoque

Descrição

Exclui via MATA015 Op=5. Header local (armazém) obrigatório. Endereço com saldo (SBF>0) é rejeitado pelo MATA015 → 422.

Cenários cobertos: cen-10 (DELETE OK), cen-11 (404 negativo).

Path & Headers

localizstring · path · obrigatórioSBE.BE_LOCALIZ

Código do endereço a excluir.

localstring · header · obrigatórioSBE.BE_LOCAL

Armazém do endereço (WSDATA local).

Chamada de exemplo

Request · cen-10HTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSBE/TSTEND01
Authorization: Bearer …
local: 01

Respostas

200

Excluído com sucesso.

400

Header local ausente.

404

Endereço não localizado.

422

MATA015 rejeitou (saldo em estoque, MV_LOCALIZ).

500

Exceção não tratada.

GET /WsSBE/{localiz} Consulta por chave (armazém + endereço)

Descrição

Retorna 1 registro via DbSeek na chave composta BE_FILIAL+BE_LOCAL+BE_LOCALIZ. Resposta inclui BE_MSBLQL/BE_MSBLQD — admin consulta estado de bloqueio sem precisar de PUT exploratório.

Cenário coberto: cen-2 (GET por chave).

Path & Headers

localizstring · path · obrigatório

Código do endereço.

localstring · header · obrigatório

Armazém.

Chamada de exemplo

Request · cen-2HTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsSBE/TSTEND01
Authorization: Bearer …
local: 01

Respostas

200

EnderecoFull com todos os campos.

400

Header local ausente.

404

Endereço não localizado.

500

Exceção.

GET /WsSBE/_list Listagem paginada por armazém

Descrição

Lista endereços com paginação, ordenados por BE_LOCAL+BE_LOCALIZ. Use local (query) para filtrar pelo armazém e cod para prefixo do código (LIKE cod%). Campo count traz total de registros que atendem o filtro (independente da página).

Cenário coberto: cen-3 (_list paginado).

Query parameters

localstring · opcional

Filtra por armazém (BE_LOCAL).

codstring · opcional

Prefixo do código (BE_LOCALIZ LIKE cod%).

pageinteger · default 1

Página (1-indexed).

pageSizeinteger · default 50, max 500

Tamanho da página.

Chamada de exemplo

Request · cen-3HTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsSBE/_list?local=01&pageSize=5
Authorization: Bearer …

Respostas

200

RespostaListagem com data, page, pageSize, count, filters.

500

Exceção (TopConnect / query).

GET /WsSBE/_search Busca por trecho da descrição

Descrição

Faz LIKE '%q%' case-insensitive em BE_DESCRIC. Resultado enxuto (3 campos: armazem, endereco, descricao) — pensado para autocomplete em UI. limit default 10, max 25.

Cenário coberto: cen-4 (_search).

Query parameters

qstring · obrigatório

Texto buscado em BE_DESCRIC.

localstring · opcional

Restringe ao armazém.

limitinteger · default 10, max 25

Quantidade máxima.

Chamada de exemplo

Request · cen-4HTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsSBE/_search?q=DOCA&local=01
Authorization: Bearer …

Respostas

200

Lista enxuta. count reflete tamanho do data.

400

q ausente.

500

Exceção.

GET /WsSBE/_byid Consulta por id interno (recno / msuid)

Descrição

Acesso direto via recno (R_E_C_N_O_) ou msuid (BE_MSUID). Útil em delta-sync ou quando outro endpoint retornou o id e você quer evitar o seek por chave.

Cenário coberto: cen-5 (_byid recno).

Query parameters

tipostring · obrigatório

Enum: recno ou msuid.

valorstring · obrigatório

Valor do id.

Chamada de exemplo

Request · cen-5HTTP/1.1

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

Respostas

200

EnderecoFull.

400

tipo/valor ausente ou tipo fora do enum.

404

Id não localizado.

500

Exceção.

Cenários

11 cenários cobertos por test-endereco.sh · all green em rev4-2026-05-14

cen-1 · POST cria endereço (201). Cria TSTEND01 no armazém 01. Body com Armazem, Endereco, Descricao e demais opcionais. → POST

cen-2 · GET por chave (200). Lê /WsSBE/TSTEND01 com header local: 01. Retorna EnderecoFull com BE_MSBLQL/BE_MSBLQD expostos. → GET por chave

cen-3 · GET _list paginado (200). ?local=01&pageSize=5. Retorna data[] + page/pageSize/count/filters. → GET _list

cen-4 · GET _search por descrição (200). ?q=TESTE&local=01. LIKE case-insensitive em BE_DESCRIC. → GET _search

cen-5 · GET _byid por recno (200). Recno extraído do _list + consulta direta. → GET _byid

cen-6 · PUT bloqueio normal (200). {BE_MSBLQL:"1"} trava o endereço por flag (independe de data). → PUT

cen-7 · PUT em bloqueado tenta outro campo (422). Após cen-6, payload com BE_DESCRIC retorna 422. Gate força desbloqueio explícito antes de qualquer update administrativo. → PUT

cen-8 · PUT bloqueio por data (200). {BE_MSBLQD:"2026-12-31"}. A partir dessa data, U_C980Blq retorna bloqueado. → PUT

cen-9 · PUT desbloqueio total (200). {BE_MSBLQL:"2", BE_MSBLQD:""} num único PUT limpa flag e data. → PUT

cen-10 · DELETE remove (200). DELETE /WsSBE/TSTEND01 com header local: 01. → DELETE

cen-11 · DELETE inexistente (404). Cenário negativo: ZZZZZZZZ não existe → resposta de erro estruturada. → DELETE

Schemas

Definições canônicas dos payloads/respostas

EnderecoRequest

object

Payload de criação (POST). Não envie Filial — conflita com WSDATA (E13 do ERROS.md).

Armazemstring · obrigatórioSBE.BE_LOCAL

Armazém (NNR). 2 chars.

Enderecostring · obrigatórioSBE.BE_LOCALIZ

Código (até 15 chars). Único por BE_FILIAL+BE_LOCAL+BE_LOCALIZ.

Descricaostring · obrigatórioSBE.BE_DESCRIC

Descrição (até 30 chars).

Capacidadenumber · default 0SBE.BE_CAPACID

Capacidade absoluta.

Prioridadestring · default "ZZZ"SBE.BE_PRIOR

Prioridade lexicográfica (3 chars).

Alturanumber · default 0SBE.BE_ALTURLC

Altura (cm).

Larguranumber · default 0SBE.BE_LARGLC

Largura (cm).

Comprimentonumber · default 0SBE.BE_COMPRLC

Comprimento (cm).

Perdanumber · default 0SBE.BE_PERDA

Perda (%).

Statusstring · default "1"SBE.BE_STATUS

1=ativo, 2=inativo.

BloqueioRequest

object

Payload de bloqueio/desbloqueio (PUT). Pelo menos um dos campos é obrigatório. Em registro já bloqueado, somente estes 2 são aceitos.

BE_MSBLQLstring · enum "1"|"2"SBE.BE_MSBLQL

"1" = bloqueia, "2" = libera. Valor fora do enum → 422.

BE_MSBLQDstring · ISO YYYY-MM-DD ou ""SBE.BE_MSBLQD

Data a partir da qual bloqueio passa a valer. String vazia limpa a data.

EnderecoFull

object

Endereço completo (resposta GET por chave / _byid). Campos com prefixo BE_ ecoam o nome do dicionário SX3.

BE_LOCALstring

Armazém.

BE_LOCALIZstring

Código do endereço.

BE_DESCRICstring

Descrição.

BE_CAPACIDnumber

Capacidade.

BE_PRIORstring

Prioridade.

BE_ALTURLC / BE_LARGLC / BE_COMPRLC / BE_PERDAnumber

Métricas físicas.

BE_STATUSstring

1=ativo, 2=inativo.

BE_MSBLQLstring

1=bloqueado, 2=ativo (padrão TOTVS).

BE_MSBLQDstring

Data ISO ou string vazia.

EnderecoResumo

object

Linha enxuta de listagem (chaves em snake_case, não BE_*).

armazem / endereco / descricaostring

Identificação e label.

capacidade / prioridade / statusmixed

Atributos de consumo.

bloqueio_flag / bloqueio_datastring

Estado de bloqueio TOTVS — útil para UI listar apenas registros ativos.

recnointeger

Identificador interno; serve de chave em _byid.

RespostaListagem

object · envelope

Envelope de _list e _search.

success / messagebool / string

Status & mensagem editorial.

dataarray<EnderecoResumo>

Linhas da página.

page / pageSize / countinteger

Paginação. count = total filtrado.

orderBystring

Ordenação aplicada ("armazem,endereco").

filtersarray<string>

Filtros efetivamente aplicados ("armazem=01").

RespostaErro

object · envelope

Envelope padrão de erros 4xx/5xx.

successboolean · const false

Sempre false.

messagestring

Mensagem editorial.

datastring | object

Detalhe técnico opcional.

Pendências conhecidas

Limitações, melhorias previstas, gaps de cobertura

Auth pendente em PUT/GET. O BE_USERLGI/BE_USERLGA (logs de inclusão/alteração) não estão sendo populados — o RecLock do PUT só mexe nos campos de bloqueio. Considerar adicionar BE_USERLGA := UsrRetName(__cUserID) quando padrão de auditoria for definido.

Filtro por estado de bloqueio. _list ainda não expõe ?somenteAtivos=1 nem ?bloqueio=1|2. Cliente que quer só endereços disponíveis precisa filtrar do lado dele via bloqueio_flag.

_search só na descrição. Não busca em BE_LOCALIZ (use _list?cod=... para prefixo de código). Avaliar união após métricas de uso.

Validação de domínio do Status. POST aceita "1" ou "2" sem rejeitar outros valores; MATA015 normalmente rejeita, mas pode haver janela onde grava lixo (gatilho/X3 customizado). Plano: adicionar fValDom antes do MsExecAuto (frente FEAT-fValDom-status-sbe).