rev3-2026-05-13 Protheus 12.1.33

ContasPagar

CRUD de Título a Pagar (tabela SE2) via rotina automática FINA050 (MsExecAuto). Cobre títulos comuns (NF, PRV, CHQ) e adiantamentos (PA) — o que muda é o tipo do payload. O identificador externo é a chave composta natural da SE2 com 7 partes: filial-prefixo-num-parcela-tipo-fornece-loja. No POST sem {key} o servidor gera E2_NUM via GetSXENum (avança SX8 em caso de gap). Esta revisão adiciona validação de domínio (fValDom) sobre E2_FLUXO antes do FINA050.

Bloqueio TOTVS: a SE2 nao expoe MSBLQL/MSBLQD; o bloqueio relevante esta em SA2 (fornecedor) e e enforcado pelo proprio FINA050.

Vinculação com o ERP

Tabela mestre SE2 Contas a Pagar (títulos)

Rotina automática FINA050 MsExecAuto · Financeiro

Wrapper AdvPL U_FN050Exc src/lib/FIN/FN050EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro · obrigatório

Fornecedor (SA2)

o par fornece/loja precisa existir em SA2 e não pode estar bloqueado (A2_MSBLQL != "1").
Sem fornecedor, FINA050 rejeita com "Fornecedor inexistente".

Cadastro · condicional

Natureza financeira (SED)

quando E2_NATUREZ é informada, o código precisa existir em SED.
U_FN050Exc enriquece E2_CODRET automaticamente via SED->ED_CODRET.

Parametrização · obrigatório

Tipo de título (E2_TIPO)

enum dependente da parametrização: NF, PRV, CHQ, BOL, ...
Para adiantamento ao fornecedor, usar tipo PA (compatível com a tabela SX5/05 do ambiente).

Dominio · combobox

E2_FLUXO (Pertence "SN")

static fValDom valida E2_FLUXO antes do FINA050.
Aceitos: S (gera fluxo de caixa) e N (não). Outros valores retornam 422 com mensagem editorial — sem disparar HELP da rotina.

Sequência

Numeração SX8 (E2_NUM)

GetSXENum("SE2","E2_NUM") + Soma1 + ConfirmSX8 em loop até gap.
Disparada no POST /INCLUIR (sem {key}); retorna data.auto=true.

Quirk · FINA050

Pergunte / closure ExecAuto

o wrapper aplica Pergunte("FIN050",.F.) e força MV_PAR02=2/MV_PAR04=2 (suprime perguntas de rateio/movimento). Closure usa 3 argumentos ({|x,y,z| FINA050(x,y,z)}) — variante com 2 args faz nOpc cair em default 3 e gera erro FA050NUM falso em PUT/DELETE.

Quirk · build 240223P

Dispatcher único de GET

WSMETHOD GET com WSSYNTAX "/WsContasPagar/{path}" + dispatcher AdvPL (_list / _byid / chave). O build não distingue múltiplos GET por WSSYNTAX, então a separação é feita no AdvPL pelo último segmento da URL.

Convenções

Identificador externo — chave composta. A chave é um único parâmetro {key} com 7 partes separadas por hífen: filial-prefixo-num-parcela-tipo-fornece-loja. Exemplo: 01-TST-000123-001-NF-000001-01. Quando o body do POST/PUT traz os mesmos campos, o path sempre vence. Pattern: ^[^-]+-[^-]+-[^-]+-[^-]+-[^-]+-[^-]+-[^-]+$.

Título normal × Adiantamento (PA). O endpoint serve os dois cenários — o que muda é o tipo. NF, PRV, CHQ, BOL representam títulos comuns; PA indica adiantamento a fornecedor (sem nota fiscal). Em PA o E2_NATUREZ tipicamente referencia uma natureza de adiantamento, e o título já nasce com E2_SALDO = E2_VALOR aguardando baixa contra a nota futura.

Whitelist por operação. POST aceita os 17 campos do cadastro completo (TituloPayload); PUT aceita apenas 4 campos editáveis: E2_NATUREZ, E2_VENCREA, E2_VALOR, E2_HIST (TituloPayloadPut). Campo fora do whitelist no PUT é silenciosamente ignorado — FINA050 não toca o registro. Para mudar valor de campo travado é preciso DELETE + POST de uma nova parcela.

Validação de domínio no POST/PUT. E2_FLUXO aceita apenas "S" ou "N" (Pertence "SN" do SX3). Static fValDom rejeita valores fora do domínio com 422 antes do FINA050, devolvendo mensagem clara em vez do HELP opaco da rotina: "E2_FLUXO invalido: 'X'. Aceitos: S (Sim, gera fluxo de caixa), N (Nao).". Campo não informado / vazio é aceito (default do dicionário).

E2_FILIAL nunca vai no array do MsExecAuto em UPDATE/DELETE. O caller posiciona SE2 antes da chamada e FINA050 usa xFilial("SE2") internamente. Passar E2_FILIAL em nOper=4 ou nOper=5 reentra em FA050INCLU e dispara o erro "Numero titulo ja existe" (FA050NUM) de forma espúria. Esta restrição vem da build atual (240223P/PRX 04/09/2025).

Soft-delete & unique index. A exclusão via FINA050 modo 5 marca o registro com D_E_L_E_T_='*' (soft-delete TOTVS) — o slot do índice único SE2990_UNQ continua ocupado. Logo, recriar título com chave idêntica (mesma filial/prefixo/num/parcela/tipo/fornece/loja) falha com 422 até purge físico. Em smoke tests, use num diferente ou parcela diferente entre execuções.

Formato de datas. Campos E2_EMISSAO, E2_VENCTO, E2_VENCREA aceitam string YYYYMMDD (8 dígitos, sem separadores) no payload. A conversão interna usa SToD(AllTrim(valor)). Em qualquer GET, datas voltam serializadas pelo U_RestMontaRegistro.

Paginação e delta-sync. /_list usa page/pageSize (default 50, máx 500) com orderBy=chave. Para sincronização incremental, alterne para orderBy=recno e use cursor conforme o nextCursor retornado. Em orderBy=chave, since filtra RecNo() < since.

ContasPagar

CRUD por chave composta — título normal e adiantamento (PA)

POST /WsContasPagar/INCLUIR Inclui título (servidor gera num via GetSXENum)

Descrição

Inclui um título a pagar via FINA050 em modo 3 (MODEL_OPERATION_INSERT). O servidor gera E2_NUM via GetSXENum + Soma1 em loop até encontrar gap livre na chave. Retorna a chave técnica completa em data, com auto: true.

Para título comum (NF/PRV/CHQ), informe o tipo usual da parametrização.
Para adiantamento (sem nota), use tipo: "PA" — mesmo endpoint, mesmo payload.
E2_FLUXO validado contra o domínio do SX3 (Pertence "SN") antes do FINA050.
Whitelist completa: ver TituloPayload.

Request body

application/json TituloPayload · obrigatório

Payload plano com chave de negócio (sem num) + campos do whitelist. Schema completo em TituloPayload.

Cenario 1 — Inclusao simples (NF). Payload completo com natureza e historico. Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "fornece": "000002",
  "loja": "01",
  "E2_NATUREZ": "201",
  "E2_EMISSAO": "20991231",
  "E2_VENCTO": "20991231",
  "E2_VALOR": 99.99,
  "E2_HIST": "TESTE_REST CONTAS A PAGAR"
}

Cenario 2 — Com fluxo de caixa. Titulo com E2_FLUXO="S" (gera fluxo). fValDom aceita; FINA050 grava. Fixture: fixtures/post-fluxo-valido-s.json.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "fornece": "000002",
  "loja": "01",
  "E2_NATUREZ": "201",
  "E2_EMISSAO": "20991231",
  "E2_VENCTO": "20991231",
  "E2_VALOR": 99.99,
  "E2_HIST": "TESTE_REST FLUXO S",
  "E2_FLUXO": "S"
}

Cenario 3 — 422 dominio (E2_FLUXO invalido). fValDom rejeita antes do FINA050. Fixture: fixtures/post-fluxo-invalido.json.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "fornece": "000002",
  "loja": "01",
  "E2_NATUREZ": "201",
  "E2_EMISSAO": "20991231",
  "E2_VENCTO": "20991231",
  "E2_VALOR": 99.99,
  "E2_HIST": "TESTE_REST FLUXO INVALIDO",
  "E2_FLUXO": "X"
}

Response · 422application/json

{
  "success": false,
  "message": "E2_FLUXO invalido: 'X'. Aceitos: S (Sim, gera fluxo de caixa), N (Nao).",
  "data": ""
}

Cenario 4 — 409 chave duplicada. POST repetido na mesma chave de negocio (mesmo prefixo+parcela+tipo+fornece+loja) com soft-delete em SE2990_UNQ ainda ocupando o slot. Tier business-error.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "fornece": "000002",
  "loja": "01",
  "E2_EMISSAO": "20991231",
  "E2_VENCTO": "20991231",
  "E2_VALOR": 99.99
}

Respostas

201

Título incluído. Envelope CrudResponse com data = TituloRef (chave de negócio resolvida + auto: true + ids técnicos).

400

Body JSON ausente/inválido, campo-chave obrigatório vazio (filial, prefixo, parcela, tipo, fornece, loja). Tier: validation-error.

409

Tentativa de incluir título com chave já existente (mesmo prefixo/parcela/tipo/fornece/loja) bloqueada pelo unique index SE2990_UNQ. Tier: business-error.

422

Validação de domínio (fValDom) ou rejeição do FINA050 — E2_FLUXO fora de "SN", fornecedor inexistente/bloqueado, natureza inválida, valor zerado, vencimento < emissão, etc. Mensagem editorial em message. Tier: business-error.

500

Erro interno (DbSeek, deserialização, exceção AdvPL).

POST /WsContasPagar/INCLUIR/{key} Inclui título com num forçado pelo cliente

Descrição

Variante do POST em que o cliente impõe a chave completa via path (incluindo num). Útil para integrações que precisam preservar o número de origem (NF do fornecedor, número externo do sistema consumidor). Se a chave já existir, retorna 409 sem tocar no registro existente.

O path sempre vence sobre o body. Os 7 segmentos do path substituem os campos correspondentes do payload — o body só precisa carregar os campos não-chave (valor, vencimento, natureza, histórico).

Path parameter

key string · path · obrigatório SE2 (chave composta)

7 partes: filial-prefixo-num-parcela-tipo-fornece-loja. Pattern: ^[^-]+-[^-]+-[^-]+-[^-]+-[^-]+-[^-]+-[^-]+$.

Request body

application/json TituloPayload · obrigatório

Campos-chave no body são ignorados (path vence). Schema em TituloPayload.

NF externa do fornecedor — preserva o número da nota como num. Body so traz campos nao-chave (path domina o resto).

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsContasPagar/INCLUIR/01-TST-999998-001-NF-000002-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E2_NATUREZ": "201",
  "E2_EMISSAO": "20991231",
  "E2_VENCTO": "20991231",
  "E2_VALOR": 250.00,
  "E2_HIST": "NF EXTERNA 999998"
}

Respostas

201

Título incluído com num forçado. data.auto = false.

400

Chave composta inválida (≠ 7 partes), body ausente. Tier: validation-error.

409

Título já existe nessa chave. Mensagem: "Titulo ja existe nesta chave (filial/prefixo/num/parcela/tipo/fornece/loja)." Tier: business-error.

422

fValDom (E2_FLUXO fora de "SN") ou rejeição do FINA050 (mesmas causas do POST sem key).

500

Erro interno.

PUT /WsContasPagar/ALTERAR/{key} Altera título (FINA050 modo 4)

Descrição

Altera campos do título via FINA050 em modo 4 (MODEL_OPERATION_UPDATE). Escopo de negócio reduzido: apenas 4 campos entram no array do MsExecAuto:

E2_NATUREZ — natureza financeira
E2_VENCREA — vencimento real
E2_VALOR — valor do título
E2_HIST — histórico

Campo fora do whitelist é silenciosamente ignorado. Para alterar campo travado (fornecedor, número, tipo, prefixo, parcela) use DELETE + POST. E2_FILIAL nunca entra no array em UPDATE — ver Convenções.

Path parameter

key string · path · obrigatório SE2 (chave composta)

7 partes separadas por hífen.

Request body

application/json TituloPayloadPut · obrigatório

Subconjunto dos 4 campos editáveis. Schema em TituloPayloadPut.

Alteracao valor + vencimento real — cenario smoke tipico (4 campos editaveis). Fixture: fixtures/put-update.json. Campos-chave do body sao ignorados (path vence).

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsContasPagar/ALTERAR/01-TST-000123-001-NF-000002-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E2_VALOR": 199.99,
  "E2_HIST": "TESTE_REST CONTAS A PAGAR ALTERADO"
}

Respostas

200

Título alterado. Envelope CrudResponse.

400

Chave composta ausente/inválida no path, body ausente, JSON malformado. Tier: validation-error.

404

Título não localizado pela chave. Tier: not-found.

422

Rejeição do FINA050 — natureza inexistente, valor inválido, regra de negócio violada. Tier: business-error.

500

Erro interno.

DEL /WsContasPagar/EXCLUIR/{key} Exclui título (FINA050 modo 5)

Descrição

Exclui o título via FINA050 em modo 5 (MODEL_OPERATION_DELETE). Pré-requisitos:

Título sem baixa parcial (E2_SALDO == E2_VALOR).
Sem movimentação contábil/bancária pendente.
Fornecedor não bloqueado.

Soft-delete TOTVS: marca D_E_L_E_T_='*', mantendo o slot do unique index ocupado. Reincluir título com chave idêntica falha até purge físico (ver Convenções).

Path parameter

key string · path · obrigatório SE2 (chave composta)

7 partes separadas por hífen.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao — soft-delete via FINA050 modo 5.

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsContasPagar/EXCLUIR/01-TST-000123-001-NF-000002-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Título excluído. Mensagem: "Titulo excluido com sucesso."

400

Chave ausente/inválida. Tier: validation-error.

404

Título não localizado. Tier: not-found.

422

Exclusão rejeitada — saldo parcial, movimentação pendente, fornecedor bloqueado. Tier: business-error.

500

Erro interno.

GET /WsContasPagar/{key} Consulta cabeçalho do título pela chave composta

Descrição

Retorna o cabeçalho do título posicionado pela chave composta (índice 1 da SE2: E2_FILIAL+E2_PREFIXO+E2_NUM+E2_PARCELA+E2_TIPO+E2_FORNECE+E2_LOJA). Cada parte é preenchida com PadR no TamSX3 correspondente antes do DbSeek. Aplica whitelist de CAMPOS_GET (cabeçalho da SE2, sem o detalhe de movimento da SE5).

Path parameter

key string · path · obrigatório SE2 (chave composta)

7 partes separadas por hífen.

Cenario

Exemplo da requisicao (cenario ativo)

Consulta por chave composta — retorna envelope com data: Titulo.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasPagar/01-TST-000123-001-NF-000002-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Título encontrado. Envelope { success: true, data: Titulo }.

400

Chave composta inválida (≠ 7 partes). Tier: validation-error.

404

Título não localizado para a chave. Tier: not-found.

500

Erro interno.

GET /WsContasPagar/_byid Consulta título por identificador técnico (recno|msuid)

Descrição

Busca o título por id técnico — útil para integrações que persistem recno ou msuid e querem reconfirmar o registro sem decompor a chave de negócio em 7 partes.

Query parameters

tipo string · query · obrigatório

Qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Inteiro positivo para tipo=recno, string para tipo=msuid.

Cenarios

Exemplo da requisicao (cenario ativo)

Busca por recno — id técnico sempre disponível.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasPagar/_byid?tipo=recno&valor=12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Busca por msuid — requer E2_MSUID no dicionário (depende de UPDDISTR de MVC). Sem o campo, retorna 501.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasPagar/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Título encontrado. Envelope { success: true, data: Titulo }.

400

tipo/valor ausentes, tipo fora do enum, valor não numérico para recno.

404

Título não localizado ou fora da filial corrente. Tier: not-found.

501

Busca por msuid requer campo E2_MSUID no dicionário.

500

Erro interno.

Listagem

Paginação por filtros e delta-sync

GET /WsContasPagar/_list Lista títulos por filtros com paginação

Descrição

Lista títulos com filtros por filial, prefixo, num, fornece, loja em dois modos:

orderBy=chave (default) — usa o índice 1 da SE2; paginação por page/pageSize.
orderBy=recno — varre fisicamente (ordem 0); paginação por keyset com cursor/nextCursor. Indicado para sync incremental.

Em orderBy=chave, since descarta registros com RecNo() < since. Em orderBy=recno, cursor retoma logo após o último RecNo retornado.

Query parameters

filial string · query · opcional SE2.E2_FILIAL

Filtro por filial. Default = xFilial("SE2").

prefixo string · query · opcional SE2.E2_PREFIXO

Prefixo do título (filtro exato após trim).

num string · query · opcional SE2.E2_NUM

Número do título (filtro exato).

fornece string · query · opcional SE2.E2_FORNECE

Código do fornecedor.

loja string · query · opcional SE2.E2_LOJA

Loja do fornecedor.

fields string · query · opcional

Lista de campos separados por vírgula. Validados contra CAMPOS_GET.

page integer · query · opcional

Página (default 1, mínimo 1). Só faz sentido com orderBy=chave.

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

orderBy string · query · opcional

Modo de ordenação. Default chave.

chaverecno

since integer · query · opcional

Em orderBy=chave, descarta RecNo() < since.

cursor integer · query · opcional

Em orderBy=recno, retoma após este RecNo (vindo de nextCursor).

Cenarios

Exemplo da requisicao (cenario ativo)

Listagem paginada — default orderBy=chave, pageSize=50.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasPagar/_list?page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Listagem filtrada por fornecedor — usa o indice 1 da SE2 e percorre enquanto fornece+loja casam.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasPagar/_list?fornece=000002&loja=01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Delta-sync — orderBy=recno + cursor retomavel via nextCursor retornado na pagina anterior. since tambem aceito (filtra RecNo < valor).

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasPagar/_list?orderBy=recno&cursor=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de títulos. Envelope com data (array de Titulo), orderBy, pageSize, count, opcionalmente page ou nextCursor conforme o modo.

400

Parâmetro inválido (fields com campo fora do whitelist, pageSize > 500).

500

Erro interno.

Schemas

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

Titulo

object

Representação retornada nos GETs (/{key}, /_list, /_byid). Cabeçalho da SE2 + ids técnicos.

E2_FILIALstringSE2.E2_FILIAL

Filial do título.

E2_PREFIXOstringSE2.E2_PREFIXO

Prefixo do título (categoria/origem).

E2_NUMstringSE2.E2_NUM

Número do título (gerado por GetSXENum no POST sem key).

E2_PARCELAstringSE2.E2_PARCELA

Parcela.

E2_TIPOstringSE2.E2_TIPO

Tipo do título — NF / PRV / CHQ / BOL / PA ... (parametrização SX5/05).

E2_FORNECEstringSE2.E2_FORNECE

Código do fornecedor.

E2_LOJAstringSE2.E2_LOJA

Loja do fornecedor.

E2_NATUREZstringSE2.E2_NATUREZ

Natureza financeira (SED).

E2_EMISSAOstringSE2.E2_EMISSAO

Data de emissão (YYYYMMDD).

E2_VENCTOstringSE2.E2_VENCTO

Vencimento contratual.

E2_VENCREAstringSE2.E2_VENCREA

Vencimento real.

E2_VALORnumberSE2.E2_VALOR

Valor original.

E2_SALDOnumberSE2.E2_SALDO

Saldo aberto.

E2_HISTstringSE2.E2_HIST

Histórico do título.

E2_CCDstringSE2.E2_CCD

Centro de custo do débito.

E2_CODRETstringSE2.E2_CODRET

Código de retenção fiscal.

recnointeger

Id técnico do registro.

msuidstring

MS_UID, quando o dicionário expõe E2_MSUID.

msuidtstring

Timestamp técnico do MS_UID.

TituloPayload

object

Payload aceito em POST (whitelist CAMPOS_ALLOW_POST). Campos-chave (filial, prefixo, num, parcela, tipo, fornece, loja) podem vir tanto no path ({key}) quanto no body — path sempre vence.

filialstring · obrigatório*SE2.E2_FILIAL

Filial. Default = xFilial("SE2") quando omitido.

prefixostring · obrigatório*SE2.E2_PREFIXO

Prefixo.

numstring · opcionalSE2.E2_NUM

Número. Omitido no POST /INCLUIR (servidor gera).

parcelastring · obrigatório*SE2.E2_PARCELA

Parcela ("001" para única).

tipostring · obrigatório*SE2.E2_TIPO

Tipo. NF/PRV/CHQ/BOL/PA...

fornecestring · obrigatório*SE2.E2_FORNECE

Fornecedor (SA2).

lojastring · obrigatório*SE2.E2_LOJA

Loja do fornecedor.

E2_NATUREZstring · opcionalSE2.E2_NATUREZ

Natureza financeira (SED).

E2_EMISSAOstring (date) · opcionalSE2.E2_EMISSAO

Emissão, YYYYMMDD.

E2_VENCTOstring (date) · opcionalSE2.E2_VENCTO

Vencimento contratual, YYYYMMDD.

E2_VENCREAstring (date) · opcionalSE2.E2_VENCREA

Vencimento real (FINA050 calcula se omitido).

E2_VALORnumber · opcionalSE2.E2_VALOR

Valor (> 0).

E2_HISTstring · opcionalSE2.E2_HIST

Histórico.

E2_CCDstring · opcionalSE2.E2_CCD

Centro de custo.

E2_CODRETstring · opcionalSE2.E2_CODRET

Código de retenção.

E2_CODBARstring · opcionalSE2.E2_CODBAR

Código de barras.

E2_PORTADOstring · opcionalSE2.E2_PORTADO

Banco portador.

E2_AGEDEPstring · opcionalSE2.E2_AGEDEP

Agência.

E2_CONTAstring · opcionalSE2.E2_CONTA

Conta.

E2_FLUXOstring · opcionalSE2.E2_FLUXO

Gera fluxo de caixa. Validado por fValDom.

SN

E2_ORIGEMstring · opcionalSE2.E2_ORIGEM

Origem (sistema externo / módulo).

E2_X_PRJTOstring · opcionalSE2.E2_X_PRJTO

Campo customizado (projeto).

E2_X_TASKstring · opcionalSE2.E2_X_TASK

Campo customizado (task).

* Obrigatoriedade dos campos-chave: no POST /INCLUIR sem {key}, os 6 campos não-num são obrigatórios no body. Quando há {key} no path, o body não precisa repeti-los.

TituloPayloadPut

object

Whitelist do PUT (CAMPOS_ALLOW_PUT) — somente 4 campos editáveis. Campo fora desta lista é silenciosamente ignorado.

E2_NATUREZstring · opcionalSE2.E2_NATUREZ

Natureza (SED).

E2_VENCREAstring (date) · opcionalSE2.E2_VENCREA

Reagendamento do vencimento real (YYYYMMDD).

E2_VALORnumber · opcionalSE2.E2_VALOR

Valor do título. Impacta E2_SALDO.

E2_HISTstring · opcionalSE2.E2_HIST

Histórico/descrição.

TituloRef

object

Referência leve à chave do título — devolvida em data nas respostas de POST e PUT. Acrescenta ids técnicos.

filialstring

Filial.

prefixostring

Prefixo.

numstring

Número resolvido (gerado ou forçado).

parcelastring

Parcela.

tipostring

Tipo.

fornecestring

Fornecedor.

lojastring

Loja.

autoboolean

true quando o servidor gerou num (POST sem key); false caso contrário.

recnointeger

RecNo do registro.

msuidstring

MS_UID quando o dicionário tem E2_MSUID.

msuidtstring

Timestamp do MS_UID.

CrudResponse

object · envelope

Envelope padrão de POST/PUT/DELETE. data traz TituloRef em POST/PUT, string vazia em DELETE.

successboolean · const: true

Sempre true em sucesso.

messagestring · obrigatório

Mensagem editorial.

datastring | TituloRef · opcional

Chave resolvida ou string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. Em 422 a message traz a mensagem do NomeAutoLog do FINA050 (ou a mensagem editorial de fValDom quando o erro é de domínio).

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro.

datastring · opcional

Token interno / detalhe técnico.

Cenários

Catálogo de combinações de payload/query reconhecidas pelos métodos. Cada cenário usa o mesmo schema mas demonstra um uso típico distinto. Tier semântico no slug; endpoint no type-pill.

incluir-simples

POST /WsContasPagar/INCLUIR

Inclusao basica de titulo NF -- chave de negocio + valor + emissao/vencto + natureza + historico. num gerado pelo servidor via GetSXENum.

Quando usar: caso de uso padrao do CRUD.

incluir-com-fluxo-caixa

POST /WsContasPagar/INCLUIR

Mesma estrutura do incluir-simples + E2_FLUXO="S" (gera lancamento no fluxo de caixa). fValDom aceita; FINA050 grava.

Quando usar: titulos que devem refletir em projecao de fluxo de caixa.

incluir-num-forcado

POST /WsContasPagar/INCLUIR/{key}

Cliente impoe a chave completa via path (incluindo num). Util para preservar numero externo (NF do fornecedor, ID de sistema integrador). Path vence sobre body.

Quando usar: integracoes que precisam manter o numero de origem.

erro-fluxo-invalido

POST /WsContasPagar/INCLUIR

422 -- dominio: E2_FLUXO fora do Pertence("SN"). Static fValDom rejeita antes do FINA050, devolvendo mensagem clara em vez do HELP opaco. Valores aceitos: S (Sim, gera fluxo de caixa), N (Nao).

erro-chave-duplicada

POST /WsContasPagar/INCLUIR

409 -- chave duplicada: tentativa de incluir titulo na mesma chave (filial/prefixo/parcela/tipo/fornece/loja) sendo bloqueada pelo unique index SE2990_UNQ. Por causa do soft-delete TOTVS, o slot do indice fica ocupado mesmo apos DELETE -- recriar com chave identica falha ate purge fisico. Use num ou parcela distintos.

alterar-valor-e-vencto

PUT /WsContasPagar/ALTERAR/{key}

Altera os 4 campos editaveis do titulo (E2_NATUREZ, E2_VENCREA, E2_VALOR, E2_HIST) via FINA050 Op=4. Campos fora do whitelist sao silenciosamente ignorados.

Quando usar: reagendar vencimento, ajustar valor, trocar natureza ou historico.

excluir

DELETE /WsContasPagar/EXCLUIR/{key}

Exclui titulo via FINA050 Op=5. Soft-delete TOTVS (D_E_L_E_T_='*') -- slot do unique index continua ocupado.

Bloqueio: 422 quando ha saldo parcial, movimentacao pendente ou fornecedor bloqueado.

consulta-por-chave

GET /WsContasPagar/{key}

DbSeek pelo indice 1 da SE2 (chave composta com PadR). Retorna envelope { success, data: Titulo }.

byid-recno

GET /WsContasPagar/_byid

Busca por RecNo() via tipo=recno&valor=N. Identificador tecnico sempre disponivel.

byid-msuid

GET /WsContasPagar/_byid

Busca por E2_MSUID via tipo=msuid&valor=GUID. Requer o campo no dicionario (UPDDISTR de MVC). Sem o campo -> 501.

listagem-paginada

GET /WsContasPagar/_list

Default orderBy=chave + page/pageSize. Paginacao por offset sobre o indice 1 da SE2.

listagem-filtrada-por-fornecedor

GET /WsContasPagar/_list

Filtros fornece + loja percorrem o indice ate o fornecedor mudar. num, prefixo, filial tambem combinaveis.

delta-sync

GET /WsContasPagar/_list

orderBy=recno + cursor retomavel. Cada pagina devolve nextCursor para a proxima chamada. since (RecNo<valor) tambem aceito como filtro de corte.

Quando usar: sincronizacao incremental do consumer (Angular embarcado, integradores externos).

Pendências conhecidas (rev3)

Cenários FINA050 não cobertos. O CRUD básico desta revisão expõe apenas título "puro". Cenários avançados que o FINA050 suporta mas que ainda não estão no payload: complementoTitulo/complementoImpostos (FKF/FKG — INSS, IR retido, dispensa por processo), rateioContabil (CTJ, LP 511), rateioProjeto (PMS · AFR/AF9/AF8), substituição de título provisório (Op=6), abatimento (AB-), valores acessórios (VA), PA com cheque. Backlog consolidado em .meta/wip/FEAT-WsSE2-complementos-fina050.md; cada subtask abre slot próprio sob demanda.

Risco conhecido em E2_CODRET. O campo está na whitelist do POST mas o wrapper ainda não chama SetFunName("FINA050") antes do MsExecAuto, o que pode quebrar o X3_VALID quando o cliente enviar E2_CODRET. Tracking na subtask 7.8 da FEAT acima. Workaround: omitir o campo do payload.

PUT restrito a 4 campos de negócio. Por desenho, o PUT aceita apenas E2_NATUREZ, E2_VENCREA, E2_VALOR e E2_HIST — qualquer outro campo no body é silenciosamente ignorado pelo MsExecAuto (TOTVS). Para alterar fornecedor, prefixo ou número, faça DELETE + POST. Não é bug, é a fronteira do que o FINA050 Op=4 considera mutável.

Bloqueio MSBLQL/MSBLQD ainda não aplicado. O padrão da biblioteca (validado em SA1/SA2/SB1/SB5/SC1) ainda não chegou ao WsSE2. Hoje o PUT em título não-bloqueado opera normal; quando entrar a onda em SE2, vai ser preciso aceitar PUT apenas em E2_MSBLQL/E2_MSBLQD enquanto o título estiver bloqueado.

Soft-delete TOTVS e índice SE2990_UNQ. O DELETE faz soft-delete (D_E_L_E_T_='*'), mas o slot do índice único permanece ocupado no MSSQL — recriar o mesmo título logo após um DELETE pode retornar 409 mesmo o registro não estando mais visível via GET. Para reaproveitar a chave, fazer DELETE físico via DBA ou usar nova chave.