rev1-2026-05-16 Protheus 12.1.33

AprovacaoTransf

Serviço REST para mudança de status de solicitações de transferência financeira (tabela SE6) via rotina automática FINA631. Não é CRUD. Três operações expostas por verbo no path: _aprovar, _excluir e _estornar. A inclusão da solicitação acontece no endpoint Transferencia (FINA621); a consulta de status, idem.

Bloqueio TOTVS: endpoint de processo (mudança de status SE6), sem MSBLQL próprio — o gating é pelo E6_SITSOL (Em aberto / Aprovada).

Vinculação com o ERP

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

Rotina automática FINA631 MsExecAuto · aprovação/exclusão/estorno

Wrapper AdvPL U_FN631Exc src/lib/FIN/FN631EXC.prw

Operações & modos

POST /_aprovar — op 3 POST /_excluir — op 5 POST /_estornar — op 6 GET não exposto (consultar via Transferencia/{numsol})

Endpoint relacionado Transferencia FINA621 · inclusão da solicitação + consulta de status

Parâmetro obrigatório MV_NATTRFF Natureza do título a pagar da filial destino

Dependências de ambiente

Parâmetro · MV_NATTRFF

MV_NATTRFF

Natureza do título a pagar da filial destino. Sem ela, o FINA631 rejeita com mensagem "Natureza não encontrada".

Cadastro · motivo de baixa

Motivo TRF (FINA490)

Motivo de baixa com sigla TRF deve estar cadastrado via FINA490. Usado pelo FINA631 para registrar a baixa por transferência.

Pré-requisito · inclusão

Endpoint Transferencia (FINA621)

Solicitação SE6 precisa existir antes (E6_NUMSOL); este endpoint só muda status, nunca cria.

Posterior · consulta

Transferencia/{numsol}

Estado da solicitação após a operação é consultado via endpoint de inclusão (mesmo serviço, GET por numsol).

Convenções

Endpoint de processo, não CRUD. Só muda status de solicitações SE6 já existentes. A inclusão é feita em outro endpoint (Transferencia — FINA621). Consulta também é via Transferencia/{numsol}.

Dispatcher por verbo no path. Único método HTTP é POST; o último segmento da URL (_aprovar, _excluir, _estornar) seleciona o nOper do FINA631 (3, 5, 6).

Pré-validação de status. Antes do MsExecAuto, o endpoint posiciona SE6 e valida E6_SITSOL:

_aprovar e _excluir exigem E6_SITSOL='1' (Em aberto)
_estornar exige E6_SITSOL='2' (Aprovada)

Se o status não bate, retorna 422 com mensagem clara antes de chamar o FINA631.

Ciclo de vida.

[em aberto E6_SITSOL=1]
       |
       |  _aprovar  ----> [aprovada E6_SITSOL=2]
       |                          |
       |                          |  _estornar
       |                          v
       |                  [em aberto novamente E6_SITSOL=1]
       |
       |  _excluir  ----> (registro removido)

Body uniforme. Os três verbos compartilham o mesmo schema NumSolRequest — apenas numsol (E6_NUMSOL, máx. 6 chars). Não há campos opcionais por operação.

Resposta enriquecida. Após sucesso, o endpoint re-localiza o registro e devolve sitsol atualizado (útil pra confirmar o novo estado sem nova chamada GET).

Aprovação / Rejeição

Mudança de status de solicitação SE6 via FINA631

POST /WsAprovaTransf/_aprovar Aprova solicitação em aberto

Descrição

Executa FINA631 nOper=3 (Aprovação) sobre a solicitação identificada por numsol (E6_NUMSOL). E6_SITSOL transita de 1 (Em aberto) para 2 (Aprovada).

Pré-condição: E6_SITSOL='1'. Caso contrário retorna 422.

Cenário

Aprovação padrão. Cenário único para uniformidade do padrão.

Request body

application/json NumSolRequest · obrigatório

numsolstring · obrigatórioSE6.E6_NUMSOL

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

Exemplo da requisição (cenário ativo)

Aprovação padrão — solicitação em aberto vira aprovada.

RequestHTTP/1.1 · application/json

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

{
  "numsol": "000001"
}

Respostas

200

Aprovada. Envelope traz data.sitsol="2" + recno + op=3.

400

Body vazio, JSON inválido, ou numsol ausente.

404

Solicitação não localizada por numsol na filial.

422

E6_SITSOL ≠ '1' (não está em aberto) ou FINA631 rejeitou (ex.: MV_NATTRFF ausente, motivo TRF não cadastrado). Tier: business-error.

500

Erro interno.

POST /WsAprovaTransf/_excluir Exclui solicitação em aberto

Descrição

Executa FINA631 nOper=5 (Exclusão) sobre a solicitação identificada por numsol. O registro é removido do SE6.

Pré-condição: E6_SITSOL='1' (apenas solicitações em aberto podem ser excluídas). Aprovadas devem ser estornadas antes de excluir.

Cenário

Request body

application/json NumSolRequest · obrigatório

numsolstring · obrigatórioSE6.E6_NUMSOL

Número da solicitação a excluir.

Exemplo da requisição (cenário ativo)

Exclusão padrão — solicitação em aberto é removida.

RequestHTTP/1.1 · application/json

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

{
  "numsol": "000001"
}

Respostas

200

Excluída. Envelope traz data.op=5 + numsol + recno.

400

Body vazio ou numsol ausente.

404

Solicitação não localizada.

422

E6_SITSOL ≠ '1' ou FINA631 rejeitou. Tier: business-error.

500

Erro interno.

POST /WsAprovaTransf/_estornar Estorna solicitação aprovada

Descrição

Executa FINA631 nOper=6 (Estorno) sobre a solicitação identificada por numsol. Reverte aprovação: E6_SITSOL volta de 2 (Aprovada) para 1 (Em aberto).

Pré-condição: E6_SITSOL='2'. Caso contrário retorna 422.

Cenário

Request body

application/json NumSolRequest · obrigatório

numsolstring · obrigatórioSE6.E6_NUMSOL

Número da solicitação aprovada a estornar.

Exemplo da requisição (cenário ativo)

Estorno padrão — solicitação aprovada volta para em aberto.

RequestHTTP/1.1 · application/json

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

{
  "numsol": "000001"
}

Respostas

200

Estornada. Envelope traz data.sitsol="1" + op=6.

400

Body vazio ou numsol ausente.

404

Solicitação não localizada.

422

E6_SITSOL ≠ '2' (não está aprovada) ou FINA631 rejeitou. Tier: business-error.

500

Erro interno.

Schemas

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

NumSolRequest

object

Body uniforme dos três verbos. Apenas numsol; não há campos opcionais por operação — o verbo no path já determina o que vai acontecer.

numsolstring · obrigatório · max 6SE6.E6_NUMSOL

Número da solicitação (E6_NUMSOL).

RespostaOperacao

object · envelope

Envelope de sucesso. Em _aprovar/_estornar, data.sitsol traz o novo estado pós-operação (re-localizado após o MsExecAuto).

successboolean · const: true

Sempre true em sucesso.

messagestring

Mensagem editorial (ex: "Operação _aprovar executada com sucesso na solicitação 000001.").

data.numsolstring

Número da solicitação processada.

data.recnointeger

RECNO devolvido pelo wrapper.

data.opinteger

nOper FINA631: 3=aprovar, 5=excluir, 6=estornar.

data.sitsolstring

Novo E6_SITSOL (vazio quando a operação remove o registro).

Erro

object · envelope

Envelope padrão de erros 4xx/5xx.

successboolean · const: false

Sempre false.

messagestring

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

datastring

Detalhe técnico opcional.

Cenários

Catálogo de combinações de payload reconhecidas pelos métodos.

aprovar-transferencia

POST /_aprovar

Aprovação padrão de uma solicitação SE6 em aberto.

Quando usar: aprovador (gestor/financeiro) confirma a transferência depois que o solicitante registrou em Transferencia (FINA621).
Pré-condição: E6_SITSOL='1', MV_NATTRFF definido, motivo TRF cadastrado.
Resultado: E6_SITSOL='2'; FINA631 gera baixa do título origem.
Próximo passo: consultar status via GET Transferencia/{numsol} ou registrar em sistema do solicitante.

numsolstring · obrigatório

000001

excluir-transferencia

POST /_excluir

Exclusão de solicitação em aberto que não será mais aprovada (cancelamento do pedido).

Quando usar: solicitação criada indevidamente, ou rejeição definitiva antes da aprovação.
Pré-condição: E6_SITSOL='1'. Aprovadas devem ser estornadas (volta para "em aberto") antes de excluir.
Resultado: registro removido do SE6.

numsolstring · obrigatório

000001

estornar-transferencia

POST /_estornar

Reverte aprovação prévia: volta a solicitação para o estado "em aberto".

Quando usar: aprovação feita por engano; necessidade de revisar a transferência antes da efetivação financeira.
Pré-condição: E6_SITSOL='2'.
Resultado: E6_SITSOL='1'; títulos associados voltam ao estado anterior à aprovação.
Próximo passo: re-aprovar via _aprovar ou excluir via _excluir.

numsolstring · obrigatório

000001

Pendências conhecidas (rev1)

Sem GET próprio. Estado da solicitação é consultado via endpoint Transferencia/{numsol} (mesmo serviço que faz a inclusão). Documentação cruzada nesta biblioteca aguarda o endpoint Transferencia ser formalizado.

Dependência externa de MV_NATTRFF. Sem o parâmetro definido, o FINA631 rejeita com mensagem "Natureza não encontrada". O endpoint não valida a existência do parâmetro previamente — só captura o erro do MsExecAuto e devolve 422.

Smoke depende de fixture pré-criada. test-aprovacao-transf.sh usa Transferencia/INCLUIR no pre-flight; se aquele endpoint não estiver de pé, o smoke falha em set-up (não em execução).

Mensagens do FINA631 não traduzidas. Em rejeição (422), o aRet[2] do wrapper traz a mensagem bruta do MsExecAuto (português técnico do AdvPL). Tradução editorial uniforme pendente.