Emissão Detalhada de Boletos

Artigo: Emissão Detalhada de Boletos

1. Visão Geral

A Emissão Detalhada permite a geração de boletos com preenchimento completo das informações de cobrança, oferecendo maior controle sobre regras, instruções e comportamentos do título após a emissão. Esse fluxo é indicado para cenários que exigem configuração de instruções detalhadas ao pagador, definição de regras de autorização de pagamento, inclusão de sacador/avalista e maior granularidade na configuração das parcelas.

2. Acesso ao Módulo

Acessado a partir da tela de Listagem de Boletos, pelo botão “Emitir boleto detalhado”. O título exibido no topo da tela é “Emissão detalhada de boletos”.

3. Dados da Cobrança

Espécie

  • Tipo: Lista suspensa (dropdown)
  • Obrigatoriedade: Sim
  • Comportamento: Carregada dinamicamente a partir dos parâmetros/cadastro da conta (endpoint /especies) — a lista de espécies pode variar entre contas. Ao acessar a tela, o sistema pré-seleciona automaticamente a espécie “Duplicata Mercantil”, quando disponível na lista.
  • Validação: Exibe mensagem de campo obrigatório quando não preenchido.

Aceite

  • Tipo: Seleção binária (chips Sim/Não)
  • Obrigatoriedade: Sim
  • Comportamento: Valor padrão: “Não”. Não impede o pagamento em caso de aceite igual a “Não”; é apenas uma informação enviada na emissão.

Informações

  • Tipo: Texto livre (área de texto)
  • Obrigatoriedade: Não
  • Comportamento: Pré-preenchido automaticamente com o texto padrão configurado nos parâmetros da conta, podendo ser editado pelo usuário antes da emissão.

  • 3.1. Instruções (exclusivo da Emissão Detalhada)

    Instruções

    • Tipo: Texto livre (área de texto)
    • Obrigatoriedade: Não
    • Comportamento: Pré-preenchido com o texto padrão de instruções configurado nos parâmetros da conta. As instruções informadas não alteram regras de cálculo ou validação — têm caráter apenas informativo, e são impressas no boleto conforme layout bancário. Podem conter, por exemplo, informações sobre prazos, avisos sobre juros e multa, ou orientações ao pagador.

3.2. Dias para Protesto e Negativação

Campos “Dias para protesto” e “Dias para negativação”: exibidos apenas quando a conta possui, respectivamente, a regra de protesto e/ou negativação habilitada nos parâmetros. Pré-preenchidos com os valores padrão da conta. Não podem ser preenchidos simultaneamente com valor maior que zero — se ambos estiverem preenchidos, a emissão é bloqueada.

Mensagem de erro (protesto e negativação preenchidos simultaneamente): “A configuração da conta possui negativação Serasa e protesto simultaneamente. Informe apenas dias para protesto ou dias para negativação.”

4. Autorização de Pagamento (exclusivo da Emissão Detalhada)

Bloco de opções (seleção única) que define regras de aceitação de pagamento divergente do valor original do boleto, controlando pagamentos parciais ou superiores.

Opção

Comportamento

Não autorizar pagamento de valor divergente do valor do documento

Opção padrão. O boleto só pode ser pago pelo valor exato emitido. Pagamentos com valor menor ou maior são recusados pelo sistema bancário. Indicada para cobranças que exigem valor fechado.

Autorizar o pagamento de qualquer valor maior que R$ 0,00

Permite que o pagador realize o pagamento de qualquer valor, desde que maior que zero. Aceita pagamentos parciais e superiores ao valor original. Comum em cobranças flexíveis, negociações ou acordos.

Autorizar valor mínimo para pagamento de:

Permite configurar um valor mínimo aceitável para pagamento; o pagador pode pagar valores iguais ou superiores ao mínimo informado. Pagamentos abaixo do valor mínimo configurado são recusados. Libera um campo numérico adicional, obrigatório quando esta opção é selecionada.

Observação sobre Pix: quando o Pix no boleto está ativo para a cobrança (ver seção 7), as opções “Autorizar o pagamento de qualquer valor maior que R$ 0,00” e “Autorizar valor mínimo para pagamento de:” ficam desabilitadas — apenas “Não autorizar pagamento de valor divergente” permanece disponível.

5. Dados do Pagador

Pagador

  • Tipo: Campo de seleção (abre modal de busca)
  • Obrigatoriedade: Sim, quando Grupo de Pagadores não estiver selecionado
  • Comportamento: Exibe o texto padrão “Nenhum pagador selecionado”; ao clicar, abre um modal de busca listando nome e CPF/CNPJ dos pagadores ativos cadastrados. Ao selecionar um pagador, o campo Grupo de Pagadores é desabilitado automaticamente.

Grupo de Pagadores

  • Tipo: Campo de seleção (abre modal de busca/cadastro)
  • Obrigatoriedade: Sim, quando Pagador não estiver selecionado
  • Comportamento: Exibe o texto padrão “Nenhum grupo de pagadores selecionado”; ao selecionar um grupo, o campo Pagador individual é desabilitado automaticamente. Apenas um grupo pode ser selecionado por emissão.

  • Pagador e Grupo de Pagadores são mutuamente exclusivos: a emissão exige exatamente um dos dois preenchidos (nunca os dois, nem nenhum dos dois).

Mensagem de erro (nenhum dos dois selecionado): “Selecione um Pagador ou Grupo de pagadores para emitir o boleto.”

6. Sacador/Avalista (exclusivo da Emissão Detalhada)

Informar sacador/avalista

  • Tipo: Interruptor (toggle)
  • Obrigatoriedade: Não
  • Comportamento: Quando ativado, libera os campos de sacador/avalista abaixo.

Sacador/avalista

  • Tipo: Campo de seleção (abre modal de busca)
  • Obrigatoriedade: Não
  • Comportamento: Abre modal de busca para selecionar um sacador/avalista pré-cadastrado.

Tipo de pessoa

  • Tipo: Lista suspensa (Física/Jurídica)
  • Obrigatoriedade: Não

CPF/CNPJ

  • Tipo: Texto
  • Obrigatoriedade: Não
  • Comportamento: O rótulo do campo muda conforme o Tipo de pessoa selecionado (CPF para Física, CNPJ para Jurídica).

Nome

  • Tipo: Texto
  • Obrigatoriedade: Não

7. Detalhamento da Parcela

Permite adicionar uma parcela avulsa ou gerar múltiplas parcelas de uma só vez, com os mesmos campos disponíveis na Emissão Rápida.

  • Ações disponíveis:
  • Múltiplas parcelas — abre o modal de geração automática de parcelas (detalhado abaixo).
  • 1 Parcela — adiciona uma única linha em branco diretamente na grade.
  • Remover as parcelas selecionadas — some apenas quando há ao menos uma parcela marcada; remove as linhas selecionadas e exibe notificação com opção “Desfazer a exclusão” por tempo limitado.

7.1. Modal de Múltiplas Parcelas

Número do Documento

  • Tipo: Texto
  • Obrigatoriedade: Sim

Número de Parcelas

  • Tipo: Numérico
  • Obrigatoriedade: Sim
  • Comportamento: Valor mínimo: 1.

Flag “Fixas”

  • Tipo: Checkbox
  • Obrigatoriedade: Não
  • Comportamento: Marcado: gera parcelas de valor fixo e igual entre si, com base no valor informado por parcela. Desmarcado: o rótulo do campo de valor muda para “Valor Total R$” e o sistema divide esse total igualmente entre as parcelas, ajustando eventuais centavos fracionados na última parcela.

Data Documento

  • Tipo: Data
  • Obrigatoriedade: Sim
  • Comportamento: Aplicada a todas as parcelas geradas.

Vencimento Inicial

  • Tipo: Data
  • Obrigatoriedade: Sim
  • Comportamento: Define o vencimento da primeira parcela; as demais são calculadas a partir dela.

Intervalo em dias

  • Tipo: Numérico
  • Obrigatoriedade: Sim
  • Comportamento: Valor padrão: 30 dias.

Flag “Mensal”

  • Tipo: Checkbox
  • Obrigatoriedade: Não
  • Comportamento: Marcado (padrão): gera vencimentos mensais, mantendo o mesmo dia do mês sempre que possível. Ao marcar, o intervalo é automaticamente ajustado para 30 dias. Desmarcado: gera vencimentos corridos, somando o intervalo de dias informado a cada parcela.

Multa (%)

  • Tipo: Numérico
  • Obrigatoriedade: Não
  • Comportamento: Pré-preenchido com o percentual padrão de multa da conta.

Juros (%)

  • Tipo: Numérico
  • Obrigatoriedade: Não
  • Comportamento: Pré-preenchido com o percentual padrão de juros da conta.

Quando a espécie selecionada é “BDP — Boleto de Proposta”, os campos de Multa e Juros do modal são zerados automaticamente e não recebem os valores padrão da conta.

  • Botão Gerar: valida os campos e cria as parcelas na grade principal.
  • Botão Cancelar: fecha o modal sem gerar parcelas.

7.2. Grade de Parcelas

Cada linha da grade representa uma parcela, com os seguintes campos editáveis: Nr. Documento, Data Documento, Data Vencimento, Valor, Desconto, Data limite desconto, Data Multa, Juros (percentual ou valor fixo, alternável por dropdown no cabeçalho), Multa (percentual ou valor fixo) e Data Juros.

Regra automática: ao definir a Data de Vencimento de uma parcela, as datas de Multa e de Juros dessa mesma parcela são preenchidas automaticamente com o dia seguinte ao vencimento (podendo ser ajustadas manualmente, exceto quando o Pix está ativo — ver seção 8).

Quando a espécie “BDP — Boleto de Proposta” está selecionada, os campos de Desconto, Data limite de desconto, Juros, Multa, Data Multa e Data Juros ficam bloqueados (não editáveis) em todas as parcelas.

Destaque visual e exibição do botão de remoção ao selecionar parcelas

Ao marcar o checkbox de uma ou mais linhas na grade de parcelas (coluna “Parc.”), a linha correspondente recebe um destaque visual de fundo, diferenciando-a das demais parcelas não selecionadas. Simultaneamente, o botão “Remover as parcelas selecionadas” passa a ser exibido na barra de ações do bloco Detalhamento da Parcela, ao lado dos botões “Múltiplas parcelas” e “1 Parcela” — esse botão permanece oculto enquanto nenhuma parcela estiver marcada. O mesmo comportamento se aplica ao marcar o checkbox do cabeçalho da tabela, que seleciona (e destaca) todas as parcelas simultaneamente. Este comportamento é idêntico ao já descrito no artigo de Emissão Rápida de Boletos, já que ambos os modos utilizam o mesmo componente de grade de parcelas.

8. Pix no Boleto (Boleto Híbrido)

Funcionalidade que permite incluir um QR Code Pix no boleto emitido, possibilitando o pagamento por Pix além dos meios tradicionais. Esta seção não constava no artigo publicado anteriormente e foi incluída a pedido do PM, que confirmou tratar-se de funcionalidade atual e vigente em produção. O Pix no boleto está disponível tanto na Emissão Detalhada quanto na Emissão Rápida.

8. Pix no Boleto (BolePix)

Funcionalidade que permite incluir um QR Code Pix no boleto emitido, possibilitando o pagamento por Pix além dos meios tradicionais. Esta seção não constava no artigo publicado anteriormente e foi incluída a pedido do PM, que confirmou tratar-se de funcionalidade atual e vigente em produção. O Pix no boleto está disponível tanto na Emissão Detalhada quanto na Emissão Rápida.

8.1. Elegibilidade e Habilitação

O Pix no boleto segue um modelo de disponibilização em etapas, controlado pelo backend (endpoint de configuração de Pix da conta):

Situação da conta

O que é exibido na tela de emissão

Não elegível (regra restrita a contas Pessoa Jurídica)

Nenhuma informação, seção, toggle ou onboarding de Pix é exibida — a seção fica totalmente oculta da tela.

Elegível, mas ainda não habilitada pelo gerente de relacionamento

A seção “Pix no boleto” aparece, com o toggle desabilitado e uma orientação para solicitar o credenciamento.

Elegível e habilitada, mas ainda não ativada pelo usuário

Ao carregar a tela de emissão, um modal de ativação do Pix é aberto automaticamente (ver seção 8.3); a seção também exibe orientação para realizar a ativação.

Elegível, habilitada e ativada

O toggle de Pix no boleto fica disponível para uso na cobrança que está sendo emitida.

Mensagem (habilitação pendente): “Para habilitar essa função, solicite o credenciamento diretamente com o seu gerente de relacionamento Cresol.”

Mensagem (ativação pendente): “Você está habilitado para o Pix. Ative-o para o seu usuário realizando o onboarding.”

8.2. Seção Pix no Boleto na Tela de Emissão

Pix no boleto

  • Tipo: Interruptor (toggle)
  • Obrigatoriedade: Não
  • Comportamento: Ativa ou desativa a inclusão do QR Code Pix nesta cobrança específica. Fica desabilitado quando a conta não está habilitada/ativada para Pix, ou quando a espécie selecionada é “BDP — Boleto de Proposta”.

O texto de descrição acima do toggle muda conforme o estado atual: “Ative o Pix para incluir QR Code nos boletos” (quando desativado) ou “QR Code Pix ativado nos boletos” (quando ativado).

Aviso exibido com o Pix ativado: “Com BolePix ativo, os campos Data de Juros e Data de Multa não podem ser alterados.”

8.3. Modal de Ativação do Pix

Quando a conta está habilitada, mas ainda não ativou o Pix, o modal de ativação é aberto automaticamente ao carregar a tela de emissão.

Elemento

Descrição

Título

“Ativar pix no boleto”

Descrição

“Ao ativar essa funcionalidade:” seguida de lista com os benefícios (QR Code nos boletos, pagamento por escaneamento ou código copia e cola, e que apenas novos boletos serão afetados).

Aviso de rodapé

Informa que a ativação é imediata para a conta e não pode ser desfeita por essa tela.

Botão primário

Ativar Pix — confirma a ativação

Botão secundário

Cancelar — fecha o modal sem ativar

Mensagem de sucesso: “Pix ativado com sucesso! Seus próximos boletos já poderão ser emitidos com QR Code Pix.”

Mensagem de erro: “Não foi possível ativar o Pix. Tente novamente.”

8.4. Impacto do Pix nas Regras de Emissão

Com o Pix ativado para a cobrança em edição, as seguintes restrições passam a valer automaticamente:

Regra afetada

Comportamento com Pix ativo

Datas de Multa e Juros (por parcela)

Preenchidas automaticamente com o dia seguinte ao vencimento e bloqueadas para edição manual em todas as parcelas.

Autorização de Pagamento

As opções “qualquer valor” e “valor mínimo” ficam desabilitadas; apenas “Não autorizar pagamento de valor divergente” permanece disponível. Se uma dessas opções já estava selecionada quando o Pix é ativado, o sistema a substitui automaticamente por “Não autorizar”.

Espécie “BDP — Boleto de Proposta”

Não pode ser selecionada com o Pix ativado: ao tentar, o sistema desativa o toggle de Pix automaticamente e exibe um aviso ao usuário.

Formatos de impressão disponíveis (modal pós-emissão)

Somente ficam disponíveis os formatos A4, Carnê PIX com capa e Carnê PIX sem capa; os formatos tradicionais de Carnê (3 e 4 lâminas) deixam de ser oferecidos.

Fluxo pós-emissão

Ao concluir a emissão com Pix ativo, o usuário não vê o modal de escolha de formato de impressão — é redirecionado diretamente para a Listagem de Boletos, com a mensagem “Boleto emitido com sucesso. Aguardando geração do QR Code Pix.”

8.5. Referência Técnica de API (Pix)

Ação

Endpoint

Método

Consultar configuração de Pix da conta

/api/pix/config

GET

Ativar Pix para a conta

/api/pix/config

PUT

 

O campo fgIncluirQrCode é enviado no payload de cada parcela ao salvar os títulos, refletindo o estado do toggle de Pix no momento da emissão.

9. Finalização da Emissão

O botão “Emitir boleto” (rodapé da tela) valida todos os campos do formulário e da grade de parcelas antes de enviar a emissão. Havendo erro de validação em alguma parcela, um aviso é exibido acima da grade.

Mensagem de campos obrigatórios: “Preencha os campos obrigatórios para continuar”

9.1. Modal de Formato de Impressão

Exibido após a emissão bem-sucedida, exceto quando o Pix está ativo para a cobrança (ver seção 8.4). Permite escolher o formato de impressão do(s) boleto(s) recém-emitido(s).

Formato

Disponível com Pix ativo?

Formato A4

Sim

Formato Carnê (3 lâminas • COM capa)

Não

Formato Carnê (3 lâminas • SEM capa)

Não

Formato Carnê (4 lâminas • COM capa)

Não

Formato Carnê (4 lâminas • SEM capa)

Não

Carnê PIX com capa

Sim (exclusivo do modo Pix)

Carnê PIX sem capa

Sim (exclusivo do modo Pix)
  • Ações do modal:
  • Imprimir — realiza o download do PDF no formato selecionado e encerra o fluxo, retornando à Listagem de Boletos.
  • Emitir outro Boleto — fecha o modal e limpa o formulário para uma nova emissão, restaurando os valores padrão de Espécie, Aceite, Informações, Instruções, Dias para protesto/negativação e Autorização de Pagamento.

10. Referência Técnica de API (Emissão)

Ação

Endpoint

Método

Salvar títulos (emitir boletos)

/titulos

POST

Consultar espécies disponíveis

/especies

GET

Consultar parâmetros da conta

/parametros-conta

GET

Gerar PDF de um boleto

/titulos/pdf/{id}

GET

Imprimir boletos em lote

/titulos/impressao

POST

 

Mensagens de sucesso relacionadas à emissão:

Sucesso (parcelas geradas via modal): “Parcela(s) gerada(s) com sucesso”

Sucesso (emissão com Pix ativo): “Boleto emitido com sucesso. Aguardando geração do QR Code Pix.”

Erro genérico de emissão: “Ocorreu um erro. Tente novamente.”