rev1-2026-05-16 Protheus 12.1.33

LiquidacaoReceber

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

Bloqueio TOTVS: endpoint de processo; não manipula MSBLQL diretamente. Bloqueio relevante recai sobre o cliente (SA1) e os títulos origem (SE1), avaliado pelo próprio FINA460.

Vinculação com o ERP

Módulo SIGAFIN Financeiro · Contas a Receber

Tabela mestre SE1 Títulos a receber

Rotina automática FINA460 MsExecAuto · liquidação SE1

Wrapper AdvPL U_FN460Exc src/lib/FIN/FN460EXC.prw

Operações & modos

POST /_liquidar op 3 — Liquidação POST /_cancelar op 5 — Cancelamento

Dependências de ambiente

Cadastro

Cliente (SA1)

cliente+loja deve referenciar registro existente em SA1
cliente não pode estar bloqueado (avaliação no próprio FINA460)

Cadastro

Natureza financeira (SED)

campo natureza obrigatório; default herdado do título origem

Cadastro · entrada

Títulos origem (SE1)

identificados por RECNO da tabela SE1
o endpoint posiciona o registro e captura E1_PREFIXO/E1_NUM/E1_PARCELA/E1_VENCTO/E1_VALOR

Wrapper

U_FN460Exc

src/lib/FIN/FN460EXC.prw · MsExecAuto({|x,y,z| FINA460(x,y,z)}, aAutoCab, aAutoIts, nOper)
agrega lMsErroAuto, retorna {lOk, cMsg}

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 (FINA460 nOper=3) e /_cancelar (FINA460 nOper=5). 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: N}. O endpoint posiciona a SE1 com DbGoTo(N) e captura E1_PREFIXO+E1_NUM+E1_PARCELA+E1_VENCTO+E1_VALOR para montar o sub-array aAutoIts. RECNO inválido ou registro não encontrado retorna 422.

Cabeçalho da liquidação. Os campos cliente, loja, natureza e tipo são obrigatórios. Ausência de qualquer um retorna 422. moeda default 1 (Real). marcaPix vazio = não usar; não-vazio = ativa AUTMRKPIX=.T. no array.

Cancelamento. A ação /_cancelar aceita apenas numeroLiquidacao (obrigatório) e filialOrigem (opcional, vira sentinela cAutoFil no cabeçalho do FINA460).

Status HTTP. 200 em sucesso; 400 body ausente ou JSON malformado; 404 ação desconhecida; 422 validação ou FINA460 rejeitou (campos obrigatórios, RECNO inválido, regra de negócio); 500 exceção não tratada (capturada por Begin Sequence).

Liquidação de Títulos a Receber (FINA460)

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

POST /WsLiqReceber/_liquidar Liquida lista de títulos a receber (FINA460 nOper=3)

Descrição

Processa a liquidação de uma lista de títulos a receber via FINA460 com nOper=3. Os títulos são identificados por RECNO na tabela SE1; o endpoint posiciona o registro, captura prefixo / número / parcela / vencimento / valor e monta o sub-array aAutoIts esperado pelo wrapper U_FN460Exc.

Status HTTP.

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

Cenário

A escolha do cenário acima filtra os campos do body abaixo e o HTTP raw de exemplo. Ambos os cenários usam o mesmo schema (LiquidarRequest) — varia a combinação enviada.

Request body

application/json LiquidarRequest · obrigatório

Cabeçalho da liquidação + lista de títulos. Schema completo em LiquidarRequest.

cliente string · obrigatório SA1.A1_COD

Código do cliente.

loja string · obrigatório SA1.A1_LOJA

Loja do cliente.

natureza string · obrigatório SED.ED_CODIGO

Código da natureza financeira.

tipo string · obrigatório SE1.E1_TIPO

Tipo do título gerado pela liquidação (RC, NF, etc.).

condicao string · opcional

Código da condição de pagamento.

moeda integer · opcional

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

marcaPix string · opcional

Vazio = não usar; não-vazio = ativa AUTMRKPIX=.T..

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

RECNO do registro origem na tabela SE1 (1 por item da lista).

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

Liquidação de 1 título — caminho feliz mínimo. Fixture: fixtures/liquidar-receber.json.

RequestHTTP/1.1 · application/json

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

{
  "condicao": "001",
  "natureza": "1101",
  "tipo":     "RC",
  "cliente":  "000001",
  "loja":     "01",
  "moeda":    1,
  "marcaPix": "",
  "titulos": [
    { "recno": 12345 }
  ]
}

Liquidação de múltiplos títulos — uso típico em produção, agrupa títulos do mesmo cliente numa única liquidação. Cada RECNO posiciona um registro distinto na SE1.

RequestHTTP/1.1 · application/json

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

{
  "condicao": "001",
  "natureza": "1101",
  "tipo":     "RC",
  "cliente":  "000001",
  "loja":     "01",
  "moeda":    1,
  "marcaPix": "",
  "titulos": [
    { "recno": 12345 },
    { "recno": 12346 },
    { "recno": 12347 }
  ]
}

Respostas

200

Liquidação processada com sucesso. Envelope RespostaSucesso.

400

Body ausente ou JSON malformado. Tier: validation-error.

422

Campo obrigatório ausente, RECNO inválido ou FINA460 rejeitou. Tier: business-error.

500

Exceção não tratada (capturada por Begin Sequence). Tier: business-error.

Exemplo de resposta

Response · 200 OKapplication/json

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

POST /WsLiqReceber/_cancelar Cancela uma liquidação gerada (FINA460 nOper=5)

Descrição

Cancela uma liquidação previamente gerada via FINA460 com nOper=5. O cabeçalho do MsExecAuto recebe a sentinela cNumLiqCan com o número da liquidação; aAutoIts permanece vazio.

Status HTTP.

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

Cenário

Cenário único — schema CancelarRequest.

Request body

application/json CancelarRequest · obrigatório

Número da liquidação a cancelar e, opcionalmente, a filial de origem.

numeroLiquidacao string · obrigatório SE1.E1_NUMLIQ

Número da liquidação a cancelar.

filialOrigem string · opcional

Filial onde a liquidação foi gerada (vira sentinela cAutoFil).

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

Cancelamento de liquidação — informa o número da liquidação e (opcionalmente) a filial origem. Fixture: fixtures/cancelar-liquidacao-rec.json.

RequestHTTP/1.1 · application/json

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

{
  "numeroLiquidacao": "000000001",
  "filialOrigem":     "01"
}

Respostas

200

Cancelamento processado com sucesso.

400

Body ausente ou JSON malformado.

422

Número ausente ou FINA460 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 + lista de títulos identificados por RECNO.

clientestring · obrigatórioSA1.A1_COD

Código do cliente.

lojastring · obrigatórioSA1.A1_LOJA

Loja do cliente.

naturezastring · obrigatórioSED.ED_CODIGO

Código da natureza financeira.

tipostring · obrigatórioSE1.E1_TIPO

Tipo do título gerado (RC, NF, etc.).

condicaostring · opcional

Código da condição de pagamento.

moedainteger · opcional

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

marcaPixstring · opcional

Vazio = não usar; não-vazio = ativa AUTMRKPIX=.T..

titulosarray<TituloRecno> · obrigatório

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

TituloRecno

object

Item da lista titulos[]. Identifica o título origem pelo RECNO na tabela SE1.

recnointeger · obrigatórioSE1.R_E_C_N_O_

RECNO do registro origem.

CancelarRequest

object

Envelope do POST /_cancelar. Identifica a liquidação a cancelar pelo número e (opcionalmente) filial origem.

numeroLiquidacaostring · obrigatórioSE1.E1_NUMLIQ

Número da liquidação a cancelar.

filialOrigemstring · opcional

Filial onde a liquidação foi gerada.

RespostaSucesso

object · envelope

Envelope das respostas 200 para _liquidar e _cancelar.

successboolean · const: true

Sempre true em 200.

messagestring · obrigatório

Mensagem editorial do sucesso.

datastring · opcional

Sentinela "OK" em sucesso.

RespostaErro

object · envelope

Envelope das respostas 400 / 404 / 422 / 500.

successboolean · const: false

Sempre false em erro.

messagestring · obrigatório

Descrição editorial do erro.

datastring · opcional

Detalhe técnico opcional.

Cenários

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

liquidar-titulo-simples

POST /_liquidar

Caminho feliz mínimo — liquida um único título.

Quando usar: recebimento avulso de cliente, sem agrupamento.
Pré-condições: existe um título em SE1 liquidável; cliente SA1 não bloqueado; natureza SED cadastrada.
Próximos passos: guardar E1_NUMLIQ gerado para eventual /_cancelar.

clientestring · obrigatórioSA1.A1_COD

Código do cliente.

lojastring · obrigatórioSA1.A1_LOJA

Loja do cliente.

naturezastring · obrigatórioSED.ED_CODIGO

Natureza financeira.

tipostring · obrigatórioSE1.E1_TIPO

Tipo do título (RC, NF…).

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

RECNO do título origem.

liquidar-multiplos-titulos

POST /_liquidar

Uso típico em produção — agrupa N títulos do mesmo cliente numa única liquidação.

Quando usar: recebimento consolidado (transferência única referente a várias parcelas / notas).
Pré-condições: todos os RECNOs apontam para títulos do mesmo cliente/loja informados no cabeçalho; títulos liquidáveis.
Validação: RECNO inválido / título não encontrado interrompe o processamento e retorna 422.

clientestring · obrigatórioSA1.A1_COD

Código do cliente.

lojastring · obrigatórioSA1.A1_LOJA

Loja do cliente.

naturezastring · obrigatórioSED.ED_CODIGO

Natureza financeira.

tipostring · obrigatórioSE1.E1_TIPO

Tipo do título gerado.

condicaostring · opcional

Condição de pagamento.

moedainteger · opcional

Default 1 (Real).

titulos[]array<TituloRecno> · obrigatório

2+ itens {recno}.

cancelar-liquidacao

POST /_cancelar

Estorna uma liquidação já gerada.

Quando usar: liquidação digitada por engano, recebimento estornado pelo banco.
Pré-condições: liquidação existente (E1_NUMLIQ conhecido); na mesma filial origem quando filialOrigem for informado.
Resultado: 200 OK e os títulos voltam ao estado anterior à liquidação.

numeroLiquidacaostring · obrigatórioSE1.E1_NUMLIQ

Número da liquidação a cancelar.

filialOrigemstring · opcional

Filial origem (sentinela cAutoFil).

Pendências conhecidas (rev1)

Identificação por RECNO acopla integração ao layout físico. A entrada titulos[].recno exige que o consumidor descubra o RECNO do título origem (consulta SE1 ou endpoint dedicado). 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.

Smoke happy-path depende de RECNO real. O script test-liquidacao-receber.sh cobre apenas negativos por default; happy-path precisa --recno N1 --recno N2 com RECNOs válidos da base. Refinar para descobrir RECNO automaticamente via cliente sentinel no próximo ciclo.

Sem GET de consulta. Endpoint de processo; não expõe consulta direta da liquidação gerada (apenas o E1_NUMLIQ retornado pelo cliente, via consulta na SE1). Avaliar GET _byNumLiq em revisão futura conforme demanda do front.