rev1-2026-05-03 Protheus 12.1.33

Enderecamento

Execucao de Enderecamento (putaway) via rotina automatica MATA265 e consulta de movimentos SDB resultantes. Substitui a User Function legada U_GAIZ265 (_incorporar/Execauto/GAIZ_MATA265.prw). Enderecamento e acao irreversivel pelo proprio MATA265 — consome saldo SDA, gera SDB e atualiza SBF. Por isso este endpoint expoe apenas POST de execucao e GETs read-only; nao ha PUT/DELETE. Para desfazer, rodar estorno via MATA266 em endpoint dedicado (roadmap).

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

Vinculacao com o ERP

Tabela mestre SDB Movimentos de enderecamento

Rotina automatica MATA265 MSExecAuto - modo 3

Wrapper AdvPL U_MT265Exc src/lib/MAT/MT265EXC.prw

Operacoes & modos

POST modo 3 sem PUT/DELETE

Dependencias de ambiente

Cadastro

Produto

tabela SB1 - nao bloqueado; parametro B5_LOCALIZ = "S" no produto (controla se exige enderecamento - confirmar parametrizacao da empresa)

Movimento pendente

Pendencia SDA

chave DA_FILIAL+DA_PRODUTO+DA_LOCAL+DA_DOC com DA_SALDO >= qtd — consumida pelo MATA265 na execucao

Cadastro

Endereco

endereco SBF cadastrado para o DB_LOCAL; DB_LOCALIZ é validado contra SBF

Sequenciamento

Numeracao DB_ITEM

calculado por Soma1 do maior DB_ITEM existente para a chave produto+doc

Convencoes

Bloqueio administrativo (MSBLQL/MSBLQD) nao se aplica a SDB. SDB é tabela de movimento (linhas de enderecamento ja efetivado) e nao possui DB_MSBLQL/DB_MSBLQD no dicionario. O bloqueio relevante para este fluxo esta nos cadastros consumidos: Produto (SB1) - pre-check de B1_MSBLQL="1" no POST retorna 422 antes do MATA265; Endereco (SBE) - bloqueio gerenciado pelo endpoint Endereco. O padrao Onda 6 (PUT condicional ao estado de bloqueio) nao aplica aqui porque WsEnderecamento nao expoe PUT/DELETE.

Acao irreversivel. O POST executa enderecamento real: consome saldo SDA, gera linha em SDB, atualiza SBF. Nao existe PUT/DELETE neste endpoint. Para desfazer, rodar estorno via MATA266 em endpoint dedicado (roadmap).

Documento é obrigatorio. O cliente envia doc especifico (mesmo do DA_DOC origem), casando exatamente com uma pendencia em SDA. Sem doc, o endpoint retorna 422 antes de chamar o MATA265.

Cardinalidade. Esta versao mantem 1 item por POST (paridade com o legado U_GAIZ265). O MATA265 aceita N itens; a expansao multi-item esta no roadmap.

Id externo opcional. O campo idExterno do payload é apenas ecoado na resposta — nao é persistido em SDB (nao depende de campos customizados x_*). Para gravar, depende de UPDDISTR com DB_X_IDEXT na empresa (roadmap).

Paginacao e delta-sync. /_list usa page/pageSize (default 50, max 500) no modo orderBy=chave (agrupa por documento). Para sincronizacao incremental linha-a-linha, use orderBy=recno com since/cursor e o nextCursor retornado.

Enderecamento

Execucao MATA265 + consultas SDB

POST /WsEnderecamento Executa enderecamento (MATA265 modo 3)

Descricao

Executa enderecamento real consumindo uma pendencia da SDA e gerando linha em SDB via MATA265 modo 3. O servidor calcula o proximo DB_ITEM via Soma1 do maior existente para a chave produto+doc.

Pre-requisito: existe SDA com DA_DOC=doc, DA_PRODUTO=produto, DA_LOCAL=local, DA_SALDO >= qtd.
Pre-requisito: SBF com o endereco cadastrado no local.
Whitelist do payload: ver EnderecamentoPayload.

Request body

application/json EnderecamentoPayload - obrigatorio

Payload plano. Schema completo em EnderecamentoPayload.

Payload minimo — somente os obrigatorios. Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 - application/json

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

{
  "produto": "PA001",
  "local": "01",
  "doc": "999998",
  "endereco": "END01",
  "qtd": 1.0
}

Com id externo e data explicita — o idExterno é ecoado na resposta (nao gravado); dataReg sobreescreve a data atual.

RequestHTTP/1.1 - application/json

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

{
  "produto": "PA001",
  "local": "01",
  "doc": "999998",
  "endereco": "END01",
  "qtd": 2.5,
  "dataReg": "20260503",
  "idExterno": "WMS-123456"
}

Respostas

201

Enderecamento realizado. Envelope ExecResponse com data.item = DB_ITEM gerado.

400

Payload malformado (JSON invalido, campo de tipo errado). Tier: validation-error.

422

Campo obrigatorio ausente, produto bloqueado, pendencia SDA inexistente, saldo insuficiente, endereco SBF inexistente, ou rejeicao do MsExecAuto do MATA265. Tier: business-error.

500

Erro interno (deserializacao, runtime do MATA265). Tier: business-error.

GET /WsEnderecamento/{doc} Consulta linhas SDB do documento

Descricao

Retorna todas as linhas SDB do documento informado (mesmo DA_DOC origem). Aplica filtro de filial (xFilial("SDB")) via indice 2 da SDB (DB_FILIAL+DB_DOC+...). Cada linha inclui os ids tecnicos opcionais (recno, msuid, msuidt) quando o dicionario tem esses campos.

Path parameter

doc string - path - obrigatorio SDB.DB_DOC

Documento de enderecamento (mesmo do DA_DOC origem).

Chamada de exemplo

RequestHTTP/1.1 - sem body

GET https://erpapi.jetme.com.br/api/99/01/WsEnderecamento/999998
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Respostas

200

Documento encontrado. Envelope com data.filial, data.doc, data.count e data.linhas[] (array de Linha).

400

Documento ausente. Tier: validation-error.

404

Nenhuma linha SDB encontrada para o documento na filial corrente. Tier: not-found.

GET /WsEnderecamento/_list Lista documentos com filtros e paginacao

Descricao

Lista movimentos de enderecamento com dois modos de ordenacao:

orderBy=chave (default) — agrupa por documento, indice 2 da SDB; paginacao por page/pageSize. Cada item da resposta é um documento distinto.
orderBy=recno — delta-sync linha-a-linha; usa since/cursor com nextCursor retornado.

Filtros: filial, doc, produto, data (formato YYYYMMDD).

Query parameters

filialstring - query - opcionalSDB.DB_FILIAL

Filial. Default = xFilial("SDB").

docstring - query - opcionalSDB.DB_DOC

Documento exato.

produtostring - query - opcionalSDB.DB_PRODUTO

Produto exato.

datastring - query - opcionalSDB.DB_DATA

Data exata. Pattern: ^\d{8}$ (YYYYMMDD).

pageinteger - query - opcional

Pagina (default 1, minimo 1). Valido com orderBy=chave.

pageSizeinteger - query - opcional

Tamanho da pagina (default 50, max 500).

orderBystring - query - opcional

Modo de ordenacao. Default chave.

chaverecno

sinceinteger - query - opcional

Inicio do delta-sync (valido com orderBy=recno).

cursorinteger - query - opcional

Cursor retornado em nextCursor de pagina anterior.

Chamada de exemplo

Request - paginacao por chaveHTTP/1.1 - sem body

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

Request - delta-sync por recnoHTTP/1.1 - sem body

GET https://erpapi.jetme.com.br/api/99/01/WsEnderecamento/_list?orderBy=recno&since=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Respostas

200

Pagina. Envelope com data[] (array de ListItem), orderBy, pageSize, count; page em modo chave ou nextCursor em modo recno.

GET /WsEnderecamento/_byid Consulta linha SDB por id tecnico (recno|msuid)

Descricao

Busca uma linha SDB por id tecnico — recno (RecNo da SDB) ou msuid (identificador universal MS_UID, quando o dicionario tem DB_MSUID). Util para integracoes que persistem o id tecnico da linha de enderecamento.

Query parameters

tipo string - query - obrigatorio

Indica qual id tecnico esta sendo usado.

recnomsuid

valor string - query - obrigatorio

Valor do id (inteiro quando tipo=recno, string quando tipo=msuid).

Chamada de exemplo

Request - por recnoHTTP/1.1 - sem body

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

Request - por msuidHTTP/1.1 - sem body

GET https://erpapi.jetme.com.br/api/99/01/WsEnderecamento/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Respostas

200

Linha encontrada. Envelope { success: true, data: Linha }.

400

Parametros tipo/valor ausentes ou tipo fora do enum. Tier: validation-error.

404

Linha nao localizada. Tier: not-found.

501

Busca por msuid requer DB_MSUID no dicionario - nao disponivel neste ambiente.

Schemas

Definicoes canonicas - campos com origem SX3 rastreavel

EnderecamentoPayload

object

Payload do POST /WsEnderecamento. Os 5 primeiros campos sao obrigatorios. idExterno é apenas ecoado na resposta (nao persistido em SDB).

produtostring - obrigatorioSB1.B1_COD

Produto a enderecar (precisa existir em SB1 e nao estar bloqueado).

localstring - obrigatorioSDA.DA_LOCAL / SDB.DB_LOCAL

Codigo de armazem/local.

docstring - obrigatorioSDA.DA_DOC

Documento do registro pendente em SDA a ser consumido.

enderecostring - obrigatorioSDB.DB_LOCALIZ

Endereco fisico (precisa estar cadastrado em SBF).

qtdnumber - obrigatorioSDB.DB_QUANT

Quantidade a enderecar; deve ser > 0 e <= DA_SALDO da pendencia.

dataRegstring - opcionalSDB.DB_DATA

Data do movimento. Formato YYYYMMDD. Default: data atual.

idExternostring - opcional

Id externo de rastreio (WMS, ZOH, etc). Apenas ecoado na resposta - nao gravado em SDB.

Linha

object

Representacao de uma linha SDB retornada em /{doc} e /_byid. Campos efetivamente retornados dependem de CAMPOS_GET_LIN no .prw. Ids tecnicos (recno, msuid, msuidt) vem do bloco TecnicoIds.

DB_FILIALstring - opcionalSDB.DB_FILIAL

Filial do movimento.

DB_DOCstring - opcionalSDB.DB_DOC

Documento de enderecamento (mesmo do DA_DOC origem).

DB_ITEMstring - opcionalSDB.DB_ITEM

Item da linha (gerado por Soma1 do maior existente para produto+doc).

DB_PRODUTOstring - opcionalSDB.DB_PRODUTO

Produto.

DB_LOCALstring - opcionalSDB.DB_LOCAL

Local/armazem.

DB_LOCALIZstring - opcionalSDB.DB_LOCALIZ

Endereco fisico (SBF).

DB_LOTECTLstring - opcionalSDB.DB_LOTECTL

Lote (quando o produto controla lote).

DB_NUMSERIstring - opcionalSDB.DB_NUMSERI

Numero de serie (quando aplicavel).

DB_QUANTnumber - opcionalSDB.DB_QUANT

Quantidade enderecada.

DB_DATAstring - opcionalSDB.DB_DATA

Data do movimento (YYYYMMDD).

DB_TMstring - opcionalSDB.DB_TM

Tipo de movimento (TM).

DB_ESTORNOstring - opcionalSDB.DB_ESTORNO

Flag de estorno ("S" apos estorno via MATA266).

DB_ORIGEMstring - opcionalSDB.DB_ORIGEM

Origem do movimento.

recnointeger - opcional

Id tecnico (RecNo da SDB).

msuidstring - opcionalSDB.DB_MSUID

Identificador universal MS_UID. Pode ser null quando o dicionario nao tem o campo.

msuidtstring - opcionalSDB.DB_MSUIDT

Timestamp tecnico associado ao msuid.

ListItem

object

Item enxuto da listagem /_list — chaves curtas em lowercase (vs. Linha que usa nomes de campo SX3). Inclui ids tecnicos opcionais.

filialstring - opcionalSDB.DB_FILIAL

Filial.

docstring - opcionalSDB.DB_DOC

Documento.

itemstring - opcionalSDB.DB_ITEM

Item.

produtostring - opcionalSDB.DB_PRODUTO

Produto.

localstring - opcionalSDB.DB_LOCAL

Local.

enderecostring - opcionalSDB.DB_LOCALIZ

Endereco.

quantnumber - opcionalSDB.DB_QUANT

Quantidade.

datastring - opcionalSDB.DB_DATA

Data (YYYYMMDD).

estornostring - opcionalSDB.DB_ESTORNO

Flag de estorno.

recnointeger - opcional

Id tecnico (RecNo).

msuidstring - opcional

MS_UID quando disponivel.

msuidtstring - opcional

Timestamp tecnico do MS_UID.

ExecResponse

object - envelope

Envelope da resposta do POST. data.item traz o DB_ITEM gerado por Soma1; data.idExterno ecoa o valor enviado (ou string vazia quando nao informado).

successboolean - const: true

Sempre true em respostas de sucesso.

messagestring - obrigatorio

Mensagem editorial de sucesso.

data.filialstring - opcional

Filial do movimento gravado.

data.docstring - opcional

Documento.

data.produtostring - opcional

Produto.

data.localstring - opcional

Local.

data.enderecostring - opcional

Endereco.

data.itemstring - opcional

DB_ITEM gerado por Soma1.

data.qtdnumber - opcional

Quantidade gravada.

data.idExternostring - opcional

Eco do idExterno enviado no payload.

Erro

object - envelope

Envelope padrao de erros 4xx/5xx. data pode conter o detalhe tecnico da causa (ex: mensagem do NomeAutoLog do MATA265) para tratamento programatico.

successboolean - const: false

Sempre false em erros.

messagestring - obrigatorio

Mensagem editorial do erro (apresentavel ao usuario final).

datastring - opcional

Token interno / detalhe tecnico (ex: log do MsExecAuto do MATA265).