rev2-2026-05-07 Protheus 12.1.33

TipoMovimentacao

Cria, consulta e exclui Tipos de Movimentação Interna (tabela SF5) via wrapper U_MT230Exe sobre o MsExecAuto da rotina padrão MATA230. A chave externa é o próprio F5_CODIGO (3 caracteres), informado via path. Operação PUT ainda não exposta — ver PROXIMOS-PASSOS.md no diretório do endpoint.

Bloqueio TOTVS: tabela SF5 — tipo de movimentacao, verificar SX3 desta base se F5_MSBLQL existe (callout generico).

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

Convenções

Identificador externo. Todas as rotas /WsSF5/INCLUIR/{codigo}, /WsSF5/EXCLUIR/{codigo} e /WsSF5/{codigo} recebem o F5_CODIGO (até 3 caracteres) no path. A chave é também a chave externa do recurso — não há identificador interno separado.

Códigos reservados. Os valores 499 (entrada automática interna) e 999 (saída automática interna) são uso exclusivo do Protheus e rejeitados com 400 antes mesmo da chamada ao MATA230.

Convenção de faixa. Por convenção interna do ERP, códigos 001–499 são usados para Devolução e Produção; códigos 501–999 para Requisição. A regra não é imposta pelo endpoint, mas mantê-la facilita o consumo posterior por MATA241.

Defaults para campos obrigatórios da SF5. Em build 240223P, vários campos da SF5 são obrigatórios para o MsExecAuto aceitar o cadastro. O endpoint aplica defaults seguros automaticamente quando o payload omite os campos: F5_APROPR="N", F5_ATUEMP="N", F5_TRANMOD="N", F5_VAL="N", F5_QTDZERO="2", F5_AGREGCU="1", entre outros. Veja o schema TipoMovPayload para a lista completa.

Operação PUT não disponível. A alteração via MATA230 Op=4 não está exposta nesta revisão. Para alterar, exclua e recrie. Roadmap registrado em src/api/TipoMovimentacao/PROXIMOS-PASSOS.md.

TipoMovimentacao

CRUD por F5_CODIGO

GET /WsSF5/{codigo} Consulta tipo de movimentação por código

Descrição

Retorna o tipo de movimentação pelo F5_CODIGO informado no path. Aplica filtro de filial (xFilial("SF5")) e varre todos os campos F5_* do registro localizado. Útil para descobrir o schema real da SF5 antes de montar um POST.

Path parameter

codigo string · path · obrigatório SF5.F5_CODIGO

Código do tipo de movimentação (até 3 caracteres).

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSF5/001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Tipo encontrado. Envelope { success: true, data: TipoMovimentacao } — data traz todos os campos F5_* serializados como string.

400

Código vazio. Tier: validation-error.

404

Tipo de movimentação inexistente. Tier: not-found.

500

Erro interno (DbSeek, serialização). Tier: business-error.

POST /WsSF5/INCLUIR/{codigo} Inclui novo tipo de movimentação

Descrição

Inclui um novo Tipo de Movimentação Interna via MATA230 em modo 3 (Op=3, inclusão). O F5_CODIGO é informado no path; o restante (descrição em F5_TEXTO, tipo em F5_TIPO e flags operacionais) vai no body.

Whitelist de campos: ver TipoMovPayload.
Defaults aplicados automaticamente para campos obrigatórios omitidos.
Códigos 499 e 999 são rejeitados antes do MATA230.

Path parameter

codigo string · path · obrigatório SF5.F5_CODIGO

Código do tipo (até 3 caracteres, alfanumérico). Não pode ser 499 nem 999.

Request body

application/json TipoMovPayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em TipoMovPayload. Obrigatórios: F5_TEXTO e F5_TIPO.

Payload mínimo — apenas os dois obrigatórios; defaults da SF5 são aplicados pelo endpoint. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "F5_TEXTO": "TM TESTE _TEST_",
  "F5_TIPO": "R"
}

Requisição (faixa 501–999) — payload realista incluindo flags operacionais. Aceita atualização de empenho e valoração via F5_ATUEMP / F5_VAL.

RequestHTTP/1.1 · application/json

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

{
  "F5_TEXTO": "REQUISICAO PRODUCAO",
  "F5_TIPO": "R",
  "F5_APROPR": "S",
  "F5_ATUEMP": "S",
  "F5_VAL": "S"
}

Produção (faixa 001–499) — uso típico de tipo de movimento associado a apontamento de produção.

RequestHTTP/1.1 · application/json

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

{
  "F5_TEXTO": "PRODUCAO ORDEM",
  "F5_TIPO": "P",
  "F5_APROPR": "S",
  "F5_AGREGCU": "1"
}

Respostas

201

Tipo incluído. Envelope CrudResponse com data.F5_CODIGO e data.F5_TEXTO.

400

Código vazio, maior que 3 caracteres, código reservado (499/999), F5_TEXTO ausente, F5_TIPO fora do enum R/D/P, body vazio ou JSON malformado. Tier: validation-error.

409

Tipo já cadastrado para o código informado. Tier: business-error.

422

MATA230 rejeitou a inclusão (validação SX3, gatilho ou regra de localização). Mensagem do NomeAutoLog em message. Tier: business-error.

500

Erro interno (deserialização, exceção não tratada).

DEL /WsSF5/EXCLUIR/{codigo} Exclui tipo de movimentação

Descrição

Exclui o Tipo de Movimentação via MATA230 em modo 5 (Op=5). Antes da chamada, o endpoint executa DbSeek em SF5 para retornar 404 claro quando o código não existe — sem isso, o MsExecAuto devolveria um erro genérico.

O MATA230 rejeita exclusões quando o tipo está referenciado em movimentos da SD3 (estoque) ou em outras tabelas de movimento. Nesse caso o endpoint responde 422 com a mensagem do NomeAutoLog.

Path parameter

codigo string · path · obrigatório SF5.F5_CODIGO

Código do tipo (até 3 caracteres).

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSF5/EXCLUIR/900
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Tipo excluído. Envelope CrudResponse.

400

Código vazio ou maior que 3 caracteres. Tier: validation-error.

404

Tipo inexistente. Tier: not-found.

422

MATA230 rejeitou a exclusão (tipo referenciado por movimentos da SD3 ou outras tabelas dependentes). Tier: business-error.

500

Erro interno.

Schemas

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

TipoMovimentacao

object

Representação retornada no GET /WsSF5/{codigo}. O endpoint varre todos os campos F5_* do registro e serializa como string (cValToChar). Os campos abaixo são os mais relevantes para integração.

F5_FILIALstring · opcionalSF5.F5_FILIAL

Filial do registro (compartilhamento conforme xFilial).

F5_CODIGOstring · opcionalSF5.F5_CODIGO

Código do tipo de movimentação (3 caracteres).

F5_TEXTOstring · opcionalSF5.F5_TEXTO

Descrição livre (até 30 caracteres).

F5_TIPOstring · opcionalSF5.F5_TIPO

Tipo do movimento.

RDP

F5_APROPRstring · opcionalSF5.F5_APROPR

Apropria custo? S=Sim, N=Não.

SN

F5_ATUEMPstring · opcionalSF5.F5_ATUEMP

Atualiza empenho? S=Sim, N=Não.

SN

F5_TRANMODstring · opcionalSF5.F5_TRANMOD

Transferência modal? S=Sim, N=Não.

SN

F5_VALstring · opcionalSF5.F5_VAL

Valoriza movimento? S=Sim, N=Não.

SN

F5_ENVCQPRstring · opcionalSF5.F5_ENVCQPR

Envia para Controle de Qualidade do Processo.

SN

F5_LIBPVPRstring · opcionalSF5.F5_LIBPVPR

Libera produto da projeção de vendas.

SN

F5_QTDZEROstring · opcionalSF5.F5_QTDZERO

Permite quantidade zero. 1=Sim, 2=Não.

12

F5_AGREGCUstring · opcionalSF5.F5_AGREGCU

Agrega ao custo do produto. 1=Sim, 2=Não.

12

F5_GERAATFstring · opcionalSF5.F5_GERAATF

Gera ativo fixo. 1=Sim, 2=Não.

12

F5_LOTVENCstring · opcionalSF5.F5_LOTVENC

Aceita lote vencido. 1=Sim, 2=Não.

12

F5_CUSTATFstring · opcionalSF5.F5_CUSTATF

Compõe custo do ativo. 1=Sim, 2=Não.

12

TipoMovPayload

object

Payload plano aceito em POST /WsSF5/INCLUIR/{codigo}. Whitelist definida em CAMPOS_ALLOW no .prw. Obrigatórios: F5_TEXTO e F5_TIPO. Os demais campos têm defaults aplicados pelo endpoint quando omitidos (ver Convenções).

F5_TEXTOstring · obrigatórioSF5.F5_TEXTO

Descrição do tipo de movimentação (até 30 caracteres).

F5_TIPOstring · obrigatórioSF5.F5_TIPO

R=Requisição, D=Devolução, P=Produção.

RDP

F5_APROPRstring · opcionalSF5.F5_APROPR

Apropria custo. Default "N".

SN

F5_ATUEMPstring · opcionalSF5.F5_ATUEMP

Atualiza empenho. Default "N".

SN

F5_TRANMODstring · opcionalSF5.F5_TRANMOD

Transferência modal. Default "N".

SN

F5_VALstring · opcionalSF5.F5_VAL

Valoriza movimento. Default "N".

SN

F5_ENVCQPRstring · opcionalSF5.F5_ENVCQPR

Envia para CQ do Processo. Default "N".

SN

F5_LIBPVPRstring · opcionalSF5.F5_LIBPVPR

Libera projeção de vendas. Default "N".

SN

F5_QTDZEROstring · opcionalSF5.F5_QTDZERO

Permite quantidade zero. Default "2".

12

F5_AGREGCUstring · opcionalSF5.F5_AGREGCU

Agrega ao custo. Default "1".

12

F5_GERAATFstring · opcionalSF5.F5_GERAATF

Gera ativo fixo. Default "2".

12

F5_LOTVENCstring · opcionalSF5.F5_LOTVENC

Aceita lote vencido. Default "2".

12

F5_CUSTATFstring · opcionalSF5.F5_CUSTATF

Compõe custo do ativo. Default "2".

12

CrudResponse

object · envelope

Envelope padrão das respostas de POST e DELETE. Em POST, data traz F5_CODIGO e F5_TEXTO; em DELETE, data é string vazia.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso (ex: "Tipo de movimentacao incluido com sucesso.").

datastring | object · opcional

Em POST, objeto { F5_CODIGO, F5_TEXTO }. Em DELETE, string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. Quando o erro vem do MATA230, message traz a mensagem acumulada do NomeAutoLog em formato apresentável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final).

datastring · opcional

Detalhe técnico residual (geralmente string vazia neste endpoint).