rev2-2026-05-11 Protheus 12.1.33

MovimentacaoInterna

Registra e estorna movimentações internas de estoque (tabela SD3) via MsExecAuto sobre a rotina padrão MATA241. O POST inclui o documento (Op=3) e devolve o D3_DOC gerado por NEXTNUMERO; o PUT estorna um item específico (Op=6) por contra-lançamento — não exclui o registro original.

Bloqueio TOTVS: tabela SD3 — RM/RD via MATA241, sem MSBLQL.

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

Convenções

Geração do número do documento. O endpoint sempre gera D3_DOC via NEXTNUMERO("SD3", 2, "D3_DOC", .T.). O {doc} no path do POST é apenas placeholder — envie AUTO. O número real volta em data.doc.

Estorno é alteração de estado, não exclusão. O PUT /WsMata241/ESTORNAR/{numseq} cria um movimento inverso na SD3 via MsExecAuto Op=6; o registro original permanece, marcado pelo Protheus com D3_ESTORNO. Por isso o verbo é PUT (não DELETE).

Chave do item de estorno. A linha SD3 é localizada por D3_FILIAL+D3_COD+D3_LOCAL+D3_NUMSEQ (DbSetOrder(3)). O {numseq} no path é o discriminador exigido pelo build 240223P; Codigo, Local e NumSeq precisam estar no body também.

Campos condicionais por rastro. O item exige Lote e Validade quando B1_RASTRO="L"; adiciona SubLote quando B1_RASTRO="S"; exige Localizacao quando B1_LOCALIZ="S". Quando o Lote for informado, ele é validado em SB8 para o Armazem do item. Validação acontece em U_RstValRas antes do MsExecAuto; falha retorna 422.

Formato de Validade. String YYYYMMDD (8 dígitos exatos, sem hífen). Strings com tamanho diferente, ou que não representem data válida, voltam 400 com a mensagem do item.

Mensagens de erro do MATA241. Quando a rotina automática rejeita (TM inválido, produto não cadastrado, saldo insuficiente, item já estornado, etc.), o log do MsExecAuto é colocado em message com status 422.

MovimentacaoInterna

Inclusão (Op=3) e estorno (Op=6) de movimentação interna de estoque

POST /WsMata241/INCLUIR/{doc} Registra nova movimentação interna

Descrição

Inclui uma nova movimentação interna na SD3 via MATA241 Op=3. O cabeçalho é montado a partir de Filial, TipoMov, OrdemProducao, CentroCusto e Identificador; cada item do array Itens vira uma linha SD3. O D3_DOC é gerado pelo servidor (NEXTNUMERO) e devolvido em data.doc.

Body schema: MovimentacaoInternaRequest.
Validação condicional de rastro/localização via U_RstValRas (consulta SB1, SB8, SBE).

Path parameter

doc string · path · obrigatório

Placeholder discriminador (build 240223P exige path param para popular Self). Cliente envia AUTO — o servidor gera D3_DOC via NEXTNUMERO.

Request body

application/json MovimentacaoInternaRequest · obrigatório

Cabeçalho + array de itens. Schema completo em MovimentacaoInternaRequest.

Payload mínimo — apenas obrigatórios; produto sem rastro nem localização. Fixture: fixtures/inclusao.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "TipoMov": "001",
  "Itens": [
    {
      "Produto": "PROD001",
      "Unidade": "UN",
      "Quantidade": 1.0,
      "Armazem": "00",
      "Obs": "smoke-test-mata241"
    }
  ]
}

Produto com rastro por lote — B1_RASTRO="L" obriga Lote + Validade (YYYYMMDD). U_RstValRas valida SB8 para o armazém informado.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "TipoMov": "001",
  "OrdemProducao": "000001",
  "CentroCusto": "001",
  "Itens": [
    {
      "Produto": "PROD_LOTE",
      "Unidade": "UN",
      "Quantidade": 5.0,
      "Armazem": "01",
      "Lote": "LT0001",
      "Validade": "20271231"
    }
  ]
}

Múltiplos itens + localização — segundo item exige Localizacao porque B1_LOCALIZ="S". Cada item é uma linha SD3 independente sob o mesmo D3_DOC.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "TipoMov": "001",
  "Identificador": "INTEG-001",
  "Itens": [
    {
      "Produto": "PROD001",
      "Unidade": "UN",
      "Quantidade": 2.0,
      "Armazem": "00"
    },
    {
      "Produto": "PROD_LOCAL",
      "Unidade": "UN",
      "Quantidade": 3.0,
      "Armazem": "01",
      "Localizacao": "A1B2C3"
    }
  ]
}

Respostas

201

Movimentação registrada. Envelope RespostaInclusao com data.doc = D3_DOC gerado.

400

Body ausente/malformado, JSON inválido, campo obrigatório (Filial, TipoMov, Itens, Produto) faltando, ou Validade com formato inválido. Tier: validation-error.

422

Validação de rastro/localização falhou (B1_RASTRO/B1_LOCALIZ via U_RstValRas) ou MATA241 rejeitou (TM inexistente em SF5, produto fora do SB1, etc). Tier: business-error.

500

Exceção não tratada no AppServer. Tier: business-error.

PUT /WsMata241/ESTORNAR/{numseq} Estorna item de movimentação interna

Descrição

Estorno de um item específico (linha SD3) via MATA241 Op=6. O wrapper U_MT241InE posiciona o registro pela chave composta D3_FILIAL+D3_COD+D3_LOCAL+D3_NUMSEQ (DbSetOrder(3)), lê D3_TM/D3_EMISSAO para o cabeçalho e D3_COD/D3_UM/D3_QUANT/D3_LOCAL/D3_LOTECTL para o item, e chama MsExecAuto({|x,y,z| MATA241(x,y,z)}, aCab, aItens, 6).

Semântica. O estorno cria um movimento inverso — contra-lançamento — na SD3. O registro original permanece; o Protheus marca o par com D3_ESTORNO. Por isso o verbo é PUT (alteração de estado lógico), não DELETE.

Path parameter

numseq string · path · obrigatório SD3.D3_NUMSEQ

Número da sequência do item SD3. Discriminador exigido pelo build 240223P; o valor canônico precisa estar também em body.NumSeq.

Request body

application/json EstornoRequest · obrigatório

Chave composta da linha SD3. Schema em EstornoRequest.

Estorno de item — NumSeq no path replicado no body junto com Codigo e Local.

RequestHTTP/1.1 · application/json

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

{
  "Codigo": "PROD001",
  "Local": "00",
  "NumSeq": "000002"
}

Respostas

200

Estorno realizado. Envelope RespostaSucesso com mensagem identificando cod/local/numseq.

400

Body ausente/malformado ou chave incompleta (Codigo, Local ou NumSeq faltando). Tier: validation-error.

422

MATA241 rejeitou (item já estornado, saldo insuficiente, item inexistente no SD3, TM da linha não aceita estorno). Mensagem traz o log do MsExecAuto. Tier: business-error.

500

Exceção não tratada no AppServer.

Schemas

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

MovimentacaoInternaRequest

object

Body do POST /WsMata241/INCLUIR/{doc}. Cabeçalho da movimentação + array de itens. Os campos opcionais do cabeçalho são propagados para todas as linhas SD3 geradas.

Filialstring · obrigatórioSD3.D3_FILIAL

Filial Protheus. Tamanho máximo 2.

TipoMovstring · obrigatórioSD3.D3_TM

Tipo de movimentação (D3_TM); precisa existir e estar ativo em SF5. Tamanho máximo 3.

OrdemProducaostring · opcionalSD3.D3_OP

Número da Ordem de Produção (SC2). Tamanho máximo 12.

CentroCustostring · opcionalSD3.D3_CC

Centro de Custo (CTT). Tamanho máximo 9.

Identificadorstring · opcionalSD3.D3_IDENT

Identificador complementar livre. Tamanho máximo 12.

Itensarray<ItemMovimentacao> · obrigatório

Lista de itens da movimentação. Mínimo 1 item. Cada item vira uma linha SD3. Schema em ItemMovimentacao.

ItemMovimentacao

object

Item da movimentação — uma linha SD3. Os campos Lote/SubLote/Validade/Localizacao são condicionalmente obrigatórios conforme B1_RASTRO/B1_LOCALIZ do produto. Validação em U_RstValRas antes do MsExecAuto.

Produtostring · obrigatórioSD3.D3_COD

Código do produto (SB1). Tamanho máximo 15.

Unidadestring · obrigatórioSD3.D3_UM

Unidade de medida. Tamanho máximo 2.

Quantidadenumber · obrigatórioSD3.D3_QUANT

Quantidade movimentada. Aceita número ou string numérica; deve ser > 0.

Armazemstring · obrigatórioSD3.D3_LOCAL

Código do armazém. Tamanho máximo 2.

Localizacaostring · condicionalSD3.D3_LOCALIZ

Localização no armazém. Obrigatório quando o produto tem B1_LOCALIZ="S"; validado em SBE. Tamanho máximo 6.

Lotestring · condicionalSD3.D3_LOTECTL

Lote do produto. Obrigatório quando B1_RASTRO != "N"; validado em SB8 para o Armazem informado.

SubLotestring · condicionalSD3.D3_NUMLOTE

Sub-lote. Obrigatório quando B1_RASTRO="S".

Validadestring · condicionalSD3.D3_DTVALID

Validade no formato YYYYMMDD (8 dígitos, sem hífen). Obrigatória quando B1_RASTRO != "N". Strings com tamanho diferente ou data inválida retornam 400.

Obsstring · opcionalSD3.D3_OBS

Observação livre. Tamanho máximo 40.

EstornoRequest

object

Body do PUT /WsMata241/ESTORNAR/{numseq}. Chave composta da linha SD3 a estornar (D3_FILIAL+D3_COD+D3_LOCAL+D3_NUMSEQ, índice 3).

Codigostring · obrigatórioSD3.D3_COD

Código do produto (SB1). Tamanho máximo 15.

Localstring · obrigatórioSD3.D3_LOCAL

Código do armazém da linha original. Tamanho máximo 2.

NumSeqstring · obrigatórioSD3.D3_NUMSEQ

Sequência do item dentro do documento. Deve coincidir com o {numseq} do path. Tamanho máximo 6.

RespostaInclusao

object · envelope

Envelope retornado em 201 pelo POST. data.doc traz o D3_DOC gerado por NEXTNUMERO — use esse valor para correlacionar itens e, se preciso, para localizar a linha que será estornada depois.

successboolean · const: true

Sempre true em resposta de sucesso.

messagestring · obrigatório

Mensagem editorial (ex: "Movimentacao interna registrada com sucesso.").

data.docstring · obrigatórioSD3.D3_DOC

Número do documento gerado via NEXTNUMERO("SD3", 2, "D3_DOC", .T.).

RespostaSucesso

object · envelope

Envelope retornado em 200 pelo PUT (estorno). data fica vazio; a mensagem traz a chave do item estornado.

successboolean · const: true

Sempre true em resposta de sucesso.

messagestring · obrigatório

Mensagem editorial identificando cod/local/numseq da linha estornada.

datastring · opcional

String vazia em operações sem payload de retorno.

RespostaErro

object · envelope

Envelope padrão de erros 4xx/5xx. message repete o log do MsExecAuto quando o MATA241 rejeitou a operação, permitindo tratamento programático e diagnóstico humano sem nova ida ao AppServer.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial. Em 422, traz o texto bruto do log do MsExecAuto.

datastring · opcional

String vazia ou token interno auxiliar.