rev1-2026-05-04 Protheus 12.1.33

TipoEntradaSaida

Cadastro de Tipos de Entrada/Saída (TES — tabela SF4) via MATA080 (MsExecAuto). Expõe inclusão e exclusão; a chave externa é o F4_CODIGO (3 caracteres). Códigos 000–499 e 500 são Entradas; 501–999 são Saídas — convenção do MATA080 que precisa casar com o campo Tipo do payload.

Bloqueio TOTVS: tabela SF4 — TES, verificar SX3 desta base se F4_MSBLQL existe (callout generico).

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

Vinculação com o ERP

Tabela mestre SF4 Cadastro de Tipos de Entrada/Saída

Rotina automática MATA080 MsExecAuto · clássico

Wrapper AdvPL U_MT080Exe src/lib/MAT/MT080EXC.prw

Operações & modos

POST Op=3 DEL Op=5

Dependências de ambiente

Cadastro

Convenção de códigos

F4_CODIGO 3 chars · F4_TIPO "E"/"S"
000–499 e 500 = Entrada · 501–999 = Saída

Integração · condicional

CFOP (SX5)

F4_CF validado contra tabela genérica 13
CFOP inexistente provoca rejeição do MATA080

Helpers

Wrapper MsExecAuto

U_MT080Exe(aArray, nOper) · U_RestErro / U_RestQ
retorna { lOk, cMsg } com log do NomeAutoLog

Convenções

Identificador externo. F4_CODIGO tem 3 caracteres (padding automático no DELETE via PadR). A rota POST /WsSF4/ é "coleção" — o código vai no body. A rota DELETE /WsSF4/{codigo} recebe o código no path. Não existe GET nesta versão.

Tipo é obrigatório. Tipo aceita apenas "E" (Entrada) ou "S" (Saída). Qualquer outro valor retorna 400 antes do MsExecAuto. A convenção de prefixos do código (0XX–4XX/500 = E, 5XX–9XX = S) é recomendação do TDN — quem garante consistência é o F4_TIPO do payload.

Defaults "N". Todos os flags S/N do payload (CreditICM, CreditIPI, Duplicata, Estoque, Poder3, CalcICM, CalcIPI, LivroICM, LivroIPI, DestacaIPI, IncideIPI, CompleICM) caem para "N" quando ausentes. Para ativar um comportamento (gerar duplicata, atualizar estoque, etc), envie "S" explicitamente.

CFOP e Texto são opcionais. CFOP só entra no aArray quando não-vazio; idem Texto. Isso evita sobrescrever default do MATA080 com string em branco. CFOP vazio é aceito mas o TES nasce sem amarração fiscal — atribua antes de movimentar nota.

TipoEntradaSaida

Inclusão e exclusão de TES via MATA080

POST /WsSF4/ Cria TES

Descrição

Inclui um novo Tipo de Entrada/Saída via MATA080 em operação 3 (inclusão). O endpoint monta o aArray a partir do payload, aplica defaults "N" para os flags S/N, e delega ao wrapper U_MT080Exe. O F4_CODIGO vai no body (não no path).

Whitelist de campos: ver TESRequest.
Campos opcionais omitidos não entram no aArray — o MATA080 aplica o próprio default.

Request body

application/json TESRequest · obrigatório

Payload plano com os campos do TES. Schema completo em TESRequest.

Filialstring · obrigatório

Filial do TES.

Codigostring · obrigatório

Código do TES (F4_CODIGO).

Tipostring ("E"/"S") · obrigatório

E=Entrada, S=Saída.

CreditICMstring ("S"/"N") · default N

Credita ICMS.

PoderTercstring · opcional

Indicador de poder de terceiros (apenas saída).

Mínimo (Entrada). Apenas os obrigatórios: Filial, Codigo e Tipo. Defaults "N" em todos os flags. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Codigo": "TST",
  "Tipo": "E"
}

Completo (Entrada com CFOP). Configuração típica de TES de compra: gera duplicata, atualiza estoque, credita ICMS e IPI, CFOP 1101. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Codigo": "TST",
  "Tipo": "E",
  "CreditICM": "S",
  "CreditIPI": "S",
  "Duplicata": "S",
  "Estoque": "S",
  "Poder3": "N",
  "CalcICM": "S",
  "CalcIPI": "S",
  "CFOP": "1101",
  "Texto": "COMPRA MERCADORIAS",
  "LivroICM": "S",
  "LivroIPI": "S",
  "DestacaIPI": "S",
  "IncideIPI": "S",
  "CompleICM": "N"
}

Saída com duplicata. TES de venda no range 5XX — gera duplicata para contas a receber, atualiza estoque, CFOP 5102 (venda dentro do estado).

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Codigo": "510",
  "Tipo": "S",
  "Duplicata": "S",
  "Estoque": "S",
  "CFOP": "5102",
  "Texto": "VENDA MERCADORIAS"
}

Respostas

201

TES criado. Envelope RespostaInclusao com data.codigo ecoando o F4_CODIGO.

400

Body ausente/malformado, Codigo vazio, ou Tipo fora do conjunto E/S. Tier: validation-error.

422

MATA080 rejeitou (TES já existe, CFOP inválido, combinação de flags incompatível, etc). Mensagem do NomeAutoLog em message. Tier: business-error.

500

Exceção não tratada no wrapper.

DEL /WsSF4/{codigo} Exclui TES

Descrição

Exclui o TES via MATA080 em operação 5 (exclusão). O endpoint faz DbSeek em SF4 (ordem 1 · xFilial("SF4") + F4_CODIGO com padding PadR) antes de chamar o MsExecAuto, para devolver 404 explicitamente quando o código não existe na filial.

Path parameter

codigo string · path · obrigatório SF4.F4_CODIGO

Código do TES (até 3 caracteres). Aplicação faz PadR automaticamente.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSF4/TST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

TES excluído. Envelope RespostaSucesso com message de confirmação.

400

codigo ausente na URL. Tier: validation-error.

404

TES inexistente na filial corrente. Tier: not-found.

422

MATA080 rejeitou (TES referenciado em movimentos, regras fiscais ativas, etc). Tier: business-error.

500

Exceção não tratada.

Schemas

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

TESRequest

object

Payload aceito em POST /WsSF4/. Os flags S/N que não vierem no body caem para "N" antes de ir para o aArray do MATA080. CFOP e Texto só são adicionados quando não-vazios.

Filialstring · obrigatório

Código da filial (máx 2). Identifica o contexto SF4 alvo da inclusão.

Codigostring · obrigatórioSF4.F4_CODIGO

Código do TES (máx 3). Convenção: 000–499 e 500 = Entrada; 501–999 = Saída.

Tipostring · obrigatórioSF4.F4_TIPO

Tipo do TES.

ES

CreditICMstring · opcionalSF4.F4_CREDICM

Credita ICMS? Default "N".

SN

CreditIPIstring · opcionalSF4.F4_CREDIPI

Credita IPI? Default "N".

SN

Duplicatastring · opcionalSF4.F4_DUPLIC

Gera duplicata (contas a pagar/receber)? Default "N".

SN

Estoquestring · opcionalSF4.F4_ESTOQUE

Atualiza estoque? Default "N".

SN

Poder3string · opcionalSF4.F4_PODER3

Poder de terceiros. Default "N".

NRD

CalcICMstring · opcionalSF4.F4_ICM

Calcula ICMS? Default "N".

SN

CalcIPIstring · opcionalSF4.F4_IPI

Calcula IPI? Default "N".

SN

CFOPstring · opcionalSF4.F4_CF

CFOP (até 4 dígitos). Só é gravado quando não-vazio. Validado contra SX5 tabela 13 pelo MATA080.

Textostring · opcionalSF4.F4_TEXTO

Texto padrão impresso na nota (máx 30). Só gravado quando não-vazio.

LivroICMstring · opcionalSF4.F4_LFICM

Registra no livro fiscal ICMS? Default "N".

SN

LivroIPIstring · opcionalSF4.F4_LFIPI

Registra no livro fiscal IPI? Default "N".

SN

DestacaIPIstring · opcionalSF4.F4_DESTACA

Destaca IPI na nota? Default "N".

SN

IncideIPIstring · opcionalSF4.F4_INCIDE

IPI incide na base do ICMS? Default "N".

SN

CompleICMstring · opcionalSF4.F4_COMPL

Complemento de ICMS? Default "N".

SN

RespostaInclusao

object · envelope

Envelope retornado em 201 de POST /WsSF4/. data.codigo ecoa o F4_CODIGO gravado — útil para confirmação no cliente sem reler do banco.

successboolean · const: true

Sempre true em 201.

messagestring · obrigatório

Mensagem editorial — "TES criado com sucesso.".

dataobject · obrigatório

Objeto com codigo (string) — espelho do F4_CODIGO incluído.

RespostaSucesso

object · envelope

Envelope retornado em 200 de DELETE /WsSF4/{codigo}. data é string vazia — a confirmação está em message.

successboolean · const: true

Sempre true em 200.

messagestring · obrigatório

Mensagem editorial — "TES {codigo} excluido com sucesso.".

datastring · opcional

Vazio.

RespostaErro

object · envelope

Envelope padrão de respostas 4xx/5xx. Em 422, message traz o token do NomeAutoLog do MATA080 para inspeção programática.

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 opcional (vazio na maioria dos casos).

Cenários

Combinações testáveis — alinhadas 1-pra-1 com examples: do YAML.

payload-minimo-entrada

POST /WsSF4/

Caminho feliz mínimo: TES de entrada com apenas os campos obrigatórios. MATA080 aplica defaults nos flags S/N.

Filial

"01"

Codigo

"TST" (3 chars; F4_CODIGO)

Tipo

"E" (Entrada)

payload-completo

POST /WsSF4/

Caminho realístico: TES de entrada com créditos de ICMS/IPI ativos e CFOP de compra.

Filial / Codigo / Tipo

"01" / "TST" / "E"

CreditICM, CreditIPI

"S" — credita imposto

CFOP

"1101" (compra industrial)

payload-saida-com-duplicata

POST /WsSF4/

Variação válida: TES de saída que gera duplicata financeira (F4_DUPLIC="S"). PoderTerc fica relevante em saídas.

Tipo

"S" (Saída)

Duplic

"S" — gera duplicata

PoderTerc

"N" — operação própria

excluir

DELETE /WsSF4/{codigo}

Exclusão do TES via MATA080 op=5. Falha quando o TES está em uso por documento existente.

path.codigo

"TST"

Pendências conhecidas (rev2)

PUT / GET ainda não documentados aqui. A TASK-fiscal-saidas-doc-api-v1 prevê WsSF4 rev2 com PUT (alteração) e GETs ({codigo}, _search, _list, _byid). Doc atualizará com a chegada do código.

Bloqueio TOTVS SF4 ausente. A tabela SF4 não tem F4_MSBLQL nesta base. Bloqueio operacional do TES é feito via campos próprios (e.g. F4_NUMSEQ=0 impede uso em nota), não via flag MSBLQL.