Adiantamento de Fornecedor
AdiantamentoFornecedor
Rotina do módulo Financeiro responsável por registrar o “Adiantamento a fornecedor” — um lançamento de contas a pagar que antecipa um pagamento a um participante (fornecedor) antes da vinculação a uma fatura/nota fiscal real, gerando automaticamente o(s) título(s), o(s) cheque(s) (quando aplicável) e os lançamentos financeiros e contábeis correspondentes.
Visão Geral
Rotina do módulo Financeiro responsável por registrar o “Adiantamento a fornecedor” — um lançamento de contas a pagar que antecipa um pagamento a um participante (fornecedor) antes da vinculação a uma fatura/nota fiscal real, gerando automaticamente o(s) título(s), o(s) cheque(s) (quando aplicável) e os lançamentos financeiros e contábeis correspondentes. É uma tela filha do grupo de menu “Transferências”. A regra de negócio é compartilhada com a rotina de Adiantamento de Cliente — ambas chamam o mesmo serviço de inclusão de título, que internamente decide se o adiantamento é de contas a pagar (Fornecedor) ou de contas a receber (Cliente) conforme o módulo informado pelo controller.
Endpoints
[POST] /AdiantamentoFornecedor/Salvar
Registra um novo adiantamento a fornecedor a partir dos dados informados na tela. Internamente, delega para o serviço de inclusão de título (IServicoDeInclusaoDeTitulo), sempre com o módulo fixado em “Contas a Pagar” (ListaAtualizarModulo.tcPagar) e sempre com a categoria de lançamento contábil “120” — este endpoint nunca gera adiantamento de cliente (Contas a Receber); esse é um fluxo tratado por outra rotina. Após a inclusão, o sistema retorna, em uma única resposta, os cheques gerados/vinculados, as movimentações financeiras e os lançamentos contábeis produzidos pela operação.
Permissão: “AdiantamentoFornecedor/Salvar” (ID 3005)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| dto | DTOCabecalhoDeOperacoes (corpo da requisição) | Sim | Cabeçalho da operação, contendo a filial, a lista de títulos a processar (apenas o primeiro item da lista é considerado), os cheques próprios e de terceiros informados, a forma de pagamento, a data de lançamento, o documento e a observação |
“` POST /AdiantamentoFornecedor/Salvar { “IDDaFilial”: “01”, “IDDaFormaDeCobranca”: 8, “DataDeLancamento”: “2026-09-09”, “Documento”: “98765”, “Observacao”: “Adiantamento pago em espécie”, “TitulosAProcessar”: [ { “IDDaCarteira”: 2, “IDDoParticipante”: 789, “Valor”: 2500.00 } ], “ChequesProprios”: [], “ChequesDeTerceiros”: [] } “`
“`json { “success”: true, “listaDeOperacoesFinanceiras”: [], “listaDeCheques”: [], “listaDeOperacoesContabeis”: [] } “`
Se dto.TitulosAProcessar vier vazio ou nulo, a ação não chama o serviço de negócio e apresenta a mensagem “Operação Cancelada. Alguns dados podem estar incorretos. Verifique se os dados informados estão corretos e tente novamente.” (ver Regras de Negócio).
[POST] /AdiantamentoFornecedor/Imprimir
Prepara o arquivo-modelo do comprovante de adiantamento (Crystal Reports) para impressão. Não executa nenhuma regra de negócio nem grava dados de adiantamento — apenas garante que a pasta de destino exista e copia o arquivo-modelo “ComprovanteCaixaAdiantamento.rpt” da pasta padrão para a pasta de destino, caso ainda não exista lá.
Permissão: “AdiantamentoFornecedor/Imprimir” (ID 3006)
Parâmetros: nenhum
“` POST /AdiantamentoFornecedor/Imprimir “`
“`json { “success”: true } “`
[GET] /AdiantamentoFornecedor/ValidarInclusaoDeCheque
Verifica, para uma lista de cheques informada, quais deles já estão vinculados a outro adiantamento (e por isso não podem ser reutilizados nesta operação) e quais estão livres para uso. É usada pela tela antes de permitir que o usuário inclua um cheque de terceiro no adiantamento.
Permissão: coberta pela permissão de acesso à rotina “EditViewDeAdiantamentoFornecedor” (ID 1556) — não possui permissão granular própria.
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| IDsDosCheques | List<string> (query string) | Sim | Lista de IDs de cheques a validar |
“` GET /AdiantamentoFornecedor/ValidarInclusaoDeCheque?IDsDosCheques=CHQ001&IDsDosCheques=CHQ002 “`
“`json { “success”: true, “listaChequesOK”: [“CHQ001”], “listaChequesJaVinculados”: [“CHQ002”] } “`
Modelos de Dados
DTOCabecalhoDeOperacoes (cabeçalho enviado pela tela)
| Campo | Tipo | Descrição |
|---|---|---|
| IDDaFilial | string | Filial informada na tela (é sobrescrita internamente pela filial logada do usuário — ver Regras de Negócio) |
| DataDeLancamento | DateTime | Data de lançamento da operação |
| Documento | string | Número/identificação do documento informado |
| Observacao | string | Observação livre digitada pelo usuário |
| IDDaFormaDeCobranca | int | Forma de pagamento selecionada (obrigatória para o fluxo de contas a pagar) |
| TitulosAProcessar | List[DTODeTituloAProcessar] | Lista de títulos a processar — apenas o primeiro item é efetivamente utilizado pelo fluxo de adiantamento a fornecedor |
| ChequesProprios | List[DTODeChequesProprios] | Cheques próprios (emitidos pela empresa) usados para pagar o adiantamento — determina se o sub-fluxo executado é à vista ou a prazo, conforme a data de vencimento de cada cheque |
| ChequesDeTerceiros | List[DTODeChequesDeTerceiros] | Cheques de terceiros (recebidos de outro participante e repassados como pagamento) usados para pagar o adiantamento — determina qual sub-fluxo interno é executado, ver Regras de Negócio |
DTODeTituloAProcessar (campos relevantes ao fluxo de adiantamento a fornecedor)
| Campo | Tipo | Descrição |
|---|---|---|
| IDDaFilial | string | Filial do título (sobrescrita pela filial logada) |
| IDDaCarteira | int | Carteira (conta bancária/caixa) usada na operação — obrigatória junto com a filial |
| IDDoParticipante | int | Participante (fornecedor) do adiantamento |
| Valor | decimal | Valor do adiantamento |
| SerieDoDocumento | string | Série do documento |
| NumeroDoDocumento | int | Número do documento |
| NumeroDaParcela | int | Sempre forçado para 1 neste fluxo |
| QuantidadeDeParcelas | int | Sempre forçado para 1 neste fluxo |
| DataDeVencimento / DataDeVencimentoUtil | DateTime | Sempre forçadas para a data atual, exceto no sub-fluxo de cheque de terceiros, onde a data é ajustada para não ficar anterior à data de movimentação configurada para o usuário (adiantamento comum não tem vencimento futuro) |
| IDDoTipoDeDocumento | string | Se não informado, assume um tipo de documento padrão de configuração (o mesmo tipo usado para verificar se um cheque já está vinculado a outro adiantamento) |
| NaturezaDoTitulo, NumeroDoTituloAuxiliar, CodigoDeBarras, NossoNumero | string | Sempre zerados/forçados para vazio neste fluxo |
| ValorDaCotacao | decimal | Sempre forçado para 0 |
| IDDoVendedor | int? | Sempre forçado para nulo |
| ChaveDeFato | string | Chave de fato do título gerado (distinta da chave de integração que amarra o conjunto da operação) |
Os demais campos de DTODeTituloAProcessar pertencem a outros fluxos (boleto, remessa bancária, tributos, PIX etc.) e não são utilizados pela rotina de Adiantamento a Fornecedor.
Regras de Negócio
Regra 1 — Filial e carteira são obrigatórias. Se a filial ou a carteira não forem informadas (ou a carteira informada não existir), a operação é bloqueada.
Regra 2 — Carteira deve pertencer à mesma filial do título. A carteira informada precisa pertencer à mesma filial informada para o título, a menos que a carteira seja do tipo Caixa (nesse caso a validação é dispensada).
Regra 3 — A filial informada na tela é substituída pela filial logada do usuário. Independentemente do que for digitado no campo de filial, o sistema sempre grava a filial do usuário logado no momento da operação.
Regra 4 — Forma de pagamento é obrigatória. Como este fluxo sempre opera em Contas a Pagar, é obrigatório informar uma forma de pagamento; caso contrário a operação é bloqueada.
Regra 5 — O usuário logado precisa ter um cadastro configurado. Se o usuário logado não tiver um cadastro geral associado, a operação é bloqueada.
Regra 6 — Toda a operação ocorre dentro de uma transação única. O sistema abre uma transação antes de processar o adiantamento e só confirma ao final — se qualquer etapa falhar, nada é persistido. Uma mesma operação pode gerar múltiplos títulos, cheques e movimentações (quando há mistura de cheque próprio à vista, cheque próprio a prazo e cheque de terceiros na mesma solicitação), e tudo isso é gravado (ou revertido) como uma única unidade.
Regra 7 — Existem quatro sub-fluxos de persistência, conforme a forma de pagamento do adiantamento. Os sub-fluxos não são mutuamente exclusivos entre si (uma mesma operação pode combinar cheques próprios à vista, a prazo e de terceiros), exceto o sub-fluxo “em dinheiro”, que só ocorre quando nenhum cheque é informado.
- Cheque próprio à vista (vencimento do cheque igual à data de movimentação): para cada cheque informado, o sistema cria dois títulos a pagar (um para o adiantamento, outro vinculado à inclusão do cheque), registra o cheque com status “Gerado” e gera duas movimentações financeiras (débito referente ao adiantamento e crédito referente à inclusão do cheque). Apenas a movimentação de débito do adiantamento é enviada para a integração contábil.
- Cheque próprio a prazo (vencimento diferente da data de movimentação): mesmo padrão do cheque à vista (dois títulos, um cheque, duas movimentações), com uma diferença: o título de adiantamento recebe adicionalmente uma marcação de liberação/aprovação, ausente no sub-fluxo à vista. Também apenas a movimentação de débito do adiantamento é enviada para a integração contábil.
- Cheque de terceiros (cheque recebido de outro participante e repassado como pagamento ao fornecedor): o sistema cria um único título de adiantamento vinculado ao cheque já existente, ajusta a data de vencimento do título para não ficar anterior à data de movimentação configurada para o usuário, marca o título com liberação/aprovação e gera a movimentação de débito do adiantamento. Em seguida, executa a liquidação do cheque de terceiros (a transferência de posse do cheque, que a empresa detinha, para pagamento do fornecedor) usando o fato contábil de liquidação. Este é o único sub-fluxo em que duas movimentações da mesma iteração (a do adiantamento e a da liquidação do cheque) são enviadas juntas para a integração contábil.
- Sem nenhum cheque informado (pagamento em dinheiro/transferência bancária): o sistema cria um único título de adiantamento com marcação de liberação/aprovação, e gera duas movimentações — uma de débito ligada ao adiantamento e uma de crédito ligada ao banco (marcada como conciliada na data de lançamento). Apenas a movimentação de débito do adiantamento é enviada para a integração contábil; a movimentação bancária é persistida mas não gera lançamento contábil direto neste sub-fluxo.
Em todos os sub-fluxos, o(s) título(s) de adiantamento são criados com status “Aberto” — a baixa/compensação não ocorre dentro desta rotina (ver seção “Lógica Contábil e Financeira”).
Regra 8 — Falha inesperada durante a inclusão. Se ocorrer qualquer erro não tratado durante o processamento, a operação é interrompida e a mensagem abaixo é exibida, contendo o detalhe técnico do erro ocorrido:
Regra 9 — Ausência de títulos a processar impede o salvamento. Se a tela enviar a requisição sem nenhum título na lista de títulos a processar, o sistema não chama a regra de negócio e apresenta a mensagem abaixo:
Regra 10 — Um cheque já vinculado a outro adiantamento não pode ser reutilizado. A tela consulta, cheque a cheque, se ele já está vinculado a algum adiantamento anterior (existe alguma movimentação financeira gravada para aquele cheque com o tipo de documento padrão de adiantamento). Cheques já vinculados são sinalizados separadamente dos cheques livres para uso, e a tela deve impedir sua reutilização nesta nova operação.
Observação de escopo: este fluxo é exclusivo de Contas a Pagar (o controller sempre invoca o serviço com o módulo “tcPagar” e nunca marca a operação como “adiantamento de cliente”). O fluxo equivalente de adiantamento de cliente (Contas a Receber) existe no mesmo serviço de negócio, mas pertence a outra rotina e não faz parte desta documentação — ver comparação abaixo.
Diferenças em relação ao Adiantamento de Cliente: o fluxo de Fornecedor possui divisão entre cheque próprio à vista e a prazo (inexistente no Cliente); em compensação, o fluxo de Cliente valida se existe uma sequência de numeração ativa para a filial/documento (validação inexistente no Fornecedor). A categoria de lançamento contábil também é diferente (“120” no Fornecedor, “209” no Cliente), assim como a mensagem exibida quando a lista de títulos vem vazia.
Lógica Contábil e Financeira
Esta seção detalha, em nível técnico, onde e como o adiantamento a fornecedor é efetivamente gravado no banco de dados, e como ele é posteriormente compensado (baixado) contra um título real. O objetivo de negócio da rotina é sempre o mesmo: gerar um lançamento de saída (caixa/banco ou cheque) e, ao mesmo tempo, um título a pagar em aberto que representa o valor antecipado ao fornecedor — título esse que fica “pendurado” até ser compensado, no futuro, com um título a pagar de verdade (por exemplo, oriundo de uma nota fiscal de compra).
Tabelas envolvidas
| Tabela | Entidade/Camada | O que é gravado |
|---|---|---|
| TBTITULOPAG | Titulo / TituloAPagar | O(s) título(s) a pagar gerado(s) pelo adiantamento (o título do adiantamento propriamente dito e, quando há cheque próprio, o título vinculado à inclusão do cheque). É gravado com status “Aberto” — permanece pendente até a compensação. |
| TBMOVTOFIN | MovimentacaoFinanceira | As movimentações financeiras (lançamentos de débito e crédito) geradas pela operação — ligada ao(s) título(s) pela chave de fato (idIntegracao) e numerada por lançamento (numLancto). |
| TBMOVTOCTB | MovimentacaoContabil | O lançamento contábil correspondente, gerado a partir das movimentações financeiras marcadas para integração — é o reflexo, na contabilidade, de cada movimentação enviada. |
Ou seja: a tabela “tbMovtoFin” corresponde à tabela TBMOVTOFIN (movimentação financeira), e “tbMovtoCtb” corresponde à tabela TBMOVTOCTB (movimentação contábil) — o mesmo padrão de gravação usado pela rotina de Adiantamento de Cliente.
Fato contábil utilizado
Cada movimentação financeira gravada carrega um “fato contábil” (o código que a contabilidade usa para saber qual regra de lançamento contábil aplicar). Os fatos contábeis utilizados por esta rotina são:
- ADIANTAMENTO (código “TPAGAD”) — usado na movimentação de débito ligada ao título de adiantamento, em todos os sub-fluxos, com uma variação diferente conforme o meio de pagamento: “Cheque à Vista”, “Cheque a Prazo”, “Cheque de Terceiros” ou “Sem Variação” (sub-fluxo em dinheiro).
- INCLUSÃO (código “TPAGINC”) — usado na movimentação de crédito ligada à inclusão do cheque, nos sub-fluxos de cheque próprio à vista e a prazo (variação “Cheque à Vista”/”Cheque a Prazo”).
- TRANSFERENCIA (código “BCOTRNF”, variação “Adiantamento”) — usado na movimentação de crédito ligada ao banco/caixa, no sub-fluxo sem nenhum cheque (pagamento em dinheiro) — é o lançamento que representa a saída do dinheiro do caixa/banco, marcado com a categoria de lançamento contábil “120”. Este é o único fato contábil desta rotina em que a categoria de lançamento é aplicada.
- LIQUIDAÇÃO (código “TRECLIQ”, variação “Cheque de Terceiros”) — usado no sub-fluxo de cheque de terceiros, para registrar a transferência de posse (liquidação) do cheque de terceiro que a empresa detinha, dado como pagamento ao fornecedor.
Lógica de gravação em TBMOVTOFIN e TBMOVTOCTB
- É gerada uma chave de fato (idIntegracao) única para a operação — essa chave amarra o(s) título(s), todas as movimentações financeiras e os lançamentos contábeis entre si, e é o valor retornado à tela para reconsultar cheques, movimentações e lançamentos contábeis gerados.
- O(s) título(s) de adiantamento (e, quando houver cheque próprio, o título vinculado ao cheque) são criados e gravados em TBTITULOPAG com status “Aberto”.
- São criadas as movimentações financeiras de cada sub-fluxo executado e gravadas em TBMOVTOFIN, cada uma com a chave de fato, o número do lançamento (numLancto) e seu respectivo fato contábil.
- Em todos os sub-fluxos, apenas a movimentação de débito ligada ao adiantamento é enviada para a integração contábil, com exceção do sub-fluxo de cheque de terceiros, no qual a movimentação de débito do adiantamento e a movimentação de liquidação do cheque são enviadas juntas. A movimentação de crédito da inclusão do cheque (sub-fluxos à vista/a prazo) e a movimentação bancária (sub-fluxo em dinheiro) são persistidas, mas não geram lançamento contábil direto por esta via.
- A integração contábil (responsável por gravar em TBMOVTOCTB) recebe, ao final do processamento — em uma única chamada agregando todos os sub-fluxos executados —, a lista de movimentações financeiras marcadas para integração, e gera, para cada uma, o lançamento contábil correspondente em TBMOVTOCTB, refletindo o fato contábil de cada movimentação.
- Toda a sequência (título(s), cheque(s) quando houver, movimentações financeiras e integração contábil) ocorre dentro de uma única transação — se qualquer etapa falhar, nada é persistido (ver Regra 6).
Compensação do adiantamento (baixa futura)
O título de adiantamento é gravado propositalmente com status “Aberto”: ele representa um valor pago antecipadamente ao fornecedor, mas ainda não vinculado a nenhuma nota fiscal/compra real. A baixa (compensação) desse título não é feita por esta rotina, e sim por uma rotina irmã, específica para isso: “Compensação de Pagamento x Adiantamento a Fornecedor” (tela de Extra-Caixa > Compensações), tipicamente usada quando o fornecedor emite a nota fiscal correspondente ao adiantamento já pago.
Nessa rotina de compensação, o sistema:
- Verifica se os títulos selecionados para compensação estão bloqueados; se estiverem, a operação é interrompida com uma mensagem informando o título e o valor bloqueado.
- Localiza o título de adiantamento em aberto e um título a pagar real (de nota fiscal/compra) do mesmo fornecedor.
- Usa o fato contábil LIQUIDACAO (código “TPAGLIQ”, variação “Compensação de Adiantamento”) para gerar o lançamento financeiro e contábil da baixa — ou seja, um novo registro em TBMOVTOFIN (e o respectivo reflexo em TBMOVTOCTB) que baixa o valor do adiantamento contra o título real.
- Ao final, o título de adiantamento deixa de estar em aberto (é compensado/baixado) e o título real a pagar é quitado (total ou parcialmente) pelo valor do adiantamento.
A mesma tela de compensação também expõe funcionalidades auxiliares de listagem (participantes e títulos elegíveis para compensação) e um indício de suporte a compensação de devolução a fornecedor pela mesma rotina — pontos que estão fora do escopo desta documentação, focada na inclusão do adiantamento.
Em resumo: esta rotina (Adiantamento a Fornecedor) cria a “ponta de saída” da antecipação — o dinheiro que sai do caixa/banco (ou o cheque emitido/repassado) e o título em aberto —, e a rotina de Compensação cria a “ponta de entrada” — a liquidação desse título em aberto contra um título a pagar real, fechando o ciclo da antecipação.
Permissões
Acesso à rotina: “EditViewDeAdiantamentoFornecedor” (ID 1556)
| Ação | Permissão | ID |
|---|---|---|
| Salvar | “AdiantamentoFornecedor/Salvar” | 3005 |
| Imprimir | “AdiantamentoFornecedor/Imprimir” | 3006 |
| ValidarInclusaoDeCheque | coberta por “EditViewDeAdiantamentoFornecedor” | — |