rev1-2026-05-16 Protheus 12.1.33

MovimentoCaixinha (SEU)

CRUD de movimentos de caixinha (tabela SEU) via rotina automática FINA560 (MsExecAuto). Cobre despesa (saída direta da caixinha), adiantamento (que depois exige prestação de contas), prestação de contas do adiantamento e exclusão. A tabela SEU é compartilhada com o endpoint irmão WsChequesTit (cheques sobre títulos) — o filtro visual deste _list considera apenas registros com EU_CAIXA preenchido (perfil caixinha).

Pré-requisito ambiental: a caixinha referenciada (ex.: CX1) deve estar cadastrada no SIGAFIN antes de qualquer POST — o FINA560 valida a existência e bloqueia inclusão se a caixinha não existir.

Vinculação com o ERP

Tabela mestre SEU Cheques / Movimentos de Caixinha (compartilhada)

Rotina automática FINA560 MsExecAuto · Financeiro

Wrapper AdvPL U_FN560Exc src/lib/FIN/FN560EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro · obrigatório

Caixinha (cadastro prévio em SIGAFIN)

o código informado em EU_CAIXA (ex.: CX1) precisa estar cadastrado.
Sem a caixinha, FINA560 rejeita a inclusão. Pré-requisito de smoke test: cadastrar CX1 na base alvo.

Cadastro · condicional

Fornecedor (SA2)

quando EU_FORNECE+EU_LOJA são informados, o par precisa existir em SA2 (não bloqueado).

Cadastro · condicional

Natureza financeira (SED)

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

Endpoint irmão

WsChequesTit (mesma SEU)

A tabela SEU também guarda cheques sobre títulos via WsChequesTit. O _list deste endpoint filtra visualmente apenas registros com EU_CAIXA preenchido para separar os dois perfis.

Tipos de movimento

EU_TIPO (combobox)

00 = Despesa (saída direta da caixinha; sem prestação).
01 = Adiantamento (precisa de prestação posterior via PUT).

Quirk · chave SEU

Chave composta filial+num+caixa+tipo

pela complexidade da chave composta, PUT/DELETE recebem recno no path em vez de chave de negócio. Posicionamento via DbGoTo(recno) antes do wrapper.

Quirk · build 240223P

Dispatcher único de GET

WSMETHOD GET com dispatcher AdvPL pelo último segmento da URL: _list / _byid / {recno}. O build não distingue múltiplos GET por WSSYNTAX.

Limitação · rev1

PUT sem aArray2

o wrapper de prestação (nOper=4) ainda não trata o array auxiliar com itens da prestação. Alguns ambientes podem exigir e o MVC rejeitar — ver TODO em src/lib/FIN/FN560EXC.prw.

Convenções

Acesso individual é recno. A chave SEU é composta por filial+EU_NUM+EU_CAIXA+EU_TIPO — expor isso em URL legível é incomum. Toda operação individual (PUT, DELETE, GET por chave) usa recno como path param, ou ?tipo=recno&valor=N no _byid. O recno é devolvido em data.recno no POST.

Despesa × Adiantamento. O mesmo POST serve os dois perfis — o que muda é EU_TIPO: "00" = despesa (saída direta, fecha quando gravada) e "01" = adiantamento (gera obrigação de prestação posterior via PUT /PRESTACAO/{recno}).

Whitelist por operação. POST aceita o cadastro completo (MovimentoPayload); PUT aceita apenas 5 campos editáveis: EU_HISTOR, EU_VALOR, EU_BENEF, EU_NATUREZA, EU_VLMOED2 (MovimentoPayloadPut). Campo fora do whitelist é silenciosamente ignorado pelo MsExecAuto.

SEU compartilhada com cheques. O _list aplica filtro implícito por EU_CAIXA != "" para excluir os registros de cheques (que vivem em WsChequesTit). Ao integrar, lembre-se de que um recno da SEU pode ser cheque OU caixinha — verifique o campo antes de operar.

Formato de datas. Campos EU_DTDIGT, EU_DTEMIS aceitam string YYYYMMDD (8 dígitos, sem separadores) no payload. Saída do GET serializa via U_RestMnt.

Paginação e delta-sync. O /_list aceita page/pageSize (default 50, máx 500) com orderBy=natural default. Para sync incremental, alterne para orderBy=recno + cursor. since filtra RecNo() < since.

Limitação atual do PUT (rev1). A prestação de contas (nOper=4) está implementada como wrapper simples sobre o cabeçalho da SEU. O array auxiliar com itens da prestação (aArray2) ainda não é tratado — alguns ambientes podem exigir e o MVC rejeitar a prestação. Plano de evolução em src/lib/FIN/FN560EXC.prw.

MovimentoCaixinha

CRUD por RecNo — despesa, adiantamento, prestação e exclusão

POST /WsCaixinha/INCLUIR Inclui movimento (despesa EU_TIPO=00 ou adiantamento EU_TIPO=01)

Descrição

Inclui um movimento de caixinha via FINA560 em modo 3 (MODEL_OPERATION_INSERT). O tipo do movimento é definido pelo campo EU_TIPO do payload:

"00" — despesa: saída direta da caixinha (fecha quando gravada).
"01" — adiantamento: gera obrigação de prestação posterior via PUT /PRESTACAO/{recno}.

Retorna data.recno — guardar para operações subsequentes (prestação, exclusão, consulta).

Whitelist completa: ver MovimentoPayload.

Request body

application/json MovimentoPayload · obrigatório

Payload plano com campos da SEU. Schema completo em MovimentoPayload.

EU_NUMstring · obrigatórioSEU.EU_NUM

Número do movimento (sequencial da caixinha).

EU_CAIXAstring · obrigatórioSEU.EU_CAIXA

Código da caixinha (cadastro prévio em SIGAFIN).

EU_TIPOstring · obrigatórioSEU.EU_TIPO

00 = despesa; 01 = adiantamento.

EU_VALORnumber · obrigatórioSEU.EU_VALOR

Valor do movimento (> 0).

EU_HISTORstring · obrigatórioSEU.EU_HISTOR

Histórico/descrição.

Cenário — Despesa (EU_TIPO=00). Saída direta da caixinha CX1 com comprovante (NF). Fixture: fixtures/caixinha-incluir.json.

RequestHTTP/1.1 · application/json

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

{
  "EU_NUM": "0000000099",
  "EU_CAIXA": "CX1",
  "EU_TIPO": "00",
  "EU_HISTOR": "_TEST_ SMOKE DESPESA CAIXINHA",
  "EU_NRCOMP": "TST-SMOKE",
  "EU_VALOR": 250.00,
  "EU_BENEF": "_TEST_FORNEC CAIXINHA",
  "EU_DTDIGT": "20260516",
  "EU_DTEMIS": "20260516",
  "EU_FORNECE": "000001",
  "EU_LOJA": "01",
  "EU_NATUREZA": "201",
  "EU_MOEDA": 1
}

Respostas

201

Movimento gravado. Envelope CrudResponse com data = MovimentoRef incluindo recno — guardar para operações subsequentes.

400

Body JSON ausente/inválido, EU_TIPO fora de [00,01], campos obrigatórios vazios. Tier: validation-error.

422

Rejeição do FINA560 — caixinha não cadastrada, fornecedor inexistente/bloqueado, natureza inválida, número duplicado. Tier: business-error.

500

Erro interno.

PUT /WsCaixinha/PRESTACAO/{recno} Prestação de contas / alteração (FINA560 nOper=4)

Descrição

Altera campos do movimento via FINA560 em modo 4 (MODEL_OPERATION_UPDATE) — tipicamente a prestação de contas de um adiantamento (EU_TIPO=01). Escopo de negócio reduzido: apenas 5 campos entram no array do MsExecAuto:

EU_HISTOR — histórico/descrição
EU_VALOR — valor do movimento
EU_BENEF — beneficiário
EU_NATUREZA — natureza financeira
EU_VLMOED2 — valor em moeda 2

Campos fora do whitelist são silenciosamente ignorados pelo MsExecAuto.

Limitação rev1: o wrapper ainda não trata aArray2 (itens da prestação). Alguns ambientes podem exigir e o MVC rejeitar — ver src/lib/FIN/FN560EXC.prw.

Path parameter

recno integer · path · obrigatório SEU.RecNo()

RecNo do movimento de adiantamento devolvido no POST.

Request body

application/json MovimentoPayloadPut · obrigatório

Subconjunto dos 5 campos editáveis. Schema em MovimentoPayloadPut.

EU_HISTORstring · opcionalSEU.EU_HISTOR

Histórico atualizado pós-prestação.

EU_VALORnumber · opcionalSEU.EU_VALOR

Valor efetivo (pode diferir do adiantado).

Prestação de contas — ajusta histórico e valor efetivo. Fixture: fixtures/caixinha-prestacao.json.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsCaixinha/PRESTACAO/12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "EU_HISTOR": "_TEST_ PRESTACAO CONCLUIDA",
  "EU_VALOR": 450.00
}

Respostas

200

Prestação registrada. Envelope CrudResponse.

400

recno ausente/inválido, body ausente, JSON malformado. Tier: validation-error.

404

Movimento não localizado pelo recno. Tier: not-found.

422

Rejeição do FINA560 — movimento de despesa (sem prestação), prestação já efetuada, natureza inválida, ambiente exige aArray2. Tier: business-error.

500

Erro interno.

DEL /WsCaixinha/EXCLUIR/{recno} Exclui movimento (FINA560 nOper=5)

Descrição

Exclui o movimento via FINA560 em modo 5 (MODEL_OPERATION_DELETE). O endpoint posiciona a SEU via DbGoTo(recno) antes do wrapper.

Pré-requisitos:

Movimento sem prestação efetuada (no caso de adiantamento).
Sem vínculo contábil/bancário pendente.

Soft-delete TOTVS: marca D_E_L_E_T_='*'.

Path parameter

recno integer · path · obrigatório SEU.RecNo()

RecNo do movimento a excluir.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusão — soft-delete via FINA560 modo 5.

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsCaixinha/EXCLUIR/12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Movimento excluído. Mensagem: "Movimento excluido com sucesso."

400

recno ausente/inválido. Tier: validation-error.

404

Movimento não localizado. Tier: not-found.

422

Exclusão rejeitada — adiantamento com prestação efetuada, vínculo pendente. Tier: business-error.

500

Erro interno.

GET /WsCaixinha/{recno} Consulta movimento pelo RecNo no path

Descrição

Retorna o movimento posicionado pelo recno. Aplica whitelist CAMPOS_GET sobre o cabeçalho da SEU.

Path parameter

recno integer · path · obrigatório SEU.RecNo()

RecNo do movimento (devolvido no POST ou no _list).

Cenario

Exemplo da requisicao (cenario ativo)

Consulta direta por RecNo — retorna envelope { success, data: Movimento }.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsCaixinha/12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Movimento encontrado. Envelope { success: true, data: Movimento }.

400

recno não numérico.

404

Movimento não localizado ou de outra filial.

500

Erro interno.

GET /WsCaixinha/_byid Consulta movimento por identificador técnico (recno|msuid)

Descrição

Busca o movimento por id técnico — alternativa programática quando o consumer prefere usar query string em vez de path param. Equivalente funcional ao GET /WsCaixinha/{recno} quando tipo=recno; ou busca por EU_MSUID quando tipo=msuid.

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 GUID para tipo=msuid.

Cenario

Exemplo da requisicao (cenario ativo)

Busca por recno — equivalente a GET /WsCaixinha/12345 mas via query string.

RequestHTTP/1.1 · sem body

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

Respostas

200

Movimento encontrado.

400

tipo/valor ausentes ou fora do enum.

404

Movimento não localizado.

501

Busca por msuid requer EU_MSUID no dicionário.

500

Erro interno.

Listagem

Paginação por filtros + delta-sync

GET /WsCaixinha/_list Lista movimentos de caixinha com filtros + paginação

Descrição

Lista movimentos da caixinha (filtra implicitamente apenas registros com EU_CAIXA preenchido, excluindo cheques). Filtros opcionais por filial, numero (EU_NUM), caixa, tipo:

orderBy=natural (default) — paginação por offset (page/pageSize).
orderBy=recno — paginação por keyset com cursor/nextCursor; indicado para sync incremental.

Query parameters

filial string · query · opcional SEU.EU_FILIAL

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

numero string · query · opcional SEU.EU_NUM

Número do movimento (filtro exato).

caixa string · query · opcional SEU.EU_CAIXA

Código da caixinha (filtro exato).

tipo string · query · opcional SEU.EU_TIPO

Tipo do movimento.

0001

fields string · query · opcional

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

page integer · query · opcional

Página (default 1). Só faz sentido com orderBy=natural.

pageSize integer · query · opcional

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

orderBy string · query · opcional

Modo de ordenação. Default natural.

naturalrecno

since integer · query · opcional

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

cursor integer · query · opcional

Em orderBy=recno, retoma após este RecNo.

Cenario

Exemplo da requisicao (cenario ativo)

Listagem paginada — movimentos da caixinha CX1, default orderBy=natural.

RequestHTTP/1.1 · sem body

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

Respostas

200

Página de movimentos. Envelope com data (array de Movimento), orderBy, pageSize, count, opcionalmente page ou nextCursor.

400

Parâmetro inválido.

500

Erro interno.

Schemas

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

Movimento

object

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

EU_FILIALstringSEU.EU_FILIAL

Filial do movimento.

EU_NUMstringSEU.EU_NUM

Número sequencial do movimento.

EU_CAIXAstringSEU.EU_CAIXA

Código da caixinha.

EU_TIPOstringSEU.EU_TIPO

00=despesa, 01=adiantamento.

EU_HISTORstringSEU.EU_HISTOR

Histórico.

EU_NRCOMPstringSEU.EU_NRCOMP

Número do comprovante.

EU_VALORnumberSEU.EU_VALOR

Valor do movimento.

EU_BENEFstringSEU.EU_BENEF

Beneficiário.

EU_DTDIGTstringSEU.EU_DTDIGT

Data de digitação (YYYYMMDD).

EU_DTEMISstringSEU.EU_DTEMIS

Data de emissão.

EU_FORNECEstringSEU.EU_FORNECE

Fornecedor.

EU_LOJAstringSEU.EU_LOJA

Loja do fornecedor.

EU_NOMEstringSEU.EU_NOME

Nome do fornecedor (desnormalizado).

EU_CGCstringSEU.EU_CGC

CGC do fornecedor (desnormalizado).

EU_NATUREZAstringSEU.EU_NATUREZA

Natureza financeira.

EU_MOEDAintegerSEU.EU_MOEDA

Código da moeda (1=R$).

EU_VLMOED2numberSEU.EU_VLMOED2

Valor em moeda 2.

recnointeger

RecNo do registro.

msuidstring

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

msuidtstring

Timestamp técnico.

MovimentoPayload

object

Payload aceito em POST para FINA560 nOper=3. Chave composta de negócio: EU_NUM+EU_CAIXA+EU_TIPO (filial vem do contexto do request).

EU_NUMstring · obrigatórioSEU.EU_NUM

Número do movimento.

EU_CAIXAstring · obrigatórioSEU.EU_CAIXA

Código da caixinha (cadastro prévio).

EU_TIPOstring · obrigatórioSEU.EU_TIPO

00=despesa, 01=adiantamento.

0001

EU_HISTORstring · obrigatórioSEU.EU_HISTOR

Histórico/descrição.

EU_VALORnumber · obrigatórioSEU.EU_VALOR

Valor (> 0).

EU_NRCOMPstring · opcionalSEU.EU_NRCOMP

Número do comprovante (NF, recibo).

EU_BENEFstring · opcionalSEU.EU_BENEF

Beneficiário.

EU_DTDIGTstring (date) · opcionalSEU.EU_DTDIGT

Data de digitação, YYYYMMDD.

EU_DTEMISstring (date) · opcionalSEU.EU_DTEMIS

Data de emissão.

EU_FORNECEstring · opcionalSEU.EU_FORNECE

Fornecedor (SA2).

EU_LOJAstring · opcionalSEU.EU_LOJA

Loja.

EU_NOMEstring · opcionalSEU.EU_NOME

Nome do beneficiário (desnormalizado).

EU_CGCstring · opcionalSEU.EU_CGC

CGC do beneficiário.

EU_NATUREZAstring · opcionalSEU.EU_NATUREZA

Natureza financeira (SED).

EU_MOEDAinteger · opcionalSEU.EU_MOEDA

Código da moeda. Default 1 (R$).

EU_VLMOED2number · opcionalSEU.EU_VLMOED2

Valor em moeda 2.

EU_ENVUMOVstring · opcionalSEU.EU_ENVUMOV

Envio do movimento.

EU_CC1string · opcionalSEU.EU_CC1

Centro de custo 1.

EU_CC2string · opcionalSEU.EU_CC2

Centro de custo 2.

EU_CC3string · opcionalSEU.EU_CC3

Centro de custo 3.

EU_CC4string · opcionalSEU.EU_CC4

Centro de custo 4.

MovimentoPayloadPut

object

Whitelist reduzida do PUT (CAMPOS_ALLOW_PUT). Apenas 5 campos editáveis para prestação — campo fora desta lista é silenciosamente ignorado pelo MsExecAuto.

EU_HISTORstring · opcionalSEU.EU_HISTOR

Histórico/descrição pós-prestação.

EU_VALORnumber · opcionalSEU.EU_VALOR

Valor efetivo (pode diferir do adiantado).

EU_BENEFstring · opcionalSEU.EU_BENEF

Beneficiário ajustado.

EU_NATUREZAstring · opcionalSEU.EU_NATUREZA

Natureza financeira.

EU_VLMOED2number · opcionalSEU.EU_VLMOED2

Valor em moeda 2.

MovimentoRef

object

Referência ao movimento — devolvida em data nas respostas de POST/PUT. Acrescenta ids técnicos.

recnointeger

RecNo do registro SEU — guardar.

operinteger

nOper aplicado (3 = inclusão, 4 = prestação, 5 = exclusão).

numstring

Número do movimento.

caixastring

Caixinha.

tipostring

Tipo do movimento.

msuidstring

MS_UID quando o dicionário tem EU_MSUID.

msuidtstring

Timestamp do MS_UID.

CrudResponse

object · envelope

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

successboolean · const: true

Sempre true em sucesso.

messagestring · obrigatório

Mensagem editorial.

datastring | MovimentoRef · opcional

Referência do movimento ou string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. Em 422 a message traz a mensagem do NomeAutoLog do FINA560.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial.

datastring · opcional

Token interno / detalhe técnico.

Cenários

Catálogo de combinações reconhecidas. Tier semântico no slug; endpoint no type-pill.

incluir-movimento

POST /WsCaixinha/INCLUIR

Inclusão de despesa (EU_TIPO=00) ou adiantamento (EU_TIPO=01) na caixinha. FINA560 modo 3.

Quando usar: registrar saída de caixinha (despesa fecha quando gravada; adiantamento aguarda prestação).

prestacao-contas

PUT /WsCaixinha/PRESTACAO/{recno}

Ajusta os campos editáveis do adiantamento (EU_HISTOR, EU_VALOR, EU_BENEF, EU_NATUREZA, EU_VLMOED2) via FINA560 nOper=4.

Limitação: rev1 não trata aArray2 (itens da prestação). Em ambientes que exigem array de itens, o MVC pode rejeitar.

excluir-movimento

DELETE /WsCaixinha/EXCLUIR/{recno}

Soft-delete (D_E_L_E_T_='*') via FINA560 nOper=5. Endpoint posiciona SEU via DbGoTo(recno) antes do wrapper.

Bloqueio: 422 quando há prestação já efetuada ou vínculo contábil/bancário pendente.

consulta-direta

GET /WsCaixinha/{recno}

Posicionamento direto via DbGoTo(recno). Devolve cabeçalho da SEU + ids técnicos.

listar-paginado

GET /WsCaixinha/_list

Lista movimentos da caixinha (filtro implícito EU_CAIXA != "" para separar dos cheques). Default orderBy=natural + page/pageSize. Delta-sync via orderBy=recno + cursor.

busca-por-recno

GET /WsCaixinha/_byid

Equivalente ao GET /{recno} em forma de query string (?tipo=recno&valor=N). Alternativa quando o consumer prefere query params sobre path params. Aceita também tipo=msuid quando EU_MSUID está no dicionário.

Pendências conhecidas (rev1)

PUT sem suporte a aArray2. O wrapper U_FN560Exc para nOper=4 ainda não trata o array auxiliar com itens da prestação. Em bases customizadas que exigem itens detalhados (com partição de valores), o MVC pode rejeitar a prestação. Plano de evolução em src/lib/FIN/FN560EXC.prw (TODO interno).

Caixinha CX1 precisa estar cadastrada. O smoke test e a fixture base usam EU_CAIXA="CX1"; sem esse cadastro na base alvo o POST retorna 422. Em ambientes novos, criar a caixinha CX1 via SIGAFIN antes de rodar testes.

SEU compartilhada com cheques. O endpoint WsChequesTit também grava em SEU — um recno da SEU pode ser caixinha OU cheque. A integração deve verificar EU_CAIXA antes de operar (vazio = cheque; preenchido = caixinha). O _list aplica esse filtro implicitamente; _byid e {recno} não.

Bloqueio MSBLQL/MSBLQD não aplicado. A SEU não expõe MSBLQL/MSBLQD; o bloqueio relevante está na caixinha (cadastro próprio do SIGAFIN) e no fornecedor (SA2) e é enforced pelo próprio FINA560. Não há contrato adicional a aplicar no endpoint.

Padronização de tipos pendente. O domínio de EU_TIPO em algumas bases customizadas vai além de 00/01 (ex.: 02 = devolução). A whitelist atual não bloqueia outros valores no payload — chega ao FINA560, que aceita ou rejeita conforme parametrização. Validação de domínio (fValDom) pode ser adicionada em rev futura se necessário.