rev1-2026-05-04 Protheus 12.1.33

BaixaReceber

Endpoint REST para baixa de títulos a receber (tabela SE1) via MsExecAuto FINA070. Aceita um ou mais títulos por requisição; o servidor processa cada um individualmente e devolve resultado por linha (sucesso ou erro), permitindo execução parcial atômica por título.

Bloqueio TOTVS: endpoint de processo (baixa via FINA070), sem MSBLQL — bloqueio relevante esta no cliente (SA1).

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

Vinculação com o ERP

Tabela mestre SE1 Títulos a receber

Rotina automática FINA070 MsExecAuto · baixa manual

Wrapper AdvPL U_FN070Exe src/lib/FN070EXC.prw

Operações & modos

POST baixa (op única)

Dependências de ambiente

Módulo

SIGAFIN (Financeiro)

módulo Financeiro habilitado para empresa/filial alvo
rotina FINA070 presente no RPO

Cadastro

Título existente (SE1)

chave composta E1_PREFIXO + E1_NUM + E1_PARCELA + E1_TIPO
E1_SALDO > 0 — não pode baixar título já quitado

Build

Protheus 7.00.240223P+

build mínimo validado; MsExecAuto em thread REST
sem RpcSetEnv/RpcClearEnv (contexto vem da URL)

Convenções

Modelo de payload — array de arrays de campos ExecAuto. O corpo não é um objeto plano com pares campo:valor; espelha a estrutura do aArray consumido pelo MsExecAuto FINA070: cada título é um array de objetos {campo, tipo, valor}, e Titulos é o array desses arrays. O atributo tipo é obrigatório em cada campo e dispara a conversão AdvPL correspondente (C=Caractere, N=Numérico, D=Data).

Identificação do título. Os campos E1_PREFIXO, E1_NUM, E1_PARCELA e E1_TIPO compõem a chave composta da SE1 e são obrigatórios em cada item de Titulos. Ausência ou erro de padding (índice SE1 exige PadR nos componentes) provoca rejeição da linha com mensagem "Titulo nao encontrado…".

Campos da baixa. AUTVALREC (valor da baixa, N) é o único campo obrigatório além da identificação. Não pode exceder E1_SALDO; ultrapassar provoca erro do MsExecAuto. AUTDTBAIXA e AUTDTCREDITO são opcionais e defaultam para dDataBase do servidor quando omitidos.

Formato de datas. Campos com tipo: "D" aceitam string no formato YYYYMMDD (convertida via SToD) ou DD/MM/YYYY (fallback via CToD). Não aceita objeto Date nem timestamp epoch.

Semântica de HTTP — execução parcial atômica. 200 quando todos os títulos foram baixados com sucesso; 207 Multi-Status quando alguns deram certo e outros falharam (a resposta detalha cada linha); 422 quando nenhum título foi baixado (todas as linhas falharam) ou quando o envelope é semanticamente inválido; 400 para JSON malformado; 500 para exceção interna não tratada.

Idempotência. A operação não é idempotente: enviar o mesmo payload duas vezes baixa o título duas vezes (até esgotar E1_SALDO) e gera dois registros SE5 de movimento. O cliente é responsável por deduplicar (chave de idempotência externa ou conferência prévia de E1_SALDO).

Fixtures sentinelas. O smoke test usa E1_PREFIXO="TST" e E1_NUM com sufixo _TEST_, permitindo identificar e limpar resíduos manualmente na SE1 em caso de interrupção. Fixture de referência: fixtures/baixa.json.

Baixa

Baixa em lote de títulos a receber via FINA070

POST /WsBaixaReceber/ Baixa um ou mais títulos a receber

Descrição

Processa a baixa de um ou mais títulos a receber em uma única requisição. Para cada item de Titulos:

Converte o array de {campo, tipo, valor} para o aArray aceito pelo MsExecAuto FINA070 (conversão dirigida por tipo).
Delega ao wrapper U_FN070Exe, que valida existência do título na SE1, saldo e valor antes de executar a baixa.
Acumula o resultado individual (sucesso/erro + RecNo + mensagem) para compor a resposta consolidada.

Não há transação global ao redor dos títulos — cada um é baixado (ou rejeitado) de forma independente. Use 207 como sinal de execução parcial.

Request body

application/json BaixaReceberRequest · obrigatório

Envelope com Filial e o array Titulos. Schema completo em BaixaReceberRequest.

Baixa de um único título — payload mínimo com identificação completa (prefixo, número, parcela, tipo), valor, data de baixa e data de crédito. Fixture: fixtures/baixa.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Titulos": [
    [
      { "campo": "E1_PREFIXO",   "tipo": "C", "valor": "TST" },
      { "campo": "E1_NUM",       "tipo": "C", "valor": "000001_TEST_" },
      { "campo": "E1_PARCELA",   "tipo": "C", "valor": "001" },
      { "campo": "E1_TIPO",      "tipo": "C", "valor": "NF" },
      { "campo": "AUTVALREC",    "tipo": "N", "valor": 100.00 },
      { "campo": "AUTDTBAIXA",   "tipo": "D", "valor": "20260504" },
      { "campo": "AUTDTCREDITO", "tipo": "D", "valor": "20260504" }
    ]
  ]
}

Baixa em lote — dois títulos — exemplo realista com dois títulos de prefixos diferentes processados em uma única chamada. O servidor responde com 200 se ambos forem baixados.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Titulos": [
    [
      { "campo": "E1_PREFIXO", "tipo": "C", "valor": "TST" },
      { "campo": "E1_NUM",     "tipo": "C", "valor": "000001_TEST_" },
      { "campo": "E1_PARCELA", "tipo": "C", "valor": "001" },
      { "campo": "E1_TIPO",    "tipo": "C", "valor": "NF" },
      { "campo": "AUTVALREC",  "tipo": "N", "valor": 100.00 }
    ],
    [
      { "campo": "E1_PREFIXO", "tipo": "C", "valor": "TST" },
      { "campo": "E1_NUM",     "tipo": "C", "valor": "000002_TEST_" },
      { "campo": "E1_PARCELA", "tipo": "C", "valor": "001" },
      { "campo": "E1_TIPO",    "tipo": "C", "valor": "NF" },
      { "campo": "AUTVALREC",  "tipo": "N", "valor": 250.50 }
    ]
  ]
}

Lote com falha parcial — segundo título com número inexistente força o servidor a responder 207 Multi-Status: linha 1 ok, linha 2 com mensagem "Titulo nao encontrado…".

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Titulos": [
    [
      { "campo": "E1_PREFIXO", "tipo": "C", "valor": "TST" },
      { "campo": "E1_NUM",     "tipo": "C", "valor": "000001_TEST_" },
      { "campo": "E1_PARCELA", "tipo": "C", "valor": "001" },
      { "campo": "E1_TIPO",    "tipo": "C", "valor": "NF" },
      { "campo": "AUTVALREC",  "tipo": "N", "valor": 100.00 }
    ],
    [
      { "campo": "E1_PREFIXO", "tipo": "C", "valor": "TST" },
      { "campo": "E1_NUM",     "tipo": "C", "valor": "999999" },
      { "campo": "E1_PARCELA", "tipo": "C", "valor": "001" },
      { "campo": "E1_TIPO",    "tipo": "C", "valor": "NF" },
      { "campo": "AUTVALREC",  "tipo": "N", "valor": 50.00 }
    ]
  ]
}

Respostas

200

Todos os títulos baixados com sucesso. Envelope BaixaReceberResponse com success: true e data.erros = 0. Tier: happy-path.

207

Multi-status — alguns títulos baixados, outros com erro. success: false, data.titulos[] detalha cada linha. Tier: edge-valid.

400

JSON inválido, body ausente ou vazio. Envelope ErroResponse. Tier: validation-error.

422

Array Titulos ausente/vazio, ou todos os títulos falharam no MsExecAuto. Tier: business-error.

500

Exceção não tratada (falha em FWJsonDeserialize, lock, etc). Tier: business-error.

Exemplo de resposta — 200

Response · 200 OKapplication/json

{
  "success": true,
  "message": "Todos os titulos baixados com sucesso.",
  "data": {
    "total": 1,
    "ok": 1,
    "erros": 0,
    "titulos": [
      {
        "linha": 1,
        "ok": true,
        "recno": 1234,
        "msg": "Baixa realizada com sucesso."
      }
    ]
  }
}

Response · 207 Multi-Statusapplication/json

{
  "success": false,
  "message": "Processamento finalizado com erros parciais.",
  "data": {
    "total": 2,
    "ok": 1,
    "erros": 1,
    "titulos": [
      {
        "linha": 1,
        "ok": true,
        "recno": 1234,
        "msg": "Baixa realizada com sucesso."
      },
      {
        "linha": 2,
        "ok": false,
        "recno": 0,
        "msg": "Titulo nao encontrado na base de dados. Prefixo=TST Num=999999 Parcela=001 Tipo=NF"
      }
    ]
  }
}

Schemas

Definições canônicas — campos com origem SE1 / FINA070 rastreável

BaixaReceberRequest

object · envelope

Envelope da requisição. Filial identifica o contexto Protheus (espelha o segmento da URL /api/99/01); Titulos é o array de títulos a baixar, cada item um TituloArray.

Filialstring · obrigatório

Código da filial Protheus (ex: "01"). Atualmente herdado da URL — mantido no payload por compatibilidade com integrações multi-filial.

Titulosarray<TituloArray> · obrigatório

Lista de títulos a baixar. minItems: 1. Cada item é um TituloArray.

TituloArray

array<CampoTitulo>

Array de campos ExecAuto descrevendo um título a baixar. minItems: 5 — pelo menos a identificação (E1_PREFIXO, E1_NUM, E1_PARCELA, E1_TIPO) e o valor (AUTVALREC) devem estar presentes. Cada elemento é um CampoTitulo.

E1_PREFIXOstring · obrigatórioSE1.E1_PREFIXO

Prefixo do título (componente 1 da chave composta).

E1_NUMstring · obrigatórioSE1.E1_NUM

Número do título (componente 2). Em fixtures de teste, sufixo _TEST_ facilita identificação.

E1_PARCELAstring · obrigatórioSE1.E1_PARCELA

Parcela do título (componente 3). Default usual "001".

E1_TIPOstring · obrigatórioSE1.E1_TIPO

Tipo do título (componente 4). Ex: "NF", "DP", "BOL".

AUTVALRECnumber · obrigatório

Valor da baixa. Não pode exceder E1_SALDO.

AUTDTBAIXAstring (date) · opcional

Data da baixa. YYYYMMDD ou DD/MM/YYYY. Default: dDataBase.

AUTDTCREDITOstring (date) · opcional

Data de crédito. Mesmo formato de AUTDTBAIXA.

AUTDESCRIstring · opcional

Histórico/descrição da baixa.

AUTCODBARstring · opcional

Código de barras (quando aplicável).

CampoTitulo

object

Tripla {campo, tipo, valor} aceita pelo MsExecAuto FINA070. tipo dirige a conversão AdvPL no servidor.

campostring · obrigatório

Nome do campo ExecAuto. E1_* identificam o título; AUT* informam dados da baixa.

tipostring · obrigatório

Tipo de conversão AdvPL aplicada ao valor.

CND

valorstring | number · obrigatório

Valor do campo. String para C e D; número para N (também aceita string numérica via Val()).

BaixaReceberResponse

object · envelope

Envelope padrão da resposta de sucesso (200) e multi-status (207). success é true apenas quando todos os títulos foram baixados.

successboolean · obrigatório

true = todos os títulos baixados; false = pelo menos um título falhou.

messagestring · obrigatório

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

dataBaixaReceberData · obrigatório

Detalhe consolidado da execução. Schema: BaixaReceberData.

BaixaReceberData

object

Sumário e detalhamento por título. Permite ao cliente decidir o que reprocessar sem precisar parsear mensagens.

totalinteger · obrigatório

Total de títulos processados (= len(Titulos)).

okinteger · obrigatório

Quantidade de títulos baixados com sucesso.

errosinteger · obrigatório

Quantidade de títulos com erro. Invariante: ok + erros == total.

titulosarray<TituloResultado> · obrigatório

Detalhe individual de cada título (mesma ordem da requisição). Schema: TituloResultado.

TituloResultado

object

Resultado individual de uma linha de Titulos. A ordem é preservada — linha espelha a posição original (1-based) no array de entrada.

linhainteger · obrigatório

Posição do título no array de entrada (1-based).

okboolean · obrigatório

true = baixa efetuada; false = título rejeitado (não encontrado, saldo insuficiente, valor inválido, etc).

recnointeger · obrigatórioSE1.R_E_C_N_O_

RecNo do registro SE1 após a baixa (0 em caso de erro). Útil para auditoria.

msgstring · obrigatório

Mensagem de sucesso ou descrição técnica do erro (incluindo, quando aplicável, o conteúdo do NomeAutoLog do FINA070).

ErroResponse

object · envelope

Envelope de erros 400 / 422 / 500. Usado quando a requisição não chega a entrar no loop de títulos (JSON inválido, envelope ausente, exceção fatal). Erros por título usam BaixaReceberResponse com status 207 ou 422.

successboolean · const: false

Sempre false.

messagestring · obrigatório

Mensagem editorial do erro.

datastring · opcional

Token interno ou string vazia. Em 400, pode conter o offset do parser JSON.