rev1-2026-05-04 Protheus 12.1.33

BaixaPagarAutomatica

Baixa e cancelamento de títulos a pagar (tabela SE2) via rotina automática FINA090 — variante bancária do processo de baixa: cada título exige Banco, Agencia e Conta no payload. Use quando o lançamento financeiro precisa registrar os dados bancários completos do pagamento; para baixa simples (sem banco), prefira BaixaPagar (FINA080).

Bloqueio TOTVS: endpoint de processo (FINA090), sem MSBLQL.

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

Vinculação com o ERP

Tabela mestre SE2 Títulos a pagar

Rotina automática FINA090 MsExecAuto · baixa bancária

Wrapper AdvPL U_FN090Exe src/lib/FIN/FN090EXC.prw

Operações & modos

Operacao=3 baixa Operacao=5 cancela baixa

Dependências de ambiente

Título

SE2 — Contas a Pagar

chave composta E2_FILIAL + E2_PREFIXO + E2_NUM + E2_PARCELA + E2_TIPO + E2_FORNECE + E2_LOJA
todos os campos devem existir antes da chamada — não há criação implícita

Cadastro bancário

SA6 — Bancos / contas

campos A6_COD + A6_AGENCIA + A6_NUMCON
trio passado em Banco/Agencia/Conta precisa estar cadastrado

Ambiente

RpcSetEnv

endpoint chama RpcSetEnv("99", Filial) antes do loop
a Filial do payload define o contexto da baixa para todos os títulos do lote

Convenções

Lote, não atômico. Cada título do array Titulos é processado individualmente via MsExecAuto. Falha em um título não aborta os demais — o resultado é consolidado em data.detalhe, indexado por "1".."N". O status HTTP reflete o agregado: 200 quando todos passam, 207 em processamento parcial e 422 quando nenhum sucede.

Diferença para BaixaPagar (FINA080). FINA090 exige Banco + Agencia + Conta no payload de cada título (estrutura posicional aBaixa[8] internamente). A variante FINA080 aceita esses campos como opcionais e suporta juros / multa / acréscimo via parâmetros AUT* — não suportados nesta versão.

Formato de data. DataBaixa aceita YYYYMMDD (8 dígitos) ou DD/MM/YYYY (10 caracteres com barras). Qualquer outro formato silenciosamente cai no default dDataBase do servidor — recomendado sempre enviar explícito para evitar ambiguidade.

Códigos de operação. Operacao aceita apenas 3 (baixa) ou 5 (cancelamento de baixa). Valores fora desse domínio retornam 422 antes mesmo de iterar pelo array de títulos.

Não-objetivos da v1. Juros, multa, acréscimo, decréscimo por título e motivo de baixa customizável (AUTMOTBX) ficam fora do escopo nesta revisão. Quando precisar desses parâmetros, use o endpoint BaixaPagar (FINA080) que já os expõe.

Processamento

Baixa ou cancelamento em lote (FINA090)

POST /WsFina090/PROCESSAR Baixa ou cancela títulos a pagar em lote

Descrição

Processa um array de títulos a pagar (SE2) em modo bancário (FINA090). Cada item do array gera uma chamada independente de MsExecAuto; resultados são consolidados em data.detalhe mantendo a ordem do payload de entrada.

Operação 3 (baixa) — registra liquidação do título com banco/agência/conta.
Operação 5 (cancelamento) — reverte uma baixa previamente lançada.

O status HTTP é decidido pelo agregado: 200 (todos OK), 207 (parcial) ou 422 (nenhum sucesso). Erros por título não interrompem o processamento dos demais.

Request body

application/json BaixaPayload · obrigatório

Envelope com Filial, Operacao e array Titulos (mínimo 1 item). Schema completo em BaixaPayload.

Baixa de um título único — operação 3 com dados bancários completos. Fixture: fixtures/baixa.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Operacao": 3,
  "Titulos": [
    {
      "E2_PREFIXO": "A01",
      "E2_NUM": "000001",
      "E2_PARCELA": "001",
      "E2_TIPO": "NF",
      "E2_FORNECE": "000001",
      "E2_LOJA": "01",
      "Banco": "001",
      "Agencia": "00001",
      "Conta": "000001-0",
      "DataBaixa": "20260504"
    }
  ]
}

Cancelamento de baixa — operação 5 sobre um título previamente baixado. Fixture: fixtures/cancelamento.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Operacao": 5,
  "Titulos": [
    {
      "E2_PREFIXO": "A01",
      "E2_NUM": "000001",
      "E2_PARCELA": "001",
      "E2_TIPO": "NF",
      "E2_FORNECE": "000001",
      "E2_LOJA": "01",
      "Banco": "001",
      "Agencia": "00001",
      "Conta": "000001-0",
      "DataBaixa": "20260504"
    }
  ]
}

Lote com múltiplos títulos — dois títulos no mesmo lote; cada um é processado isoladamente. Caso um falhe (ex: chave inexistente), a resposta vem como 207 com detalhe por índice.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Operacao": 3,
  "Titulos": [
    {
      "E2_PREFIXO": "A01",
      "E2_NUM": "000001",
      "E2_PARCELA": "001",
      "E2_TIPO": "NF",
      "E2_FORNECE": "000001",
      "E2_LOJA": "01",
      "Banco": "001",
      "Agencia": "00001",
      "Conta": "000001-0",
      "DataBaixa": "20260504"
    },
    {
      "E2_PREFIXO": "A01",
      "E2_NUM": "000002",
      "E2_PARCELA": "001",
      "E2_TIPO": "NF",
      "E2_FORNECE": "000001",
      "E2_LOJA": "01",
      "Banco": "001",
      "Agencia": "00001",
      "Conta": "000001-0",
      "DataBaixa": "20260504"
    }
  ]
}

Respostas

200

Todos os títulos processados com sucesso. Envelope { success: true, message, data: BaixaData } — ver BaixaData.

207

Processamento parcial — pelo menos 1 título OK e pelo menos 1 com erro. data.detalhe traz o resultado item-a-item. Tier: happy-path-realistic.

400

Body ausente / vazio ou JSON inválido. Tier: validation-error.

422

Filial vazio, Operacao fora de {3,5}, Titulos não é array ou está vazio, ou nenhum título processado com sucesso (todos falharam). Tier: business-error.

500

Erro interno (exceção fora do laço de processamento). Tier: business-error.

Schemas

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

BaixaPayload

object

Envelope de entrada do POST. Define filial-alvo, código de operação e o array de títulos a processar.

Filialstring · obrigatório

Filial de execução do RpcSetEnv. Aplica-se a todos os títulos do lote.

Operacaointeger · obrigatório

Código da operação do FINA090.

35

Titulosarray<TituloItem> · obrigatório · minItems 1

Lista de títulos a baixar/cancelar. Cada item é processado isoladamente. Schema do item em TituloItem.

TituloItem

object

Item do array Titulos. Os 5 campos da chave SE2 (E2_PREFIXO, E2_NUM, E2_TIPO, E2_FORNECE, E2_LOJA) são obrigatórios e identificam o título no Protheus. O trio bancário (Banco/Agencia/Conta) é característico do FINA090.

E2_PREFIXOstring · obrigatórioSE2.E2_PREFIXO

Prefixo do título.

E2_NUMstring · obrigatórioSE2.E2_NUM

Número do título.

E2_PARCELAstring · opcionalSE2.E2_PARCELA

Parcela. Default "".

E2_TIPOstring · obrigatórioSE2.E2_TIPO

Tipo do título (ex: NF, DP).

E2_FORNECEstring · obrigatórioSE2.E2_FORNECE

Código do fornecedor (SA2.A2_COD).

E2_LOJAstring · obrigatórioSE2.E2_LOJA

Loja do fornecedor (SA2.A2_LOJA).

Bancostring · recomendadoSA6.A6_COD

Código do banco usado na baixa.

Agenciastring · recomendadoSA6.A6_AGENCIA

Agência bancária.

Contastring · recomendadoSA6.A6_NUMCON

Conta corrente.

DataBaixastring · opcional

Data da baixa em YYYYMMDD (8) ou DD/MM/YYYY (10). Outros formatos caem em dDataBase.

BaixaData

object

Bloco data retornado em 200 / 207. Consolida o resumo do lote e o detalhe título-a-título.

totalinteger · obrigatório

Quantidade de títulos recebidos no array.

okinteger · obrigatório

Quantidade de títulos baixados/cancelados com sucesso.

errosinteger · obrigatório

Quantidade de títulos que falharam.

detalheobject<TituloResult> · obrigatório

Mapa indexado por posição do título no array ("1".."N"). Cada valor segue TituloResult.

TituloResult

object

Resultado individual de cada título dentro do mapa data.detalhe.

titulointeger · obrigatório

Índice 1-based correspondente à posição do título no array de entrada.

okboolean · obrigatório

true quando o MsExecAuto aceitou; false em qualquer falha.

msgstring · obrigatório

Mensagem de status — "OK" em sucesso; token interno do NomeAutoLog em falha.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. Aplica-se a falhas estruturais (body ausente, JSON inválido, campos raiz fora do domínio) — falhas por título não usam este envelope, vão para data.detalhe[*] com ok: false.

successboolean · const: false

Sempre false em erros estruturais.

messagestring · obrigatório

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

datastring · opcional

Token interno / detalhe técnico, quando aplicável.