rev1-2026-05-16 Protheus 12.1.33

LiquidacaoPagar

Liquidação e cancelamento de liquidação de títulos do Contas a Pagar (tabela SE2) via rotina automática FINA565 do Protheus. Endpoint Tier 3 — verbo no path com prefixo underscore: /_liquidar e /_cancelar. POST único com dispatcher por último segmento da URL.

FINA565 — complexidade L (alta). Esta rotina é uma das mais sensíveis do módulo financeiro. Os arrays aTela1 (15-18 elementos posicionais), aTela2 (cabeçalho do novo título), aCols (linhas/cheques) e aEdtVlr (edição de valores) têm chaves string sensíveis e o comportamento muda conforme houver ou não condição de pagamento. Este endpoint é candidato a refinamento iterativo — ver Pendências conhecidas.

Exceção do mapeamento nOper. A FINA565 é exceção do padrão Protheus: usa nOper=2 para liquidar (não 3) e nOper=4 para cancelar (não 5).

Bloqueio TOTVS: endpoint de processo; não manipula MSBLQL diretamente. Bloqueio relevante recai sobre o fornecedor (SA2) e os títulos origem (SE2).

Vinculação com o ERP

Módulo SIGAFIN Financeiro · Contas a Pagar

Tabela mestre SE2 Títulos a pagar

Rotina automática FINA565 MsExecAuto · liquidação SE2 (complexidade L)

Wrapper AdvPL U_FN565Exc src/lib/FIN/FN565EXC.prw

Operações & modos

POST /_liquidar op 2 — Liquidação (exceção: não é 3) POST /_cancelar op 4 — Cancelamento (exceção: não é 5)

Dependências de ambiente

Cadastro

Fornecedor (SA2)

fornecedor+loja deve referenciar registro existente em SA2
fornecedor não pode estar bloqueado (avaliação no FINA565)

Cadastro

Natureza financeira (SED)

campo natureza obrigatório

Cadastro · entrada

Títulos origem (SE2)

identificados por RECNO da tabela SE2
o endpoint posiciona o registro e captura E2_PREFIXO/E2_NUM/E2_PARCELA/E2_TIPO/E2_SALDO

Cadastro · opcional

Banco pagador (SA6)

triplica banco+agencia+conta grava E2_BCOCHQ/E2_AGECHQ/E2_CTACHQ em aCols
obrigatório se houver pagamento via cheque

Wrapper

U_FN565Exc

src/lib/FIN/FN565EXC.prw · MsExecAuto({|x,y,z,w| FINA565(x,y,z,w)}, aTela1, aTela2, aCols, aEdtVlr, nOper)
retorna {lOk, cMsg}; arrays passados por referência posicional

Build

Protheus 240223P+

build mínimo validado: 240223P; padrões herdados do WsBaixaPagar / WSSE2
thread REST: oWsSelf capturado antes de Begin Sequence

Convenções

Verbo no path (Tier 3). O endpoint expõe duas ações via POST único com dispatcher pelo último segmento da URL: /_liquidar (FINA565 nOper=2) e /_cancelar (FINA565 nOper=4). Qualquer outro segmento retorna 404 com mensagem listando as ações aceitas.

Identificação dos títulos por RECNO. A lista titulos[] traz objetos {recno, valor, valorJuros, valorMulta, valorDesc}. O endpoint posiciona a SE2 com DbGoTo(N) e captura E2_PREFIXO+E2_NUM+E2_PARCELA+E2_TIPO+E2_SALDO para montar aCols e aEdtVlr. RECNO inválido ou registro não encontrado retorna 422.

Valor a liquidar default = saldo aberto. Se valor for omitido, zero ou negativo, o endpoint usa SE2->E2_SALDO como base. valorLiquido interno é calculado por valor + valorJuros + valorMulta - valorDesc.

Cabeçalho da liquidação. Os campos fornecedor, loja e natureza são obrigatórios. Ausência de qualquer um retorna 422. moeda default 1 (Real); dataLiquidacao default dDataBase.

Formato de datas. dataLiquidacao aceita string ISO YYYY-MM-DD. Conversão interna usa CToD(SubStr(dt,9,2) + "/" + SubStr(dt,6,2) + "/" + SubStr(dt,1,4)) antes de empurrar para aTela1.dData565I/F.

Cancelamento. A ação /_cancelar aceita apenas numeroLiquidacao (obrigatório). O número vira sentinela CLIQCAN no aTela1; aTela2, aCols e aEdtVlr seguem vazios.

Status HTTP. 200 em sucesso; 400 body ausente ou JSON malformado; 404 ação desconhecida; 422 validação ou FINA565 rejeitou; 500 exceção não tratada.

Liquidação de Títulos a Pagar (FINA565)

Liquidação e cancelamento via FINA565 — Tier 3 (verbo no path)

POST /WsLiqPagar/_liquidar Liquida lista de títulos a pagar (FINA565 nOper=2)

Descrição

Processa a liquidação automática de uma lista de títulos a pagar via FINA565 com nOper=2 (exceção do mapeamento: FINA565 usa 2 para liquidar, não 3). Os títulos são identificados por RECNO em SE2; o endpoint posiciona cada registro, captura prefixo / número / parcela / tipo / saldo e monta os arrays aTela1/aTela2/aCols/aEdtVlr esperados pelo wrapper U_FN565Exc.

Status HTTP.

200 — liquidação processada com sucesso.
400 — body ausente / JSON malformado.
422 — campo obrigatório ausente, RECNO inválido ou FINA565 rejeitou.
500 — exceção não tratada.

Cenário

A escolha do cenário filtra os campos do body. Ambos cenários usam o mesmo schema (LiquidarRequest) — varia a combinação de campos por título.

Request body

application/json LiquidarRequest · obrigatório

Cabeçalho + lista de títulos. Schema completo em LiquidarRequest.

fornecedor string · obrigatório SA2.A2_COD

Código do fornecedor.

loja string · obrigatório SA2.A2_LOJA

Loja do fornecedor.

natureza string · obrigatório SED.ED_CODIGO

Código da natureza financeira.

moeda integer · opcional

Código da moeda (1=Real). Default 1.

dataLiquidacao string (date) · opcional

Data da liquidação (YYYY-MM-DD). Default dDataBase.

banco string · opcional SA6.A6_COD

Banco pagador.

agencia string · opcional SA6.A6_AGENCIA

Agência bancária.

conta string · opcional SA6.A6_NUMCON

Conta corrente do banco pagador.

titulos[].recno integer · obrigatório SE2.R_E_C_N_O_

RECNO do registro origem na SE2.

titulos[].valor number · opcional

Valor base a liquidar. Default SE2->E2_SALDO.

titulos[].valorJuros number · opcional

Valor de juros agregado à liquidação.

titulos[].valorMulta number · opcional

Valor de multa agregado à liquidação.

titulos[].valorDesc number · opcional

Desconto aplicado na liquidação.

Exemplo da requisição (cenário ativo)

Liquidação simples — 1 título sem juros / multa / desconto. Fixture: fixtures/liquidar-pagar.json.

RequestHTTP/1.1 · application/json

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

{
  "fornecedor":     "000001",
  "loja":           "01",
  "natureza":       "2101",
  "moeda":          1,
  "dataLiquidacao": "2026-05-16",
  "banco":          "001",
  "agencia":        "1234",
  "conta":          "12345-6",
  "titulos": [
    { "recno": 22345, "valor": 1500.00 }
  ]
}

Liquidação com juros, multa e desconto — pagamento em atraso negociado com desconto comercial. O valor líquido aplicado é calculado por valor + valorJuros + valorMulta - valorDesc.

RequestHTTP/1.1 · application/json

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

{
  "fornecedor":     "000001",
  "loja":           "01",
  "natureza":       "2101",
  "moeda":          1,
  "dataLiquidacao": "2026-05-16",
  "banco":          "001",
  "agencia":        "1234",
  "conta":          "12345-6",
  "titulos": [
    {
      "recno":      22345,
      "valor":      1500.00,
      "valorJuros": 25.00,
      "valorMulta": 15.00,
      "valorDesc":  10.00
    }
  ]
}

Respostas

200

Liquidação processada com sucesso.

400

Body ausente ou JSON malformado.

422

Campo obrigatório ausente, RECNO inválido ou FINA565 rejeitou.

500

Exceção não tratada.

Exemplo de resposta

Response · 200 OKapplication/json

{
  "success": true,
  "message": "Liquidacao processada com sucesso.",
  "data":    "OK"
}

POST /WsLiqPagar/_cancelar Cancela uma liquidação gerada (FINA565 nOper=4)

Descrição

Cancela uma liquidação previamente gerada via FINA565 com nOper=4 (exceção: não é 5). O cabeçalho aTela1 recebe a sentinela CLIQCAN com o número da liquidação; aTela2/aCols/aEdtVlr permanecem vazios.

Status HTTP.

200 — cancelamento processado.
400 — body ausente / JSON malformado.
422 — número ausente ou FINA565 rejeitou.
500 — exceção não tratada.

Cenário

Cenário único — schema CancelarRequest.

Request body

application/json CancelarRequest · obrigatório

Apenas o número da liquidação a cancelar.

numeroLiquidacao string · obrigatório SE2.E2_NUMLIQ

Número da liquidação a cancelar (vira sentinela CLIQCAN).

Exemplo da requisição (cenário ativo)

Cancelamento — informa apenas o número da liquidação a estornar. Fixture: fixtures/cancelar-liquidacao-pag.json.

RequestHTTP/1.1 · application/json

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

{
  "numeroLiquidacao": "000000010"
}

Respostas

200

Cancelamento processado com sucesso.

400

Body ausente ou JSON malformado.

422

Número ausente ou FINA565 rejeitou.

500

Exceção não tratada.

Exemplo de resposta

Response · 200 OKapplication/json

{
  "success": true,
  "message": "Cancelamento de liquidacao processado com sucesso.",
  "data":    "OK"
}

Schemas

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

LiquidarRequest

object

Envelope do POST /_liquidar. Cabeçalho da liquidação + dados bancários do pagador + lista de títulos origem identificados por RECNO.

fornecedorstring · obrigatórioSA2.A2_COD

Código do fornecedor.

lojastring · obrigatórioSA2.A2_LOJA

Loja do fornecedor.

naturezastring · obrigatórioSED.ED_CODIGO

Natureza financeira.

moedainteger · opcional

Default 1 (Real).

dataLiquidacaostring (date) · opcional

ISO YYYY-MM-DD. Default dDataBase.

bancostring · opcionalSA6.A6_COD

Banco pagador.

agenciastring · opcionalSA6.A6_AGENCIA

Agência.

contastring · opcionalSA6.A6_NUMCON

Conta corrente.

titulosarray<TituloLiq> · obrigatório

Lista não vazia de títulos a liquidar.

TituloLiq

object

Item da lista titulos[]. Identifica o título origem pelo RECNO em SE2 e opcionalmente ajusta valor base / juros / multa / desconto.

recnointeger · obrigatórioSE2.R_E_C_N_O_

RECNO do registro origem.

valornumber · opcional

Default SE2->E2_SALDO.

valorJurosnumber · opcional

Valor de juros agregado.

valorMultanumber · opcional

Valor de multa agregado.

valorDescnumber · opcional

Desconto subtraído do líquido.

CancelarRequest

object

Envelope do POST /_cancelar. Identifica a liquidação pelo número.

numeroLiquidacaostring · obrigatórioSE2.E2_NUMLIQ

Número da liquidação a cancelar (sentinela CLIQCAN).

RespostaSucesso

object · envelope

Envelope das respostas 200 para _liquidar e _cancelar.

successboolean · const: true

Sempre true em 200.

messagestring · obrigatório

Mensagem editorial.

datastring · opcional

Sentinela "OK".

RespostaErro

object · envelope

Envelope das respostas 400 / 404 / 422 / 500.

successboolean · const: false

Sempre false em erro.

messagestring · obrigatório

Descrição editorial.

datastring · opcional

Detalhe técnico opcional.

Cenários

Catálogo de combinações de payload reconhecidas pelas ações /_liquidar e /_cancelar.

liquidar-titulo-pagar

POST /_liquidar

Caminho feliz mínimo — liquida 1 título no valor cheio do saldo aberto (ou no valor informado), sem juros / multa / desconto.

Quando usar: pagamento simples no vencimento, dentro do banco pagador padrão.
Pré-condições: existe título em SE2 com E2_SALDO > 0; fornecedor não bloqueado; natureza cadastrada.
Próximos passos: guardar E2_NUMLIQ gerado para eventual cancelamento.

fornecedorstring · obrigatórioSA2.A2_COD

Código do fornecedor.

lojastring · obrigatórioSA2.A2_LOJA

Loja.

naturezastring · obrigatórioSED.ED_CODIGO

Natureza financeira.

dataLiquidacaostring · opcional

Default dDataBase.

titulos[0].recnointeger · obrigatórioSE2.R_E_C_N_O_

RECNO do título origem.

titulos[0].valornumber · opcional

Default SE2->E2_SALDO.

liquidar-com-juros-multa-desc

POST /_liquidar

Uso típico em produção — pagamento em atraso negociado acrescenta juros / multa e/ou aplica desconto comercial.

Quando usar: renegociação de título vencido; pagamento adiantado com desconto pontual.
Pré-condições: as três grandezas (valorJuros, valorMulta, valorDesc) são opcionais — qualquer combinação é aceita.
Cálculo: valorLiquido = valor + valorJuros + valorMulta - valorDesc.

fornecedorstring · obrigatórioSA2.A2_COD

Código do fornecedor.

lojastring · obrigatórioSA2.A2_LOJA

Loja.

naturezastring · obrigatórioSED.ED_CODIGO

Natureza financeira.

titulos[0].recnointeger · obrigatórioSE2.R_E_C_N_O_

RECNO do título origem.

titulos[0].valornumber · opcional

Valor base.

titulos[0].valorJurosnumber · opcional

Juros agregado.

titulos[0].valorMultanumber · opcional

Multa agregada.

titulos[0].valorDescnumber · opcional

Desconto.

cancelar-liquidacao-pagar

POST /_cancelar

Estorna uma liquidação a pagar previamente gerada.

Quando usar: liquidação digitada por engano, pagamento devolvido pelo banco.
Pré-condições: liquidação existente (E2_NUMLIQ conhecido).
Resultado: 200 OK e os títulos voltam ao estado anterior à liquidação.

numeroLiquidacaostring · obrigatórioSE2.E2_NUMLIQ

Número da liquidação a cancelar.

Pendências conhecidas (rev1)

FINA565 é complexidade L — candidato a refinamento iterativo. Os arrays aTela1 (15-18 elementos posicionais), aTela2 (cabeçalho do novo título), aCols (linhas/cheques) e aEdtVlr (edição de valores) têm chaves string sensíveis e o comportamento muda conforme houver ou não condição de pagamento. Se o smoke falhar com erro de aTela1/aTela2/aCols/aEdtVlr, abrir TASK dedicada para investigação. A implementação atual segue o doc TDN no que pôde ser inferido sem rodar a tela interativa em paralelo; ajustes finos virão dos primeiros happy-path reais.

Smoke happy-path requer RECNO real. O script test-liquidacao-pagar.sh cobre apenas negativos por default; happy-path precisa --recno N com RECNO válido de título SE2 liquidável. Refinar para descobrir RECNO automaticamente via fornecedor sentinel no próximo ciclo.

Condição de pagamento fixa em "001" no aTela2. O wrapper hardcoda cCondicao="001" e cTipo="NF" em aTela2. Em produção real, esses valores podem variar por fornecedor / filial — evoluir para aceitar override pelo payload assim que primeiro caso de uso aparecer.

Sem GET de consulta da liquidação gerada. Endpoint de processo; não expõe consulta direta. Avaliar GET _byNumLiq em revisão futura conforme demanda do front.

Identificação por RECNO acopla integração ao layout físico. Evolução natural: aceitar também {prefixo,num,parcela,tipo} e resolver internamente para RECNO. Sem pressa enquanto o front consumir só o endpoint de listagem de títulos a pagar.