Onboarding Pix no Boleto

1. Visão Geral

O Pix no Boleto (também chamado de BolePix) é uma funcionalidade que adiciona um QR Code Pix aos boletos emitidos, permitindo que o pagador realize o pagamento por escaneamento do código ou por Pix Copia e Cola, além da forma tradicional via código de barras/rede bancária.

“Onboarding do Pix” é o nome dado ao fluxo de habilitação dessa funcionalidade para uma conta: da liberação comercial (feita fora da plataforma, pelo gerente de relacionamento) até a efetiva ativação técnica pelo próprio usuário dentro do sistema, que é quando o Pix passa a valer para os boletos emitidos a partir daquele momento.

2. Estados Possíveis da Conta em Relação ao Pix

A situação de uma conta em relação ao Pix no Boleto é definida pela combinação de três informações, consultadas automaticamente pelo sistema:

Estado	Elegível	Habilitado	Ativado	O que o usuário vê
Não elegível	Não	—	—	Nenhuma informação, card ou opção de Pix em qualquer tela do sistema
Elegível, mas não habilitada	Sim	Não	Não	Nenhum card de onboarding é exibido; na tela de Emissão de Boletos, a seção de Pix aparece, mas o toggle permanece desabilitado com uma orientação para solicitar o credenciamento
Habilitada, pendente de ativação	Sim	Sim	Não	Card de onboarding exibido no Dashboard; modal de ativação também pode ser aberto automaticamente ao acessar a Emissão de Boletos
Habilitada e ativada	Sim	Sim	Sim	Toggle de Pix disponível e ativável livremente na Emissão de Boletos; nenhum card de onboarding é exibido

“Habilitada” significa que a conta já recebeu a liberação comercial para usar o Pix no Boleto (processo realizado fora da plataforma). “Ativada” significa que o usuário já concluiu o passo de ativação técnica dentro do sistema, descrito neste documento.

3. Card de Onboarding no Dashboard

Ao acessar o Dashboard, o sistema consulta automaticamente a configuração de Pix da conta. Caso a conta esteja elegível, habilitada e ainda não tenha sido ativada, um card de onboarding é exibido automaticamente, em formato de modal centralizado.

3.1. Conteúdo do Card

Título: “Pix agora disponível no boleto!”

Descrição: “Agora você pode adicionar QR Code Pix aos seus boletos e receber pagamentos de forma instantânea. Ative para começar a usar.”

O card apresenta um banner de imagem no topo e dois botões de ação:

Botão	Comportamento
Ver depois	Fecha o card sem ativar o Pix. A conta é marcada como “dispensada” apenas durante a sessão atual do navegador — o card volta a ser exibido normalmente em um novo acesso ao sistema.
Ativar	Fecha o card e abre, na sequência, o modal “Ativar pix no boleto” (detalhado na seção 4 deste documento).

3.2. Comportamento do “Ver depois”

Ao clicar em “Ver depois”, o sistema registra a conta como dispensada usando o armazenamento de sessão do navegador (sessionStorage). Isso significa que:

O card não volta a ser exibido enquanto a mesma aba/sessão do navegador permanecer aberta;
Ao fechar o navegador ou abrir uma nova sessão (ex.: nova aba anônima, outro navegador, ou após limpar os dados de navegação), o card volta a ser exibido normalmente, caso a conta continue habilitada e não ativada.

4. Emissão de Boletos como Ponto de Entrada do Onboarding

Além do card no Dashboard, o onboarding do Pix também pode ser disparado diretamente ao acessar as telas de Emissão de Boletos (tanto na Emissão Rápida quanto na Emissão Detalhada), de forma independente do card do Dashboard já ter sido visto ou dispensado.

Ao carregar a tela de emissão, o sistema também consulta a configuração de Pix da conta. Se a conta estiver habilitada, porém ainda não ativada, o modal de ativação (seção 5 deste documento) é aberto automaticamente, assim que a tela termina de carregar — sem exigir nenhuma ação prévia do usuário além de acessar a tela.

Esse comportamento se repete a cada novo acesso à tela de emissão, enquanto a conta permanecer no estado “habilitada, porém não ativada” — diferente do card do Dashboard, aqui não existe opção de “adiar”: o modal é sempre reaberto até que o usuário efetivamente conclua a ativação.

4.1. Seção de Pix na Tela de Emissão (contas elegíveis)

Independentemente do card ou do modal de onboarding, contas elegíveis (mesmo que ainda não habilitadas) visualizam uma seção dedicada de Pix na tela de emissão, com um toggle para ativar ou desativar o Pix apenas para aquela emissão específica:

Título da seção: “Pix no boleto”

Descrição (com Pix ativo na cobrança): “QR Code Pix ativado nos boletos”

Descrição (com Pix inativo na cobrança): “Ative o Pix para incluir QR Code nos boletos”

Se a conta ainda não estiver habilitada (liberação comercial pendente), o toggle aparece desabilitado, e a seguinte orientação é exibida:

Orientação (conta ainda não habilitada): “Para habilitar essa função, solicite o credenciamento diretamente com o seu gerente de relacionamento Cresol.”

Se a conta já estiver habilitada, porém ainda não tiver sido ativada pelo usuário, a orientação exibida é outra, reforçando que a ativação já está disponível:

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

5. Modal de Ativação do Pix (“Ativar pix no boleto”)

Este é o modal central do fluxo de onboarding — é nele que a ativação técnica do Pix efetivamente acontece. Ele pode ser aberto de duas formas, já descritas nas seções anteriores: pelo botão “Ativar” do card do Dashboard, ou automaticamente ao acessar a tela de Emissão de Boletos com a conta habilitada e não ativada.

O modal é aberto de forma bloqueante: não é possível fechá-lo clicando fora dele nem pressionando a tecla Esc — a única forma de sair é usando um dos botões disponíveis.

Após uma ativação concluída com sucesso, a conta passa para o estado “habilitada e ativada”: o card de onboarding do Dashboard não é mais exibido, o modal de ativação não é mais aberto automaticamente na Emissão de Boletos, e o toggle de Pix na tela de emissão passa a ficar disponível para uso livre em cada nova cobrança.