rev1-2026-05-16 Protheus 12.1.33

Transferencia

Inclusão e consulta de Solicitação de Transferência Financeira (tabela SE6) via rotina automática FINA621 (MsExecAuto). Endpoint apenas de criação e leitura: alteração / aprovação / rejeição / estorno vão pelo endpoint irmão AprovacaoTransf (rotina FINA631). O identificador externo é o numsol (E6_NUMSOL), gerado pela FINA621 e devolvido na resposta do POST. A solicitação nasce com E6_SITSOL='1' (em aberto) e aguarda aprovação para virar transferência efetiva.

Endpoint apenas POST + GET. Não há PUT/DELETE neste endpoint. O ciclo de vida pós-criação (aprovar, rejeitar, estornar, excluir) pertence ao AprovacaoTransf (FINA631). Esta separação reflete a separação de papéis do Protheus: quem solicita ≠ quem aprova.

Vinculação com o ERP

Tabela mestre SE6 Solicitações de transferência financeira

Rotina automática FINA621 MsExecAuto · Financeiro · SIGAFIN

Wrapper AdvPL U_FN621Exc src/lib/FIN/FN621EXC.prw

Operações & modos

POST nOper 3 (única)

Dependências de ambiente

Cadastro · obrigatório

Cliente (SA1)

o par cliente/loja precisa existir em SA1 e não pode estar bloqueado. Sem cliente, FINA621 rejeita com mensagem do NomeAutoLog.

Parametrização · obrigatória

MV_NATTRFF (natureza de transferência)

parâmetro do sistema que aponta a natureza financeira default de transferência. Sem este parâmetro definido, a FINA621 pode rejeitar a inclusão.

Motivo / Justificativa

SX5/Z3 "TRF" via FINA490

motivos cadastrados via rotina FINA490 sob tabela SX5/05 (ou Z3 conforme parametrização). Item TRF = "transferência". Necessário quando o fluxo de aprovação exigir justificativa textual.

Endpoint complementar

AprovacaoTransf (FINA631)

para aprovar, rejeitar, estornar ou excluir uma solicitação, use o endpoint AprovacaoTransf. Esta separação reflete a separação de papéis do Protheus (solicitante ≠ aprovador).

Quirk · WSDATA reservada

JSON usa "vlrTransf", não "valor"

a chave JSON do valor da transferência é vlrTransf (não valor) porque WSDATA valor está reservada ao _byid?valor=N. Build 240223P resolve oJson["valor"] case-insensitive contra WSDATA e devolveria o default da WSDATA — bug silencioso (ver ERROS.md E13).

Quirk · build 240223P

Dispatcher único de GET

WSMETHOD GET com WSSYNTAX "/WsTransfFin/{path}" + dispatcher AdvPL (_list / _byid / numsol). O build não distingue múltiplos GET por WSSYNTAX.

Convenções

Identificador externo — numsol. O número da solicitação (E6_NUMSOL) é gerado pelo FINA621 e devolvido na resposta do POST via data.numsol. Após a criação, use o numsol como chave de leitura: GET /WsTransfFin/{numsol}.

Chave JSON do valor: vlrTransf. Não use valor — a WSDATA valor está reservada ao parâmetro _byid?valor=N. Build 240223P resolve oJson["valor"] case-insensitive contra WSDATA e devolveria o default. Use sempre vlrTransf no body do POST.

Sem PUT/DELETE. Esta API é apenas de criação e consulta. Para alterar (raro) ou cancelar uma solicitação, use o endpoint AprovacaoTransf (FINA631) — ele expõe _aprovar, _rejeitar, _excluir, _estornar conforme o ciclo de vida.

Status (E6_SITSOL). A solicitação nasce em "1" (Em aberto). Após processamento pelo aprovador, vira "2" (Aprovada) ou "3" (Rejeitada). O endpoint WsTransfFin só cria solicitações em "1" — mudanças de status pertencem ao AprovacaoTransf.

Formato de data. Campo data no payload aceita formato ISO YYYY-MM-DD. Quando omitido, o servidor usa dDataBase (data corrente do Protheus).

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

Solicitação de Transferência (SE6)

Inclusão e consulta — aprovação vai pelo AprovacaoTransf (FINA631)

POST /WsTransfFin/INCLUIR Inclui solicitação de transferência (nasce em "1 Em aberto")

Descrição

Cria nova solicitação de transferência via FINA621 nOper 3 (única operação suportada pela rotina). Retorna o numsol gerado e o recno SE6. A solicitação nasce com E6_SITSOL='1' (Em aberto) e aguarda processamento pelo endpoint AprovacaoTransf.

Obrigatórios: filDeb, cliente, loja, vlrTransf (> 0).
Opcionais: data (default dDataBase), histDeb.
Schema completo em TransferenciaPayload.

Request body

application/json TransferenciaPayload · obrigatório

Payload plano. Schema em TransferenciaPayload.

filDeb string · obrigatório

Filial de débito (E6_FILDEB, 4 chars).

cliente string · obrigatório

Código do cliente (E6_CLIENTE, 6 chars).

loja string · obrigatório

Loja do cliente (E6_LOJA, 2 chars).

vlrTransf number · obrigatório

Valor (E6_VALOR, > 0). Chave JSON é vlrTransf, não valor.

data string · opcional

Data de referência ISO YYYY-MM-DD. Default = dDataBase.

histDeb string · opcional

Histórico do débito (E6_HISTDEB, máx 40 chars).

Cenario 1 — Inclusão simples. Payload mínimo + histórico explicativo. numsol é gerado pela FINA621 e devolvido no data.

RequestHTTP/1.1 · application/json

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

{
  "filDeb":    "0101",
  "cliente":   "000001",
  "loja":      "01",
  "data":      "2026-05-16",
  "vlrTransf": 1000.00,
  "histDeb":   "Transferencia teste smoke"
}

Response · 201application/json

{
  "success": true,
  "message": "Solicitacao de transferencia incluida com sucesso.",
  "data": {
    "recno":  12345,
    "numsol": "000001",
    "filial": "0101",
    "valor":  1000.00,
    "data":   "20260516"
  }
}

Respostas

201

Solicitação criada. Envelope CrudResponse com data = TransferenciaRef.

400

Body JSON ausente/inválido, campo obrigatório vazio (filDeb, cliente, loja), vlrTransf ≤ 0. Tier: validation-error.

422

FINA621 rejeitou a inclusão — cliente inexistente/bloqueado, MV_NATTRFF ausente, motivo TRF não cadastrado, regra de negócio violada. Mensagem editorial em message. Tier: business-error.

500

Erro interno.

GET /WsTransfFin/{numsol} Consulta solicitação pelo número

Descrição

Retorna o cabeçalho da solicitação posicionada pelo E6_NUMSOL (índice 3 da SE6: E6_FILIAL+E6_NUMSOL). Aplica whitelist de CAMPOS_GET + ids técnicos.

Path parameter

numsol string · path · obrigatório SE6.E6_NUMSOL

Número da solicitação (6 chars).

Cenario

Exemplo da requisicao (cenario ativo)

Consulta por numsol — retorna envelope com data: Transferencia.

RequestHTTP/1.1 · sem body

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

Respostas

200

Solicitação encontrada. Envelope { success: true, data: Transferencia }.

400

Numsol ausente. Tier: validation-error.

404

Solicitação não localizada. Tier: not-found.

500

Erro interno.

GET /WsTransfFin/_byid Consulta solicitação por id técnico (recno)

Descrição

Busca a solicitação por RecNo() — útil para integrações que persistem o id técnico e querem reconfirmar o registro sem decompor numsol. Apenas tipo=recno nesta revisão — SE6 nesta base não expõe E6_MSUID.

Query parameters

tipo string · query · obrigatório

Único valor aceito nesta revisão.

recno

valor string · query · obrigatório

Inteiro positivo (RecNo físico).

Cenario

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/WsTransfFin/_byid?tipo=recno&valor=12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Solicitação encontrada. Envelope { success: true, data: Transferencia }.

400

tipo/valor ausentes, tipo fora do enum, valor não inteiro.

404

Solicitação não localizada ou fora da filial corrente. Tier: not-found.

500

Erro interno.

Listagem

Paginação por filtros e delta-sync

GET /WsTransfFin/_list Lista solicitações com filtros e paginação

Descrição

Lista solicitações com filtros por filial, cliente, loja, numero em dois modos:

orderBy=numsol (default) — usa o índice 3 da SE6 (E6_FILIAL+E6_NUMSOL); paginação por page/pageSize.
orderBy=recno — varre fisicamente; paginação por keyset com cursor/nextCursor. Indicado para sync incremental.

Query parameters

filial string · query · opcional SE6.E6_FILIAL

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

numero string · query · opcional SE6.E6_NUMSOL

Número da solicitação (filtro exato após trim).

cliente string · query · opcional SE6.E6_CLIENTE

Código do cliente.

loja string · query · opcional SE6.E6_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=numsol.

pageSize integer · query · opcional

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

orderBy string · query · opcional

Modo de ordenação. Default numsol.

numsolrecno

since integer · query · opcional

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

cursor integer · query · opcional

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

Cenario

Exemplo da requisicao (cenario ativo)

Listagem paginada de pendentes — default orderBy=numsol, pageSize=50. Para filtrar apenas em aberto, o consumer aplica filtro pós-resposta (E6_SITSOL='1') — este endpoint não tem filtro nativo por status.

RequestHTTP/1.1 · sem body

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

Respostas

200

Página de solicitações. Envelope com data (array de Transferencia), orderBy, pageSize, count, opcionalmente page ou nextCursor.

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

Transferencia

object

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

E6_FILIALstringSE6.E6_FILIAL

Filial.

E6_NUMSOLstringSE6.E6_NUMSOL

Número da solicitação (6 chars, gerado pela FINA621).

E6_FILDEBstringSE6.E6_FILDEB

Filial de débito.

E6_CLIENTEstringSE6.E6_CLIENTE

Código do cliente.

E6_LOJAstringSE6.E6_LOJA

Loja do cliente.

E6_DATAstringSE6.E6_DATA

Data de referência (YYYYMMDD).

E6_VALORnumberSE6.E6_VALOR

Valor da transferência.

E6_HISTDEBstringSE6.E6_HISTDEB

Histórico do débito.

E6_SITSOLstringSE6.E6_SITSOL

Status: 1 Em aberto · 2 Aprovada · 3 Rejeitada.

E6_AUTORstringSE6.E6_AUTOR

Usuário que registrou a solicitação.

recnointeger

Id técnico do registro.

msuidstring

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

msuidtstring

Timestamp técnico do MS_UID.

TransferenciaPayload

object

Payload aceito em POST /WsTransfFin/INCLUIR. Whitelist da FINA621. O servidor gera numsol internamente — não enviar.

filDebstring · obrigatórioSE6.E6_FILDEB

Filial de débito (4 chars).

clientestring · obrigatórioSE6.E6_CLIENTE

Código do cliente (6 chars).

lojastring · obrigatórioSE6.E6_LOJA

Loja do cliente (2 chars).

vlrTransfnumber · obrigatórioSE6.E6_VALOR

Valor da transferência (> 0). Chave JSON é vlrTransf, não valor.

datastring (date) · opcionalSE6.E6_DATA

Data de referência ISO YYYY-MM-DD. Default = dDataBase.

histDebstring · opcionalSE6.E6_HISTDEB

Histórico do débito (máx 40 chars).

TransferenciaRef

object

Referência leve devolvida em data na resposta do POST.

recnointeger

RecNo do registro recém-criado.

numsolstring

Número da solicitação gerado pela FINA621.

filialstring

Filial.

valornumber

Valor gravado.

datastring

Data gravada (YYYYMMDD).

CrudResponse

object · envelope

Envelope padrão do POST. data traz TransferenciaRef.

successboolean · const: true

Sempre true em sucesso.

messagestring · obrigatório

Mensagem editorial.

dataTransferenciaRef

Chave gerada + ids técnicos.

Erro

object · envelope

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

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 reconhecidas. Tier semântico no slug; endpoint no type-pill.

incluir-solicitacao

POST /WsTransfFin/INCLUIR

Cria nova solicitação de transferência (E6_SITSOL='1' Em aberto). FINA621 gera numsol sequencial. Pré-requisitos: cliente cadastrado em SA1 não bloqueado, MV_NATTRFF configurado, motivo TRF disponível em SX5/05.

Quando usar: caso de uso padrão — integração cria solicitação que depois será processada pelo endpoint AprovacaoTransf.

Próximos passos: aguardar aprovação via FINA631 (status vira "2") ou rejeição ("3").

consulta-direta

GET /WsTransfFin/{numsol}

DbSeek pelo índice 3 da SE6 (E6_FILIAL+E6_NUMSOL). Retorna envelope { success, data: Transferencia }. Use após o POST para reconferir o registro gravado, ou em qualquer momento para checar o status atual (E6_SITSOL).

busca-por-recno

GET /WsTransfFin/_byid

Busca por RecNo() via tipo=recno&valor=N. Identificador técnico sempre disponível — útil quando o consumer persistiu o recno na criação e não precisa retransmitir o numsol.

listar-pendentes

GET /WsTransfFin/_list

Default orderBy=numsol + page/pageSize. Paginação por offset sobre o índice 3 da SE6. O filtro por status (E6_SITSOL) é aplicado pelo consumer pós-resposta — o endpoint não tem query param dedicado para status nesta revisão.

Pendências conhecidas (rev1)

Sem PUT/DELETE neste endpoint. A separação de papéis exige que alteração / aprovação / rejeição / estorno / exclusão venham pelo endpoint irmão AprovacaoTransf (FINA631). O smoke test não consegue limpar a sentinela criada porque depende desse outro endpoint — o trap chama AprovacaoTransf/_excluir em best-effort.

Sem filtro nativo por status (E6_SITSOL). O _list não expõe status/sitsol como query param. Para listar apenas em aberto, o consumer aplica o filtro pós-resposta. Próxima revisão considera adicionar query param dedicado.

Bloqueio MSBLQL/MSBLQD não aplicável a SE6. A tabela SE6 não expõe campos administrativos de bloqueio — o que conta é o status (E6_SITSOL) e o estado do cliente (SA1.A1_MSBLQL). O bloqueio do cliente é enforcado pelo FINA621 — este endpoint só propaga a mensagem 422.

_byid só com tipo=recno. O endpoint aceita o parâmetro tipo=msuid no schema, mas a SE6 nesta base não tem E6_MSUID — comportamento default fica em 400/501 conforme enums. Aguarda UPDDISTR de MVC para SE6.

Pré-requisitos ambientais sensíveis. FINA621 depende de MV_NATTRFF (natureza default de transferência) e do cadastro do motivo TRF em SX5/05 via rotina FINA490. Sem qualquer um desses, o POST retorna 422 com mensagem do NomeAutoLog — nem sempre auto-explicativa.