rev2-2026-05-13 Protheus 12.1.33

ContasReceber

CRUD de Título a Receber (tabela SE1) via rotina automática FINA040 (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 SE1 com 7 partes: filial-prefixo-num-parcela-tipo-cliente-loja. No POST sem {key} o servidor gera E1_NUM via GetSXENum (avança SX8 em caso de gap). Esta revisão adiciona validação de domínio (fValDom) sobre E1_FLUXO antes do FINA040.

Bloqueio TOTVS: a SE1 nao expoe MSBLQL/MSBLQD; o bloqueio relevante esta em SA1 (cliente) e e enforcado pelo proprio FINA040.

Vinculação com o ERP

Tabela mestre SE1 Contas a Receber (títulos)

Rotina automática FINA040 MsExecAuto · Financeiro

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

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro · obrigatório

Cliente (SA1)

o par cliente/loja precisa existir em SA1 e não pode estar bloqueado (A2_MSBLQL != "1").
Sem cliente, FINA040 rejeita com "Cliente inexistente".

Cadastro · condicional

Natureza financeira (SED)

quando E1_NATUREZ é informada, o código precisa existir em SED.

Parametrização · obrigatório

Tipo de título (E1_TIPO)

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

Dominio · combobox

E1_FLUXO (Pertence "SN")

static fValDom valida E1_FLUXO antes do FINA040.
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 (E1_NUM)

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

Quirk · FINA040

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| FINA040(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 "/WsContasReceber/{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-cliente-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 cliente (sem nota fiscal). Em PA o E1_NATUREZ tipicamente referencia uma natureza de adiantamento, e o título já nasce com E1_SALDO = E1_VALOR aguardando baixa contra a nota futura.

Whitelist única. POST e PUT compartilham o mesmo conjunto CAMPOS_ALLOW (13 campos: E1_NATUREZ, E1_EMISSAO, E1_VENCTO, E1_VENCREA, E1_VALOR, E1_HIST, E1_PORTADO, E1_AGEDEP, E1_CONTA, E1_X_PRJTO, E1_X_TASK, E1_FLUXO, E1_ORIGEM). Campo-chave (filial/prefixo/num/parcela/tipo/cliente/loja) não é alterável; para mudar a chave, faça DELETE + POST. Diferente do WsSE2, onde o PUT é restrito a 4 campos.

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

E1_FILIAL nunca vai no array do MsExecAuto em UPDATE/DELETE. O caller posiciona SE1 antes da chamada e FINA040 usa xFilial("SE1") internamente. Passar E1_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 FINA040 modo 5 marca o registro com D_E_L_E_T_='*' (soft-delete TOTVS) — o slot do índice único SE1990_UNQ continua ocupado. Logo, recriar título com chave idêntica (mesma filial/prefixo/num/parcela/tipo/cliente/loja) falha com 422 até purge físico. Em smoke tests, use num diferente ou parcela diferente entre execuções.

Formato de datas. Campos E1_EMISSAO, E1_VENCTO, E1_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.

ContasReceber

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

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

Descrição

Inclui um título a receber via FINA040 em modo 3 (MODEL_OPERATION_INSERT). O servidor gera E1_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.
E1_FLUXO validado contra o domínio do SX3 (Pertence "SN") antes do FINA040.
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/WsContasReceber/INCLUIR
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "cliente": "000002",
  "loja": "01",
  "E1_NATUREZ": "201",
  "E1_EMISSAO": "20991231",
  "E1_VENCTO": "20991231",
  "E1_VALOR": 99.99,
  "E1_HIST": "TESTE_REST CONTAS A PAGAR"
}

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

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "cliente": "000002",
  "loja": "01",
  "E1_NATUREZ": "201",
  "E1_EMISSAO": "20991231",
  "E1_VENCTO": "20991231",
  "E1_VALOR": 99.99,
  "E1_HIST": "TESTE_REST FLUXO S",
  "E1_FLUXO": "S"
}

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

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "cliente": "000002",
  "loja": "01",
  "E1_NATUREZ": "201",
  "E1_EMISSAO": "20991231",
  "E1_VENCTO": "20991231",
  "E1_VALOR": 99.99,
  "E1_HIST": "TESTE_REST FLUXO INVALIDO",
  "E1_FLUXO": "X"
}

Response · 422application/json

{
  "success": false,
  "message": "E1_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+cliente+loja) com soft-delete em SE1990_UNQ ainda ocupando o slot. Tier business-error.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "prefixo": "TST",
  "parcela": "001",
  "tipo": "NF",
  "cliente": "000002",
  "loja": "01",
  "E1_EMISSAO": "20991231",
  "E1_VENCTO": "20991231",
  "E1_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, cliente, loja). Tier: validation-error.

409

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

422

Validação de domínio (fValDom) ou rejeição do FINA040 — E1_FLUXO fora de "SN", cliente 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 /WsContasReceber/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 cliente, 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 SE1 (chave composta)

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

Request body

application/json TituloPayload · obrigatório

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

NF externa do cliente — 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/WsContasReceber/INCLUIR/01-TST-999998-001-NF-000002-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E1_NATUREZ": "201",
  "E1_EMISSAO": "20991231",
  "E1_VENCTO": "20991231",
  "E1_VALOR": 250.00,
  "E1_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/cliente/loja)." Tier: business-error.

422

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

500

Erro interno.

PUT /WsContasReceber/ALTERAR/{key} Altera título (FINA040 modo 4)

Descrição

Altera campos do título via FINA040 em modo 4 (MODEL_OPERATION_UPDATE). Whitelist única — PUT aceita o mesmo conjunto de CAMPOS_ALLOW do POST (13 campos não-chave). Campo-chave (filial/prefixo/num/parcela/tipo/ cliente/loja) não é alterável; para mudar a chave use DELETE + POST. E1_FILIAL nunca entra no array em UPDATE — ver Convenções.

Path parameter

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

7 partes separadas por hífen.

Request body

application/json TituloPayload · obrigatório

Mesmo schema do POST — PUT unificado. Ver TituloPayload.

Alteracao valor + vencimento real — cenario smoke tipico. 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/WsContasReceber/ALTERAR/01-TST-000123-001-NF-000002-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E1_VALOR": 199.99,
  "E1_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 FINA040 — natureza inexistente, valor inválido, regra de negócio violada. Tier: business-error.

500

Erro interno.

DEL /WsContasReceber/EXCLUIR/{key} Exclui título (FINA040 modo 5)

Descrição

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

Título sem baixa parcial (E1_SALDO == E1_VALOR).
Sem movimentação contábil/bancária pendente.
Cliente 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 SE1 (chave composta)

7 partes separadas por hífen.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao — soft-delete via FINA040 modo 5.

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsContasReceber/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, cliente bloqueado. Tier: business-error.

500

Erro interno.

GET /WsContasReceber/{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 SE1: E1_FILIAL+E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO+E1_CLIENTE+E1_LOJA). Cada parte é preenchida com PadR no TamSX3 correspondente antes do DbSeek. Aplica whitelist de CAMPOS_GET (cabeçalho da SE1, sem o detalhe de movimento da SE5).

Path parameter

key string · path · obrigatório SE1 (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/WsContasReceber/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 /WsContasReceber/_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/WsContasReceber/_byid?tipo=recno&valor=12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Busca por msuid — requer E1_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/WsContasReceber/_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 E1_MSUID no dicionário.

500

Erro interno.

Listagem

Paginação por filtros e delta-sync

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

Descrição

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

orderBy=chave (default) — usa o índice 1 da SE1; 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 SE1.E1_FILIAL

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

prefixo string · query · opcional SE1.E1_PREFIXO

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

num string · query · opcional SE1.E1_NUM

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

cliente string · query · opcional SE1.E1_CLIENTE

Código do cliente.

loja string · query · opcional SE1.E1_LOJA

Loja do cliente.

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/WsContasReceber/_list?page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Listagem filtrada por cliente — usa o indice 1 da SE1 e percorre enquanto cliente+loja casam.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsContasReceber/_list?cliente=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/WsContasReceber/_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 SE1 + ids técnicos.

E1_FILIALstringSE1.E1_FILIAL

Filial do título.

E1_PREFIXOstringSE1.E1_PREFIXO

Prefixo do título (categoria/origem).

E1_NUMstringSE1.E1_NUM

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

E1_PARCELAstringSE1.E1_PARCELA

Parcela.

E1_TIPOstringSE1.E1_TIPO

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

E1_CLIENTEstringSE1.E1_CLIENTE

Código do cliente.

E1_LOJAstringSE1.E1_LOJA

Loja do cliente.

E1_NATUREZstringSE1.E1_NATUREZ

Natureza financeira (SED).

E1_EMISSAOstringSE1.E1_EMISSAO

Data de emissão (YYYYMMDD).

E1_VENCTOstringSE1.E1_VENCTO

Vencimento contratual.

E1_VENCREAstringSE1.E1_VENCREA

Vencimento real.

E1_VALORnumberSE1.E1_VALOR

Valor original.

E1_SALDOnumberSE1.E1_SALDO

Saldo aberto.

E1_HISTstringSE1.E1_HIST

Histórico do título.

recnointeger

Id técnico do registro.

msuidstring

MS_UID, quando o dicionário expõe E1_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, cliente, loja) podem vir tanto no path ({key}) quanto no body — path sempre vence.

filialstring · obrigatório*SE1.E1_FILIAL

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

prefixostring · obrigatório*SE1.E1_PREFIXO

Prefixo.

numstring · opcionalSE1.E1_NUM

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

parcelastring · obrigatório*SE1.E1_PARCELA

Parcela ("001" para única).

tipostring · obrigatório*SE1.E1_TIPO

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

clientestring · obrigatório*SE1.E1_CLIENTE

Cliente (SA1).

lojastring · obrigatório*SE1.E1_LOJA

Loja do cliente.

E1_NATUREZstring · opcionalSE1.E1_NATUREZ

Natureza financeira (SED).

E1_EMISSAOstring (date) · opcionalSE1.E1_EMISSAO

Emissão, YYYYMMDD.

E1_VENCTOstring (date) · opcionalSE1.E1_VENCTO

Vencimento contratual, YYYYMMDD.

E1_VENCREAstring (date) · opcionalSE1.E1_VENCREA

Vencimento real (FINA040 calcula se omitido).

E1_VALORnumber · opcionalSE1.E1_VALOR

Valor (> 0).

E1_HISTstring · opcionalSE1.E1_HIST

Histórico.

E1_PORTADOstring · opcionalSE1.E1_PORTADO

Banco portador.

E1_AGEDEPstring · opcionalSE1.E1_AGEDEP

Agência.

E1_CONTAstring · opcionalSE1.E1_CONTA

Conta.

E1_FLUXOstring · opcionalSE1.E1_FLUXO

Gera fluxo de caixa. Validado por fValDom.

SN

E1_ORIGEMstring · opcionalSE1.E1_ORIGEM

Origem (sistema externo / módulo).

E1_X_PRJTOstring · opcionalSE1.E1_X_PRJTO

Campo customizado (projeto).

E1_X_TASKstring · opcionalSE1.E1_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) — no WsSE1, mesmo conjunto de campos do POST (PUT unificado). Campos editáveis: E1_NATUREZ, E1_EMISSAO, E1_VENCTO, E1_VENCREA, E1_VALOR, E1_HIST, E1_PORTADO, E1_AGEDEP, E1_CONTA, E1_X_PRJTO, E1_X_TASK, E1_FLUXO, E1_ORIGEM. Campo fora desta lista é silenciosamente ignorado pelo FINA040. Para alterar fornecedor/prefixo/num/parcela/tipo, faça DELETE + POST.

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.

clientestring

Cliente.

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 E1_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 FINA040 (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 /WsContasReceber/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 /WsContasReceber/INCLUIR

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

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

incluir-num-forcado

POST /WsContasReceber/INCLUIR/{key}

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

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

erro-fluxo-invalido

POST /WsContasReceber/INCLUIR

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

erro-chave-duplicada

POST /WsContasReceber/INCLUIR

409 -- chave duplicada: tentativa de incluir titulo na mesma chave (filial/prefixo/parcela/tipo/cliente/loja) sendo bloqueada pelo unique index SE1990_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 /WsContasReceber/ALTERAR/{key}

Altera campos do titulo (mesma whitelist CAMPOS_ALLOW do POST — 13 campos) via FINA040 Op=4. Campos-chave no body sao silenciosamente ignorados (path vence).

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

excluir

DELETE /WsContasReceber/EXCLUIR/{key}

Exclui titulo via FINA040 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 cliente bloqueado.

consulta-por-chave

GET /WsContasReceber/{key}

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

byid-recno

GET /WsContasReceber/_byid

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

byid-msuid

GET /WsContasReceber/_byid

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

listagem-paginada

GET /WsContasReceber/_list

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

listagem-filtrada-por-cliente

GET /WsContasReceber/_list

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

delta-sync

GET /WsContasReceber/_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 (rev2)

Cenários FINA040 avançados não cobertos. O CRUD básico desta revisão expõe título "puro". Cenários avançados que o FINA040 suporta mas que ainda não estão no payload (analogia direta à FEAT-WsSE2-complementos-fina050): rateio contábil, rateio de projeto (PMS), abatimento, valores acessórios, PA com cheque, código de retenção. Backlog específico do WsSE1 será aberto em .meta/wip/FEAT-WsSE1-complementos-fina040.md quando houver demanda.

PUT unificado — não há schema restrito. No WsSE1 o PUT aceita o mesmo conjunto de campos do POST (CAMPOS_ALLOW). Diferente do WsSE2, onde o PUT é limitado a 4 campos de negócio. Para alterar fornecedor/prefixo/num/parcela/tipo (campos-chave), continua sendo necessário DELETE + POST — o FINA040 Op=4 não muda a chave do título.

Bloqueio MSBLQL/MSBLQD ainda não aplicado em SE1. O padrão da biblioteca (validado em SA1/SA2/SB1/SB5/SC1) ainda não chegou ao WsSE1. Hoje o PUT em título não-bloqueado opera normal. Quando entrar a onda em SE1, será necessário aceitar PUT apenas em E1_MSBLQL/E1_MSBLQD enquanto o título estiver bloqueado — mesmo contrato do WsSE2.

Soft-delete TOTVS e índice SE1990_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. Mesmo quirk do WsSE2 (SE2990_UNQ). Para reaproveitar a chave, fazer DELETE físico via DBA ou usar nova chave.

Bloqueio do cliente (SA1). SE1 não expõe campos próprios de bloqueio; o FINA040 consulta SA1->A1_MSBLQL e rejeita inclusão de título (422) quando o cliente está bloqueado. Sem semáforo editorial — a rotina decide e devolve a mensagem.