rev1-2026-05-03 Protheus 12.1.33

Empenho

CRUD de Empenho de Produção (tabelas SD4 + SDC enderecos) via rotina automática MATA381 (MSExecAuto). Substitui a User Function de desktop GAIZ_MATA381 (que era interativa). Identificador externo é a chave composta natural da SD4 (índice 2): filial-op-cod-trt-lotectl-numlote. Endereços (SDC) vêm como sub-array enderecos dentro de cada item do payload.

Bloqueio TOTVS (MSBLQL/MSBLQD): SD4 é tabela de movimento — sem bloqueio TOTVS aplicável diretamente ao empenho. O bloqueio relevante é herdado dos cadastros referenciados: produto (SB1 via B1_MSBLQL, validado em pre-check 422) e ordem de produção (SC2). Este endpoint não expõe nem aceita campos D4_MSBLQL / D4_MSBLQD por inexistirem no dicionário.

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

Vinculação com o ERP

Tabela mestre SD4 Empenho de produção (cabeçalho da linha)

Tabela detalhe SDC Endereços empenhados, nested via AUT_D4_END

Rotina automática MATA381 Clássica · MsExecAuto (não MVC)

Wrapper AdvPL U_MT381Exc src/lib/MAT/MT381EXC.prw

Operações & modos

POST modo 3 PUT modo 2 (legado) DEL modo 5

Indice externo SD4 idx 2 filial-op-cod-trt-lotectl-numlote

Dependências de ambiente

Cadastro

Ordem de Produção (SC2)

OP cadastrada e em aberto · C2_QUJE < C2_QUANT
ausência → MATA381 rejeita o payload (422)

Cadastro

Produto (SB1) e Local (SBE)

B1_MSBLQL != "1" obrigatório · SBE validado se B1_LOCALIZ == "S"
produto bloqueado / local inexistente → 422

Integração · condicional

Endereçamento físico (SDC)

cada localiz tem que existir no SBE & ter saldo
acoplado a cada linha SD4 via tag AUT_D4_END no array MSExecAuto

Saldo

Estoque (SB2/SBF)

saldo suficiente no local/localiz para empenhar a quantidade
insuficiência → 422 com mensagem do NomeAutoLog

Convenções

Identificador externo. Todas as rotas /WsEmpenho/<ACAO>/{key} usam a chave composta natural da SD4 separada por hífen: <filial>-<op>-<cod>-<trt>-<lotectl>-<numlote>. As partes cod, trt, lotectl, numlote podem ser vazias se o ambiente não controlar. Para buscar pela chave técnica (recno ou msuid) use /_byid?tipo=…&valor=….

Alteração usa nOper=2, não 4. Diferente dos outros wrappers da biblioteca (FN040 / FN050 / MT103 usam 4 para alteração), o MATA381 do build 240223P espera 2. O wrapper U_MT381Exc aceita explicitamente 2/3/5 e rejeita 4.

Exclusão de endereço dentro de PUT. Em alteração, cada item do array enderecos aceita um campo opcional delete: true. Quando presente, a linha SDC correspondente recebe a tag AUTDELETA="S" no array MSExecAuto e o MATA381 exclui apenas aquele endereço, preservando os demais. Em POST, delete:true é ignorado.

Modelagem nested. O MATA381 espera os endereços acoplados a cada linha SD4 via tag AUT_D4_END — não como entidade separada. O endpoint monta internamente o array no formato { {"D4_OP",…}, {"D4_COD",…}, …, {"AUT_D4_END", aEnder} }, onde aEnder é um array de arrays com DC_LOCALIZ/DC_QUANT e opcionalmente AUTDELETA.

Paginação e delta-sync. /_list usa page/pageSize (default 50, máx 500) com ordem por chave de negócio (índice 2). Para sincronização incremental alterne para orderBy=recno e use since/cursor conforme o nextCursor retornado.

Identificadores técnicos. Toda resposta é enriquecida com recno (sempre presente — RecNo() do registro SD4 do primeiro empenho da OP) e, quando o dicionário expõe via UPDDISTR, msuid / msuidt (D4_MSUID / D4_MSUIDT). A filtragem dos opcionais é feita por U_RestCamposOpc.

Empenho

CRUD por chave composta natural (SD4 idx 2) — filial-op-cod-trt-lotectl-numlote

POST /WsEmpenho/INCLUIR Inclui empenhos para a OP especificada no body

Descrição

Inclui empenhos de produção via MATA381 em modo 3 (inclusão). A filial e a op vêm no body. Cada item do array itens gera uma linha SD4; cada elemento de itens[].enderecos gera uma linha SDC acoplada via AUT_D4_END.

Whitelist do payload: ver EmpenhoPayload.
Sucesso devolve recno/msuid da primeira linha SD4 da OP.

Request body

application/json EmpenhoPayload · obrigatório

Payload com cabeçalho (filial, op) e array de itens. Schema completo em EmpenhoPayload.

Inclusão com 2 itens e 3 endereços — caminho feliz, OP 999998 01001, produtos MP001/MP002, locais END01/END02. Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "op": "999998 01001",
  "itens": [
    {
      "cod": "MP001",
      "local": "01",
      "data": "20991231",
      "qtdeori": 10.00,
      "quant": 10.00,
      "enderecos": [
        { "localiz": "END01", "quant": 6.00 },
        { "localiz": "END02", "quant": 4.00 }
      ]
    },
    {
      "cod": "MP002",
      "local": "01",
      "data": "20991231",
      "qtdeori": 5.00,
      "quant": 5.00,
      "enderecos": [
        { "localiz": "END01", "quant": 5.00 }
      ]
    }
  ]
}

Respostas

201

Empenhos incluídos. Envelope CrudResponse com data trazendo filial/op/linhas/recno/msuid/msuidt.

400

Payload mal-formado, JSON inválido, campo obrigatório ausente. Tier: validation-error.

422

Pré-checks 422 (SC2/SB1/SBE) ou rejeição do MsExecAuto — produto inexistente, OP encerrada, saldo insuficiente, endereço inválido. Tier: business-error.

500

Erro interno.

POST /WsEmpenho/INCLUIR/{key} Inclui usando filial+op extraídos da chave do path

Descrição

Variante de POST em que filial e op vêm pela {key} do path — útil quando o cliente já mantém a chave composta como identificador externo. As partes adicionais de {key} (cod, trt, lotectl, numlote) são ignoradas na inclusão; o corpo continua trazendo o array itens.

Path parameter

key string · path · obrigatório SD4 idx 2

Chave composta <filial>-<op>-<cod>-<trt>-<lotectl>-<numlote> — apenas filial e op são usados aqui.

Request body

application/json EmpenhoPayload · obrigatório

Mesmo schema do POST /WsEmpenho/INCLUIR. Se o body trouxer filial/op divergente da {key}, o endpoint resolve a divergência conforme a regra do .prw (consultar implementação).

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsEmpenho/INCLUIR/01-999998 01001----
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "filial": "01",
  "op": "999998 01001",
  "itens": [
    {
      "cod": "MP001",
      "local": "01",
      "data": "20991231",
      "qtdeori": 10.00,
      "quant": 10.00,
      "enderecos": [
        { "localiz": "END01", "quant": 10.00 }
      ]
    }
  ]
}

Respostas

201

Empenhos incluídos.

400

Payload mal-formado ou {key} fora do pattern. Tier: validation-error.

409

Já existe empenho com a mesma chave composta. Tier: business-error.

422

Rejeição do MsExecAuto — ver descrição de POST /WsEmpenho/INCLUIR.

500

Erro interno.

GET /WsEmpenho/{key} Consulta linha SD4 + endereços SDC

Descrição

Retorna a linha SD4 mestre identificada pela chave composta e todas as linhas SDC vinculadas (mesma combinação de filial / OP / produto / TRT / lote-ctl / num-lote). Aplica filtro de filial (xFilial("SD4")) e respeita o whitelist CAMPOS_GET.

Path parameter

key string · path · obrigatório SD4 idx 2

Chave composta <filial>-<op>-<cod>-<trt>-<lotectl>-<numlote>. As partes cod, trt, lotectl e numlote podem ser vazias.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsEmpenho/01-999998 01001-MP001---
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Empenho encontrado. Envelope { success: true, data: EmpenhoConsulta } com empenho (campos D4_*) e enderecos (array de campos DC_*).

400

{key} fora do pattern. Tier: validation-error.

404

Empenho inexistente para a chave informada. Tier: not-found.

500

Erro interno.

PUT /WsEmpenho/ALTERAR/{key} Altera empenhos da OP (MATA381 modo 2 — legado)

Descrição

Altera empenhos da OP via MATA381 em modo 2 (legado — não 4). Cada item de enderecos aceita delete: true que marca a linha SDC para exclusão via AUTDELETA="S". O MsExecAuto aplica delta — itens não citados no payload permanecem inalterados.

Path parameter

key string · path · obrigatório SD4 idx 2

Chave composta da SD4.

Request body

application/json EmpenhoPayload · obrigatório

Mesmo schema do POST. Em alteração, itens de enderecos com delete:true são marcados para exclusão SDC. Ver convenções.

Altera quantidade e remove um endereço — reduz quant de 10 para 8, mantém END01 com 8 e exclui END02 via delete:true. Fixture: fixtures/put-update.json.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsEmpenho/ALTERAR/01-999998 01001-MP001---
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "filial": "01",
  "op": "999998 01001",
  "itens": [
    {
      "cod": "MP001",
      "local": "01",
      "data": "20991231",
      "qtdeori": 10.00,
      "quant": 8.00,
      "enderecos": [
        { "localiz": "END01", "quant": 8.00 },
        { "localiz": "END02", "quant": 0, "delete": true }
      ]
    }
  ]
}

Respostas

200

Empenho alterado. Envelope CrudResponse.

400

Payload mal-formado ou {key} fora do pattern. Tier: validation-error.

404

Empenho inexistente para a chave informada. Tier: not-found.

422

Rejeição do MsExecAuto — saldo insuficiente, OP encerrada, endereço inválido. Tier: business-error.

500

Erro interno.

DEL /WsEmpenho/EXCLUIR/{key} Exclui empenhos da OP (MATA381 modo 5)

Descrição

Exclui os empenhos da OP via MATA381 em modo 5. Remove as linhas SD4 e SDC vinculadas. Sem body — a {key} identifica completamente o conjunto a apagar.

Path parameter

key string · path · obrigatório SD4 idx 2

Chave composta da SD4.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsEmpenho/EXCLUIR/01-999998 01001-MP001---
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Empenho excluído. Envelope CrudResponse.

400

{key} fora do pattern. Tier: validation-error.

404

Empenho inexistente. Tier: not-found.

422

Rejeição do MsExecAuto (OP encerrada, integração contábil bloqueia exclusão, etc.). Tier: business-error.

500

Erro interno.

GET /WsEmpenho/_byid Consulta empenho por id técnico (recno|msuid)

Descrição

Busca um empenho por id técnico — útil para integrações que persistem recno ou msuid e querem reconfirmar a linha sem reconstruir a chave composta. Resposta 501 se o ambiente não tiver D4_MSUID via UPDDISTR.

Query parameters

tipo string · query · obrigatório

Qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

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/WsEmpenho/_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/WsEmpenho/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Empenho encontrado. Envelope { success: true, data: EmpenhoConsulta }.

400

Parâmetros tipo/valor ausentes ou tipo fora do enum. Tier: validation-error.

404

Empenho não localizado. Tier: not-found.

501

Busca por msuid requer D4_MSUID publicado via UPDDISTR — indisponível neste ambiente.

500

Erro interno.

Listagem

Listagem paginada por filtros — ordem natural (chave) ou delta-sync (recno)

GET /WsEmpenho/_list Lista empenhos por filtros com paginação

Descrição

Lista linhas SD4 filtrando por qualquer combinação de filial/op/cod/trt/lotectl/numlote. Dois modos:

orderBy=chave (default) — paginação por page/pageSize, ordem por índice 2.
orderBy=recno — delta-sync, usa since/cursor com nextCursor retornado.

Query parameters

filial string · query · opcional SD4.D4_FILIAL

Filtra pela filial.

op string · query · opcional SD4.D4_OP

Filtra pela Ordem de Produção.

cod string · query · opcional SD4.D4_COD

Filtra pelo código do produto.

trt string · query · opcional SD4.D4_TRT

Filtra pela TRT.

lotectl string · query · opcional SD4.D4_LOTECTL

Filtra pelo controle de lote.

numlote string · query · opcional SD4.D4_NUMLOTE

Filtra pelo número de lote.

page integer · query · opcional

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

pageSize integer · query · opcional

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

orderBy string · query · opcional

Modo de ordenação. Default chave.

chaverecno

since integer · query · opcional

Início do delta-sync (válido com orderBy=recno).

cursor integer · query · opcional

Cursor retornado em nextCursor da página anterior.

Chamada de exemplo

Request · paginação por chaveHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsEmpenho/_list?op=999998 01001&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/WsEmpenho/_list?orderBy=recno&since=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de empenhos. Envelope com data (array de ListItem), orderBy, page, pageSize, count, opcionalmente nextCursor.

400

Parâmetro fora do domínio (ex: orderBy inválido, pageSize > 500). Tier: validation-error.

500

Erro interno.

Schemas

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

EmpenhoPayload

object

Payload aceito em POST e PUT. Cabeçalho (filial, op) define o escopo; itens traz cada linha SD4 com seu sub-array enderecos (SDC).

filialstring · obrigatórioSD4.D4_FILIAL

Filial da OP. Geralmente alinhada com xFilial("SD4").

opstring · obrigatórioSD4.D4_OP

Número da Ordem de Produção (C2_NUM + C2_ITEM + C2_SEQUEN).

itensarray<ItemEmpenho> · obrigatório

Pelo menos um item. Ver ItemEmpenho.

ItemEmpenho

object

Cada item gera uma linha SD4. O array enderecos é acoplado via tag AUT_D4_END no MSExecAuto.

codstring · obrigatórioSD4.D4_COD

Código do produto (SB1). Produto bloqueado (B1_MSBLQL="1") é rejeitado em 422.

localstring · opcional · default "01"SD4.D4_LOCAL

Local de estoque (SBE). Validado se B1_LOCALIZ="S".

datastring · obrigatórioSD4.D4_DATA

Data do empenho no formato YYYYMMDD (8 dígitos).

qtdeorinumber · opcionalSD4.D4_QTDEORI

Quantidade original empenhada. Default = quant quando ausente. Deve ser > 0.

quantnumber · obrigatórioSD4.D4_QUANT

Quantidade efetivamente empenhada (saldo). Deve ser > 0.

trtstring · opcionalSD4.D4_TRT

Tratamento (quando aplicável). Compõe a chave do índice 2.

lotectlstring · opcionalSD4.D4_LOTECTL

Controle de lote (apenas se o produto controla lote).

numlotestring · opcionalSD4.D4_NUMLOTE

Número de lote (apenas se o produto controla lote).

enderecosarray<EnderecoSDC> · opcional

Endereços empenhados. Ver EnderecoSDC.

EnderecoSDC

object

Linha SDC acoplada a um ItemEmpenho via tag AUT_D4_END. Em PUT, delete:true gera AUTDELETA="S" no array MSExecAuto.

localizstring · obrigatórioSDC.DC_LOCALIZ

Endereço físico no armazém (cadastrado em SBE).

quantnumber · obrigatório (>0)SDC.DC_QUANT

Quantidade empenhada neste endereço. A soma das quant dos endereços normalmente fecha com a quant da linha SD4 pai.

deleteboolean · opcional · default false

Apenas em PUT: marca a linha SDC para exclusão via AUTDELETA="S". Ignorado em POST.

EmpenhoConsulta

object

Estrutura retornada nos GETs /{key} e /_byid. Contém a linha mestre (empenho: campos D4_*) e os endereços SDC vinculados (enderecos: campos DC_*).

filialstring · opcionalSD4.D4_FILIAL

Filial da linha.

opstring · opcionalSD4.D4_OP

Ordem de Produção.

codstring · opcionalSD4.D4_COD

Código do produto.

trtstring · opcionalSD4.D4_TRT

Tratamento.

lotectlstring · opcionalSD4.D4_LOTECTL

Controle de lote.

numlotestring · opcionalSD4.D4_NUMLOTE

Número de lote.

countinteger · opcional

Quantidade de endereços SDC retornados.

empenhoobject · opcional

Mapa com os campos D4_* da linha SD4 (whitelist CAMPOS_GET).

enderecosarray<object> · opcional

Endereços SDC vinculados (campos DC_*): DC_LOCALIZ, DC_QUANT, DC_NUMSERI, etc.

recnointeger · opcional

RecNo do registro SD4 (sempre presente).

msuidstring · opcionalSD4.D4_MSUID

Id universal — somente se D4_MSUID existe no dicionário (UPDDISTR aplicado).

msuidtstring · opcionalSD4.D4_MSUIDT

Timestamp técnico associado ao msuid.

ListItem

object

Representação enxuta usada no /_list. Não inclui o sub-array de endereços — para isso, fazer GET /{key}.

filialstring · opcionalSD4.D4_FILIAL

Filial.

opstring · opcionalSD4.D4_OP

OP.

codstring · opcionalSD4.D4_COD

Código do produto.

trtstring · opcionalSD4.D4_TRT

Tratamento.

lotectlstring · opcionalSD4.D4_LOTECTL

Controle de lote.

numlotestring · opcionalSD4.D4_NUMLOTE

Número de lote.

localstring · opcionalSD4.D4_LOCAL

Local de estoque.

datastring · opcionalSD4.D4_DATA

Data do empenho.

quantnumber · opcionalSD4.D4_QUANT

Quantidade empenhada.

recnointeger · opcional

Id técnico do registro.

msuidstring · opcional

Id universal (quando disponível).

msuidtstring · opcional

Timestamp técnico.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz filial/op/linhas + ids técnicos (recno, msuid, msuidt) da primeira linha SD4 da OP.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

dataEmpenhoData | string · opcional

Em POST/PUT, objeto com filial/op/linhas + ids técnicos. Em DELETE pode ser string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog do MATA381) para tratamento programático.

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 MATA381).