Cobranças / Boletos bancários

O motor de cobrança é a parte do sistema que emite, registra e acompanha boletos bancários junto ao banco. O boleto não tem tela própria: ele é gerido dentro da tela de contas a receber, na subtabela que aparece ao expandir a linha de um título. Cada boleto percorre um ciclo de vida — rascunho, registrando, registrado, rejeitado, liquidado, baixado ou baixa pendente — e o motor cuida sozinho do registro no banco, da liquidação quando o cliente paga, da baixa por cancelamento e dos alertas quando algo trava.

Por trás de cada boleto há um convênio bancário: o cadastro, vinculado à conta bancária, que guarda as credenciais do banco e os encargos (juros, multa e desconto) com os quais o boleto sai. Sem convênio ativo, não há boleto.

Como acessar

Não há um item de menu Cobranças / Boletos. Os boletos vivem dentro da tela de contas a receber: abra Financeiro › Contas a receber, localize o título e clique na seta à esquerda da linha para expandir a subtabela de boletos daquela conta. Toda a gestão — reimprimir, consultar a situação no banco, prorrogar o vencimento, registrar recebimento, cancelar a cobrança, registrar de novo após cancelar, resolver divergência, resolver cancelamento de baixa — sai do menu de ações dessa subtabela.

Se o item Contas a receber não aparece no menu, seu perfil de acesso ainda não tem permissão para a carteira de recebíveis — peça ao administrador do sistema. As ações sobre cada boleto, por sua vez, seguem a permissão de financeiro › boletos: quem só pode ler vê o histórico, mas não registra nem cancela; quem pode criar registra (rascunho ou de novo após baixado) e reemite; quem pode editar prorroga o vencimento, registra recebimento, cancela cobrança, resolve divergência e resolve cancelamento de baixa.

O motor de cobrança e o convênio bancário

O motor de cobrança é quem fala com o banco no lugar do operador. Quando um boleto precisa ser registrado, é o motor que envia os dados ao banco. Quando o boleto é pago, o motor dá a baixa de dois jeitos: pelo aviso imediato do banco (por webhook) e pela consulta periódica ao banco, para um pagamento não ficar registrado se o aviso atrasar. Quando uma venda é devolvida, o motor cancela a cobrança no banco para o cliente não ser cobrado indevidamente. O operador não precisa ir ao portal do banco para nada do que o motor faz.

O convênio bancário é o cadastro que habilita essa conversa. Ele é vinculado a uma conta bancária (no cadastro de contas bancárias) e descreve como sua empresa se apresenta àquele banco como beneficiária dos boletos: o número do convênio (Banco do Brasil), a cooperativa e o posto (Sicredi), as credenciais de acesso à API do banco e os encargos padrão. Um boleto só pode ser emitido por uma conta que tenha um convênio ativo.

Os encargos do boleto vêm do convênio, não da forma de pagamento

Juros, multa e desconto de um boleto são definidos no convênio bancário da conta que emite — não na forma de pagamento que o originou. A forma de pagamento só decide que a cobrança é um boleto e qual conta emite; os encargos saem do convênio. Por isso, ao ajustar juros ou multa de um boleto, mexa no convênio da conta, não na forma de pagamento.

O motor já vem pronto para os provedores suportados, cada um com suas peculiaridades (veja Provedores suportados).

Como o boleto nasce

Um boleto nasce sozinho, sem o operador digitá-lo, quando um pedido de venda cobrado por boleto é faturado. Cada parcela da forma de pagamento da categoria Boleto bancário vira um título no contas a receber e, junto, um boleto. A conta destino dessa forma precisa ter um convênio ativo — convênio em outra conta da empresa não gera boleto neste pedido. Emitir a nota fiscal do pedido não cria boleto: o boleto já nasceu no faturamento.

No momento do faturamento, o motor já envia o boleto para registro no banco. O operador acompanha esse registro em tempo real, numa animação que mostra a conexão com o banco e o resultado — registrado (o banco aceitou) ou rejeitado (o banco recusou). Não é preciso faturar e depois ir registrar o boleto: o registro é parte do faturamento.

Caso o registro automático falhe ou o boleto seja rejeitado, é possível registrá-lo ou reemiti-lo manualmente pela subtabela (veja A subtabela de boletos). O boleto carrega os dados do pagador (nome, documento e endereço do cliente) e o valor nominal e o vencimento da parcela que o originou.

O ciclo de vida do boleto

Cada boleto carrega um status que reflete onde ele está no banco. O ciclo normal é: o boleto nasce rascunho, vai a registrando quando é enviado ao banco, passa a registrado quando o banco aceita, e liquidado quando é pago. Desse caminho saem dois atalhos: o banco pode rejeitar o registro, e o boleto pode ser baixado (cancelado no banco). Quando a baixa falha, ele fica em baixa pendente até o retry conseguir.

Os status são:

• Rascunho — o boleto foi criado, mas ainda não foi enviado ao banco. É o estado de passagem entre a criação (no faturamento) e o início do registro.
• Registrando — o motor enviou o boleto ao banco e aguarda a resposta. Em geral é breve; se travar aqui, use Consultar situação na subtabela para confirmar o estado atual no banco.
• Registrado — o banco aceitou o boleto. Ele está ativo, pronto para o cliente pagar, e pode ser reimpresso. É o estado normal de um boleto aguardando pagamento.
• Rejeitado — o banco recusou o registro. O motivo fica registrado e pode ser lido com Ver motivo da rejeição na subtabela; é possível reemitir depois de corrigir a causa.
• Liquidado — o boleto foi pago. O pagamento chega por webhook (o banco avisa o motor), pela consulta periódica do motor ao banco (se o aviso atrasar) ou por recebimento manual registrado pelo operador. Ao liquidar, o contas a receber marca o título como pago (mesmo que o valor recebido seja menor que o nominal, por desconto). O valor recebido na conta guarda o que de fato entrou.
• Baixado — a cobrança foi cancelada no banco. Acontece quando uma venda é devolvida (o motor cancela a cobrança para não cobrar o cliente) ou quando o operador usa Cancelar cobrança no banco. O boleto deixa de ser cobrável; o título no contas a receber segue seu próprio status. Na subtabela, o operador pode Registrar no banco de novo: nasce um boleto novo na mesma conta, com nosso número novo, sem faturar outra vez.
• Baixa pendente — o motor tentou baixar o boleto no banco e falhou (banco indisponível, por exemplo). Ele fica nesse estado e o motor re-tenta automaticamente até conseguir (veja Cancelamento por devolução e Boleto preso em baixa pendente).

Na subtabela de boletos, cada status aparece com uma cor própria, para ser lida de relance: cinza para rascunho, amarelo para registrando, laranja para registrado, vermelho para rejeitado, verde para liquidado, roxo para baixado e rosa para baixa pendente.

A subtabela de boletos

A subtabela de boletos é a única superfície de gestão do boleto. Ela aparece ao expandir a linha de um título na lista de contas a receber. Cada boleto da conta vira uma linha com:

• Nosso número — o identificador do boleto no banco. Boletos ainda não registrados (e os rejeitados sem número) aparecem com um traço.
• Banco / Convênio — o banco emissor e o número do convênio usado.
• Valor — o valor nominal do boleto (o da parcela que o originou).
• Vencimento — a data de vencimento da cobrança.
• Status — a situação atual (veja O ciclo de vida do boleto).

O menu de ações (à esquerda de cada linha, no ícone de três pontos) oferece operações diferentes conforme o status do boleto e a permissão do operador:

• Reimprimir PDF — abre o boleto em PDF para imprimir ou enviar ao cliente. Disponível em quase todos os status em que já há boleto.
• Consultar situação — pergunta ao banco o estado atual do boleto e mostra o status no toast (Registrado, Liquidado, Baixado, Rejeitado ou Vencido). Essa consulta não persiste o status na subtabela: o badge só muda quando o banco avisa por webhook ou quando a consulta periódica do motor encontra o pagamento. Vencido existe só nessa consulta: o badge da subtabela não vira Vencido (o status persistido continua Registrado até liquidar ou baixar). Útil quando o status da subtabela parece desatualizado (um boleto parado em registrando, por exemplo).
• Ver motivo da rejeição — mostra o motivo que o banco informou ao recusar o registro. Disponível só em rejeitado.
• Registrar no banco — em rascunho, envia o boleto para registro. Em baixado, cria um boleto novo na mesma conta a receber (valor e vencimento do título, nosso número novo) e dispara o registro — não reusa o número do boleto cancelado e não exige faturar de novo. Em geral o faturamento já registra; estas ações cobrem o caso em que o registro automático não aconteceu e o caso em que a cobrança foi cancelada e precisa voltar.
• Reemitir — reenvia um boleto rejeitado ao banco, depois de corrigir a causa da rejeição. O boleto volta a registrando.
• Prorrogar vencimento — altera a Nova data de vencimento de um boleto registrado no Banco do Brasil, sem cancelar. A data é obrigatória, precisa ser hoje ou posterior e diferente do vencimento atual do boleto. A alteração muda só o vencimento do boleto (PDF e linha digitável); o vencimento do título na lista de contas a receber permanece. Um Registrar no banco depois de cancelar usa o vencimento do título, não o prorrogado. O banco só aceita a alteração 30 minutos após o registro; se ainda não passou, o diálogo avisa o horário a partir do qual dá para tentar. Boleto sem horário de registro mostra «Este boleto não tem horário de registro. O banco recusa a alteração.» No Sicredi a ação não aparece — cancele e registre de novo.
• Registrar recebimento — dá baixa no título pelo valor do boleto, com campos opcionais de juros, multa, desconto e abatimento para refletir o que o cliente efetivamente pagou. Disponível em registrado; some quando o título já está pago ou pago parcial (a conta já foi quitada, não há o que receber).
• Cancelar cobrança no banco — solicita a baixa do boleto no banco. O boleto vai a baixado; o título no contas a receber não é mexido (para dar baixa no título, use Registrar recebimento). Se o banco recusar (por exemplo, ainda dentro dos 30 minutos após o registro), a subtabela mostra o motivo real — não um sucesso falso. Depois de baixado, use Registrar no banco para emitir outro boleto na mesma conta.
• Resolver divergência — aparece quando um pagamento chega com valor diferente do registrado. Mostra o valor esperado e o valor recebido, e deixa o operador aceitar o valor que veio do banco, manter o registrado ou ajustar para outro valor.
• Resolver cancelamento de baixa — aparece quando o banco cancela uma baixa operacional já liquidada (o boleto tinha sido dado como pago e o banco desfez o aviso). A conta não é estornada sozinha. O operador escolhe manter a liquidação (só fecha o alerta) ou estornar (reabre o boleto e desfaz o valor na conta a receber).

Nem toda ação aparece sempre: o menu é montado conforme o status do boleto, a permissão do operador e o estado do título. Quando a subtabela está vazia, o título não tem boletos vinculados.

O boleto impresso (PDF)

O PDF do boleto é o documento que o cliente paga — o Recibo do pagador e a Ficha de compensação. Para abri-lo, use Reimprimir PDF na subtabela.

O beneficiário (quem recebe) que aparece no boleto é sempre a razão social da empresa emitente, nunca o nome de fantasia. É assim nos dois blocos do documento, para que o nome jurídico seja o mesmo no recibo e na ficha de compensação. Se o cliente perguntar por que o boleto mostra o nome jurídico em vez do nome de fantasia da empresa, é por isso: o documento de cobrança usa o nome registrado.

O layout do PDF é ancorado no topo da folha A4: o cabeçalho e o bloco de cobrança começam respeitando a margem superior, e o respiro de papel fica em baixo. Isso garante que a impressão comece do cabeçalho, sem risco de a ficha de compensação ser cortada na impressora.

Cancelamento por devolução

Quando uma venda é devolvida por inteiro, o título no contas a receber é cancelado — e o motor de cobrança cuida de cancelar a cobrança no banco automaticamente, para que o cliente não seja cobrado por mercadoria devolvida. O operador não precisa ir à subtabela cancelar boleto por boleto.

O motor decide o caminho conforme o estado de cada boleto vinculado ao título:

• Boletos sem nosso número (rascunho, registrando ou rejeitado) — não há o que cancelar no banco; o motor os marca como baixado localmente.
• Boletos registrados (com nosso número) — o motor solicita a baixa ao banco. Se o banco aceitar, o boleto vai a baixado.
• Boletos já liquidados ou baixados — são mantidos como estão (nada a refazer).

Quando a baixa no banco falha (banco indisponível, por exemplo), o boleto não fica perdido: ele vai a baixa pendente, e o motor passa a tentar de novo automaticamente com intervalo crescente (começa em dez minutos e sobe até no máximo quatro horas entre tentativas), até conseguir. A cobrança, do lado do título, já está suspensa (o título foi cancelado); o que falta é só confirmar o cancelamento no banco. Assim que a causa passa (o banco volta a responder), a próxima tentativa do motor baixa o boleto.

Boleto preso em baixa pendente

Quando um boleto está em baixa pendente há muito tempo, o motor avisa o operador na tela de contas a receber com o alerta “Boleto … está preso em baixa pendente (após … tentativas)” — onde as reticências trazem o nosso número do boleto e a contagem de tentativas já feitas. O aviso também mostra o motivo informado pelo banco.

As causas mais comuns são:

• Nosso número inválido — o número do boleto no banco não bate com o que o motor enviou;
• Convênio bancário desativado — o convênio da conta que emite perdeu o acesso ao banco (credenciais vencidas, convênio cancelado no portal);
• Banco indisponível — o banco está fora do ar ou recusando a chamada.

O que o operador faz: anote o Nosso número e o motivo do aviso, localize o título correspondente (filtre por pedido de venda ou nota fiscal se já souber a origem) e acione quem cuida do convênio bancário para confirmar se está ativo e com os dados corretos. Para investigar sem esperar o próximo ciclo, expanda a linha do título e, na subtabela de boletos, use Consultar situação (confirma o estado atual no banco) e, se for o caso, Cancelar cobrança no banco (solicita a baixa direto).

O motor continua tentando sozinho, mesmo depois do aviso. Quando a causa é resolvida (convênio reativado, nosso número corrigido), a próxima tentativa baixa o boleto e o aviso deixa de aparecer. O alerta é disparado depois de várias tentativas seguidas sem sucesso — um sinal de que a causa é estrutural (convênio, nosso número) e não uma indisponibilidade pontual do banco.

Divergência de valor

Quando o banco avisa que um boleto foi pago com valor diferente do registrado, o motor emite um alerta na tela de contas a receber: “Divergência de valor no boleto”, com o valor esperado e o valor recebido. O mesmo canal do aviso de boleto preso.

Para resolver, expanda a linha do título e, na subtabela de boletos, use Resolver divergência no boleto com o alerta. O operador pode:

• aceitar o valor que veio do banco (o recebido);
• manter o valor registrado; ou
• ajustar para outro valor.

A divergência costuma vir de arredondamento, de juros ou desconto que o banco aplicou de forma diferente da registrada, ou de um pagamento parcial. Resolvida, o título no contas a receber reflete o valor efetivamente recebido.

Cancelamento de baixa operacional

Depois que o boleto já está liquidado, o banco pode desfazer o aviso de pagamento — no Banco do Brasil isso chega como cancelamento da baixa operacional. O motor não zera a conta sozinho: o título permanece pago e o boleto permanece liquidado, com um alerta na tela de contas a receber (“Cancelamento de baixa no boleto”).

Para resolver, expanda a linha do título e, na subtabela de boletos, use Resolver cancelamento de baixa. O operador escolhe:

• manter a liquidação — a conta continua paga; só fecha o alerta;
• estornar — o boleto volta a registrado e o valor pago é desfeito na conta a receber (se zerar, o título volta a pendente).

Sem essa ação, o alerta permanece. Não há estorno automático.

Provedores suportados

O motor de cobrança já vem pronto para os provedores abaixo. Cada provedor tem suas peculiaridades de credencial e de como o banco avisa os pagamentos:

• Banco do Brasil (001) — autentica a aplicação por OAuth no gateway do banco, com número do convênio, carteira e variação (obrigatória). Emitir com PIX no cadastro da conta liga o Bolepix; não há campo de chave PIX para colar. O aviso de pagamento chega por webhook configurado no portal do banco e na infraestrutura da Tromso — não há interruptor no cadastro da conta. Se o aviso atrasar, o motor consulta o banco periodicamente e baixa o boleto mesmo assim. Em Sandbox o banco só aceita o convênio de teste 3128557 (carteira 17, variação 35) e pagador fictício; o convênio real vale em Produção. O nosso número é gerado pelo sistema.
• Sicredi (748) — autentica pela cooperativa, posto e código do beneficiário. As notificações automáticas de pagamento são contratadas pelo próprio sistema, direto na API do Sicredi: o operador ativa a opção no cadastro do convênio, sem ver URLs, tokens ou jargão técnico. O nosso número segue o formato próprio do Sicredi.

Novos provedores são adicionados ao motor conforme a necessidade, sem mudar a forma como o operador usa a subtabela de boletos.

Onde mais os boletos aparecem

• Na tela de contas a receber, o boleto é gerido pela subtabela de cada título — é a fonte da verdade do ciclo de vida.
• No controle de inadimplência, os títulos vencidos são observados antes de uma venda; um boleto pendente de pagamento conta como título em aberto.
• Nas movimentações financeiras, a liquidação de um boleto entra como recebimento na conta que emite.

Dúvidas frequentes

Apareceu um aviso 'Boleto está preso em baixa pendente'. O que faço?

Esse aviso indica que um boleto vinculado a um título seu tentou ser baixado no banco (geralmente por causa de uma devolução total ou de um cancelamento) e o banco vem recusando a baixa há horas — o motor de cobrança continua tentando com intervalo crescente entre as tentativas (de dez minutos até no máximo quatro horas). As causas mais comuns são nosso número inválido, convênio bancário desativado ou indisponibilidade do banco.

O aviso traz o nosso número do boleto e o motivo informado pelo banco: anote os dois, localize o título correspondente na lista (filtre por pedido de venda ou nota fiscal se já souber a origem) e acione o responsável pelo cadastro do convênio bancário para confirmar se está ativo e com os dados certos. O sistema continua tentando sozinho. Para investigar, expanda a linha do título e use a subtabela de boletos: Consultar situação confirma o estado atual no banco e, se precisar encerrar a cobrança, Cancelar cobrança no banco solicita a baixa direto. Quando a causa for resolvida (convênio reativado, nosso número corrigido), a próxima tentativa do motor baixa o boleto e o aviso deixa de aparecer.

O boleto foi rejeitado pelo banco. O que eu faço?

Um boleto rejeitado significa que o banco recusou o registro. Na subtabela de boletos, use Ver motivo da rejeição para ler o que o banco informou (campo obrigatório ausente, convênio inválido, nosso número em uso etc.). Corrigida a causa — em geral no convênio bancário da conta ou nos dados do cliente — use Reemitir para reenviar o boleto ao banco. Ele volta a registrando e, se o banco aceitar, passa a registrado.

Por que o boleto mostra a razão social e não o nome de fantasia?

O beneficiário impresso no boleto é sempre a razão social da empresa emitente, nos dois blocos do documento (recibo do pagador e ficha de compensação). É assim para que o nome jurídico seja o mesmo nas duas vias e o documento de cobrança use o nome registrado da empresa — não é um erro.

Recebi um pagamento com valor diferente do boleto. Como registro?

Quando o banco avisa um pagamento com valor diferente do registrado, o motor emite o alerta de divergência de valor na tela de contas a receber. Expanda a linha do título, abra a subtabela de boletos e use Resolver divergência no boleto afetado: aceite o valor que veio do banco, mantenha o registrado ou ajuste para outro. Resolvida, o título reflete o valor efetivamente recebido.

O banco cancelou um pagamento que já tinha liquidado o boleto. O que faço?

O motor avisa “Cancelamento de baixa no boleto” e não estorna a conta sozinho. Expanda a linha do título, abra a subtabela de boletos e use Resolver cancelamento de baixa: manter a liquidação fecha o alerta deixando a conta paga; estornar reabre o boleto e desfaz o valor na conta (se zerar, o título volta a pendente).

Cadastrei uma venda com boleto, mas não vejo o boleto na subtabela.

Um boleto só nasce quando o pedido de venda é faturado com uma forma de pagamento da categoria boleto bancário. Emitir a nota fiscal não cria boleto — o boleto já nasceu no faturamento. Se o pedido ainda está em aberto, ainda não há boleto. Se já foi faturado e mesmo assim não há boleto, confira se a forma usada é da categoria boleto e se a conta destino dessa forma tem um convênio bancário ativo — convênio em outra conta da empresa não gera boleto neste pedido. A conta destino e o convênio vivem no cadastro de contas bancárias.

Cancelando a cobrança no banco, o título também é cancelado?

Não. Cancelar cobrança no banco só cancela o boleto junto ao banco (o boleto vai a baixado); o título no contas a receber não é mexido. Para dar baixa no título pelo valor do boleto, use Registrar recebimento. O cancelamento automático do título acontece no caminho inverso: é uma devolução total da venda que cancela o título, e aí o motor cancela os boletos vinculados. Se o banco recusar o cancelamento, a subtabela mostra o motivo (não um sucesso falso). Depois de baixado, use Registrar no banco para emitir outro boleto na mesma conta, com nosso número novo, sem faturar de novo.

O cliente pagou o boleto, mas o status continua Registrado. O que acontece?

O motor dá baixa no boleto de dois jeitos: pelo aviso imediato do banco (por webhook) e pela consulta periódica ao banco. Se o aviso atrasar, o boleto permanece registrado até a consulta encontrar o pagamento; aí o status vira liquidado e o título no contas a receber marca pago. Consultar situação na subtabela mostra o estado no banco na hora, mas não grava o badge — o badge só muda com o aviso ou com a consulta periódica do motor.

O cliente pediu mais prazo. Como adio o vencimento do boleto?

No Banco do Brasil, abra a subtabela do título, no boleto registrado use Prorrogar vencimento e informe a Nova data de vencimento (hoje ou posterior, diferente da atual). Só o vencimento do boleto muda — o do título na lista permanece. O banco só aceita a alteração 30 minutos após o registro; o diálogo avisa o horário se ainda não passou, e recusa boleto sem horário de registro. O PDF e a linha digitável saem com o novo vencimento. No Sicredi essa ação não aparece: cancele a cobrança e use Registrar no banco para emitir um boleto novo na mesma conta (esse novo boleto usa o vencimento do título, não o que tinha sido prorrogado).

Cancelei o boleto por engano. Consigo cobrar de novo sem faturar outra vez?

Sim, se o boleto está baixado (e não liquidado). Na subtabela, use Registrar no banco: o sistema cria um boleto novo na mesma conta a receber, com o valor e o vencimento do título e um nosso número novo, e envia ao banco. O boleto cancelado permanece no histórico. Não há tela avulsa de boletos — tudo sai da subtabela do título.