rev4-2026-05-12 Protheus 12.1.33

TransferenciaEstoque

Transferência de estoque entre armazéns via MATA261 (Modelo 2) — escreve direto em SD3 sem gerar SD1/SD2 nem permitir estorno automático pela própria rotina. O endpoint cobre dois fluxos sob o mesmo WSRESTFUL: TRANSFERIR/{produto} (inclusão, op=3) e ESTORNAR/{doc} (estorno nativo via MTA260+MV_PAR04, op=6).

Bloqueio TOTVS: tabela SD3 — transferencia entre armazens, sem MSBLQL.

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

Vinculação com o ERP

Tabela mestre SD3 Movimentações de estoque

Rotina automática MATA261 Modelo 2 · MsExecAuto

Wrapper AdvPL U_MT261Exe / U_MT261Est src/lib/MAT/MT261EXC.prw

Operações & modos

TRANSFERIR op 3 ESTORNAR op 6 (via MTA260)

Dependências de ambiente

Cadastro

Produto (controle de rastro/localização)

tabela SB1 · campos B1_RASTRO + B1_LOCALIZ
B1_RASTRO: "N"=sem rastro, "L"=lote, "S"=lote+sub-lote
B1_LOCALIZ: "N"=não controla, "S"=exige endereço

Saldo · obrigatório

Saldo em estoque

tabela SB2 (saldo armazém) · SB8 (lote) · SBE (endereço)
Wrapper U_RstValRas valida lote em SB8 e endereço em SBE antes do MsExecAuto

Pergunta · estorno

MTA260 / MV_PAR04

pergunta MTA260 · variável MV_PAR04
1=estorno por DOC · 2=estorno por ITEM
liberado a partir do release 12.1.2210+ (DT DMANMAT01-34333)

Integração · sem reverso

SD3 direto (sem SD1/SD2)

Modelo 2 não passa por nota fiscal — diferente do MATA241 (Modelo 1) e do MATA240.
Estorno somente via ESTORNAR; aplica D3_ESTORNO="S"

Convenções

Modelo 1 vs Modelo 2. Use TransferenciaArmazem (MATA241, Modelo 1) quando o processo exigir geração de SD1/SD2 e estorno nativo via reversão automática. Este endpoint (Modelo 2) faz movimento direto em SD3 e não gera reverso pelo próprio fluxo — o cancelamento é uma operação distinta (ESTORNAR).

Roteamento por verbo na URL. O mesmo WSRESTFUL serve dois fluxos diferenciados pelo penúltimo segmento do path: /WsMata261/TRANSFERIR/{produto} aciona o fluxo de inclusão; /WsMata261/ESTORNAR/{doc} aciona o estorno. O wrapper lê aURLParms[Len()] (último) e aURLParms[Len()-1] (verbo).

Rastro e localização. Os campos opcionais Lote, SubLote, Validade, EndOrigem, EndDestino são condicionalmente obrigatórios em função de B1_RASTRO e B1_LOCALIZ do produto. A regra é aplicada pelo helper U_RstValRas antes do MsExecAuto — payload incompleto retorna 422 com motivo explícito.

Formato de validade. Validade entra como string de 8 dígitos no formato YYYYMMDD (não ISO). Conversão interna usa SToD(); string vazia é aceita quando o produto não controla rastro.

CriarSB2 aceito porém ignorado. O campo existe no contrato por compatibilidade com clientes antigos, mas o comportamento foi removido na rev2 — chamar CriaSB2() dentro da thread REST do build 240223P invalidava o Self. Criar saldo zerado em armazém destino é tarefa transversal (MATA225) fora do escopo deste endpoint.

Quirk do estorno — HTTP 500 com efeito aplicado. No build 240223P, o MsExecAuto em op=6 do MATA261 invalida a thread REST após gravar D3_ESTORNO="S". O cliente deve confirmar o resultado consultando SD3 (ou o endpoint irmão WsTransferenciaArmazem) depois de chamar ESTORNAR. Retorno 200 indica sucesso confirmado pelo wrapper; 500 sem body também é compatível com sucesso — não retentar sem verificar.

Movimentação

Transferência (Modelo 2) e estorno do documento

POST /WsMata261/TRANSFERIR/{produto} Transfere estoque entre armazéns (Modelo 2)

Descrição

Executa transferência de estoque entre dois armazéns via MATA261 em modo 3 (MODEL_OPERATION_INSERT) — escreve um movimento direto em SD3 sem gerar nota. Operação irreversível pelo próprio fluxo: use o endpoint ESTORNAR para cancelar, ou consulte os não-objetivos antes de planejar correção.

Lote/validade/endereço validados pelo wrapper U_RstValRas antes do MsExecAuto.
CriarSB2: true aceito no contrato porém ignorado — ver Convenções.

Path parameter

produto string · path · obrigatório SB1.B1_COD

Código do produto (até 15 caracteres). Deve existir em SB1 com saldo em LocOrigem.

Request body

application/json TransferenciaPayload · obrigatório

Schema completo em TransferenciaPayload. Campos condicionalmente obrigatórios em função de B1_RASTRO e B1_LOCALIZ.

Produto sem rastro nem endereço — caso coberto pelo smoke test-transferencia-estoque.sh. Produto com B1_RASTRO="N" e B1_LOCALIZ="N". Fixture: fixtures/transferencia.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "LocOrigem": "01",
  "LocDestino": "02",
  "Quantidade": 10.0,
  "EndOrigem": "",
  "EndDestino": "",
  "CriarSB2": false
}

Produto controla lote — B1_RASTRO="L" (somente lote). Lote e Validade obrigatórios. O wrapper valida o lote em SB8 pelo armazém origem antes de aceitar. Não validado por smoke — confira em homologação.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "LocOrigem": "01",
  "LocDestino": "02",
  "Quantidade": 10.0,
  "EndOrigem": "",
  "EndDestino": "",
  "Lote": "LOTE001",
  "Validade": "20271231",
  "CriarSB2": false
}

Produto controla endereço — B1_LOCALIZ="S", sem rastro de lote. EndOrigem e EndDestino obrigatórios; o wrapper valida ambos em SBE. Não validado por smoke.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "LocOrigem": "01",
  "LocDestino": "02",
  "Quantidade": 10.0,
  "EndOrigem": "END001",
  "EndDestino": "END002",
  "CriarSB2": false
}

Cenário completo — lote + endereço — produto com B1_RASTRO="L" e B1_LOCALIZ="S". Quando B1_RASTRO="S", adicionar SubLote no payload. Lote validado em SB8 do armazém+endereço origem (onde existe saldo a baixar). Não validado por smoke.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "LocOrigem": "01",
  "LocDestino": "02",
  "Quantidade": 10.0,
  "EndOrigem": "END001",
  "EndDestino": "END002",
  "Lote": "LOTE001",
  "Validade": "20271231",
  "CriarSB2": false
}

Respostas

201

Transferência concluída. Envelope TransferenciaOk com produto, armazéns, quantidade e (quando aplicável) lote/validade.

400

Body ausente/JSON inválido, path param vazio ou Validade fora do formato YYYYMMDD. Tier: validation-error.

422

Validação de negócio — campo obrigatório vazio, produto não cadastrado, lote inexistente em SB8, endereço inválido em SBE, falha do MsExecAuto (saldo insuficiente, armazém inativo, etc). Tier: business-error.

500

Erro interno (exceção não tratada). Tier: business-error.

POST /WsMata261/ESTORNAR/{doc} Estorna documento de transferência (op=6)

Descrição

Estorna um documento SD3 previamente incluído pelo TRANSFERIR — chama MATA261 em modo 6 com a pergunta MTA260 preenchida via MV_PAR04 (1=DOC, 2=ITEM). Disponível a partir do release 12.1.2210+ (DT DMANMAT01-34333). Aplica D3_ESTORNO="S" nas linhas alvo.

Quirk 240223P. A operação op=6 invalida a thread REST após gravar no banco — o response pode chegar como HTTP 500 sem corpo JSON apesar do estorno ter sido aplicado. O cliente deve confirmar via consulta a SD3 antes de retentar. Ver Convenções.

Path parameter

doc string · path · obrigatório SD3.D3_DOC

Número do documento SD3 gerado pelo TRANSFERIR. Sequencial controlado pelo Protheus.

Request body

application/json EstornoPayload · opcional

Body opcional. Schema em EstornoPayload. Sem body, default tipo="DOC".

Estorno de documento inteiro — sem body — quando o body é omitido, o wrapper assume tipo="DOC" (MV_PAR04=1): todas as linhas do D3_DOC são estornadas.

RequestHTTP/1.1 · sem body

POST https://erpapi.jetme.com.br/api/99/01/WsMata261/ESTORNAR/000000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Estorno por documento — body explícito — equivalente ao default. Útil quando o cliente serializa o tipo como configuração e quer rastreabilidade no log da chamada.

RequestHTTP/1.1 · application/json

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

{
  "tipo": "DOC"
}

Estorno item-a-item — passa MV_PAR04=2 internamente; a rotina nativa apresenta as linhas do documento ao usuário. Em fluxo REST sem UI, esse modo só é útil quando o documento tem uma única linha.

RequestHTTP/1.1 · application/json

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

{
  "tipo": "ITEM"
}

Respostas

200

Estorno confirmado pelo wrapper. Envelope EstornoOk.

400

Path param {doc} vazio ou JSON inválido no body opcional. Tier: validation-error.

422

Documento inexistente, já estornado, ou regra de negócio do MATA261 rejeitou. Tier: business-error.

500

Pode coexistir com estorno aplicado — quirk 240223P. Confirme via consulta a SD3 antes de retentar.

Schemas

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

TransferenciaPayload

object

Payload do TRANSFERIR. Filial, LocOrigem, LocDestino e Quantidade sempre obrigatórios. Os demais são condicionalmente obrigatórios em função de B1_RASTRO e B1_LOCALIZ do produto — ver Convenções.

Filialstring · obrigatório

Filial de execução. Convenção do projeto fixa "01".

LocOrigemstring · obrigatórioSD3.D3_LOCAL

Armazém de origem. Precisa ter saldo do produto.

LocDestinostring · obrigatórioSD3.D3_LOCAL

Armazém de destino. Pode não ter SB2 ainda — ver CriarSB2.

Quantidadenumber · obrigatórioSD3.D3_QUANT

Quantidade a transferir; deve ser maior que zero (mínimo 0.001).

EndOrigemstring · condicionalSD3.D3_LOCALIZ

Endereço de origem. Obrigatório quando B1_LOCALIZ="S"; validado em SBE. Default "".

EndDestinostring · condicionalSD3.D3_LOCALIZ

Endereço de destino. Obrigatório quando B1_LOCALIZ="S". Default "".

Lotestring · condicionalSD3.D3_LOTECTL

Obrigatório quando B1_RASTRO≠"N". Quando informado, validado em SB8 do armazém origem. Default "".

SubLotestring · condicionalSD3.D3_NUMLOTE

Obrigatório quando B1_RASTRO="S". Default "".

Validadestring · condicionalSD3.D3_DTVALID

Obrigatória quando B1_RASTRO≠"N". Formato YYYYMMDD (não ISO). Pattern: ^[0-9]{8}$. Default "".

CriarSB2boolean · opcional

Aceito no contrato porém ignorado na rev2 — ver Convenções. Default false.

EstornoPayload

object

Body opcional do ESTORNAR. Quando omitido, o wrapper assume tipo="DOC".

tipostring · opcional

Modo de estorno mapeado para MV_PAR04 da pergunta MTA260. Default "DOC".

DOCITEM

TransferenciaOk

object · envelope

Envelope retornado pelo TRANSFERIR. Campos de lote/validade só aparecem quando o produto controla rastro.

successboolean · const: true

Sempre true em sucesso.

messagestring · obrigatório

Mensagem editorial — tipicamente "Transferencia concluida.".

data.produtostring

Código do produto transferido.

data.locOrigemstring

Armazém de origem.

data.locDestinostring

Armazém de destino.

data.quantidadenumber

Quantidade transferida.

data.lotestring · condicional

Presente apenas quando informado no payload.

data.subLotestring · condicional

Presente apenas quando informado.

data.validadestring · condicional

Serializado via DToS — formato YYYYMMDD. Presente apenas quando informado.

EstornoOk

object · envelope

Envelope do ESTORNAR quando o wrapper consegue retornar 200. Em caso de 500 com efeito aplicado (quirk 240223P), nenhum body JSON estruturado é entregue.

successboolean · const: true

Sempre true.

messagestring · obrigatório

Mensagem editorial — "Estorno concluido (modo DOC)." ou "... (modo ITEM).".

data.docstring

Número do documento estornado.

data.tipostring

Modo aplicado — "DOC" ou "ITEM".

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: log do MsExecAuto) 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).