Grupo de Pagadores

1. Visão Geral

A tela de Grupo de Pagadores permite organizar múltiplos pagadores em um mesmo grupo, para uso posterior na emissão de boletos direcionada a um conjunto de pagadores de uma só vez, em vez de selecionar um pagador individual a cada emissão.

Um grupo pode conter qualquer quantidade de pagadores ativos previamente cadastrados na plataforma, e um mesmo pagador pode pertencer a mais de um grupo simultaneamente.

2. Localização no Sistema

Caminho de navegação: Carteira → Pagadores → aba Grupo de Pagadores

A aba Grupo de Pagadores fica ao lado da aba Pagadores, dentro da mesma tela do módulo Carteira.

3. Estrutura da Tela

A listagem apresenta os grupos de pagadores já cadastrados, em formato de tabela, com as seguintes colunas:

Coluna	Descrição
Ações	Ícones de editar, excluir/gerenciar vínculo e vincular pagadores (ver seção 4)
Data de Registro	Data e hora de criação do grupo (formato dd/MM/aaaa HH:mm:ss)
Nome	Nome atribuído ao grupo
Prox. Incremental	Próximo número incremental utilizado pelo grupo em emissões futuras
Nr. Emissões	Quantidade de emissões de boletos já realizadas com este grupo

Quando não há nenhum grupo cadastrado (ou nenhum resultado para o filtro de busca aplicado), a tabela exibe a mensagem “Nenhum registro encontrado.”

4. Ícones de Ação na Listagem

Ícone	Ação	Condição de exibição
Editar (lápis)	Abre o modal de edição do grupo, com nome e pagadores vinculados carregados	Sempre exibido
Excluir (X circulado)	Remove definitivamente o grupo, mediante confirmação	Exibido apenas quando o grupo NÃO possui boletos emitidos (temBoletos = falso)
Vincular pagadores (usuário)	Abre o modal dedicado de vinculação/desvinculação de pagadores ao grupo	Sempre exibido; o tooltip do ícone mostra a quantidade atual de pagadores vinculados ao grupo

Assim como ocorre na aba Pagadores, um grupo que já possui boletos emitidos não pode ser excluído — essa é uma proteção para preservar o histórico de emissões associado ao grupo.

5. Ações Disponíveis na Barra Superior

Ação	Descrição
Pesquisar	Exibe um campo de busca por nome do grupo; busca aplicada automaticamente após pausa na digitação (debounce)
Adicionar (+)	Abre o modal de cadastro de um novo grupo de pagadores (ver seção 6)

6. Cadastro e Edição de Grupo de Pagadores

Ao clicar em Adicionar (+) ou no ícone de editar de um grupo existente, o sistema abre um único modal combinado, contendo simultaneamente o campo de nome do grupo e a tabela de seleção de pagadores a vincular — não há etapas separadas (stepper) quando o acesso é feito por esta aba.

6.1. Campos do Modal

Nome do grupo

Tipo: Texto
Obrigatoriedade: Sim
Comportamento: Nome de identificação do grupo, exibido na listagem.
Validação: Mínimo de 3 caracteres e máximo de 200 caracteres. Exibe mensagem de campo obrigatório quando vazio, mensagem de tamanho mínimo quando muito curto, e mensagem de nome duplicado quando já existe outro grupo com o mesmo nome (validação feita pelo backend no momento de salvar).

6.2. Seleção de Pagadores no Modal

Abaixo do campo de nome, o modal exibe uma barra de busca (por nome do pagador) e a tabela com todos os pagadores ativos cadastrados na plataforma, cada um com um ícone de ação para vincular ou desvincular do grupo em edição.

Coluna da tabela	Descrição
Ações	Ícone que alterna a seleção do pagador (vincular/desvincular) apenas localmente, dentro do formulário — a confirmação definitiva só ocorre ao salvar o modal
Código	Identificador do pagador
Nome	Nome do pagador
CPF/CNPJ	Documento do pagador

Também é possível cadastrar um novo pagador diretamente a partir deste modal, sem precisar fechá-lo: o botão “Cadastrar pagador” abre o formulário de cadastro de pagador (o mesmo utilizado na aba Pagadores); ao concluir o cadastro, o novo pagador é automaticamente adicionado à seleção do grupo em edição.

6.3. Salvamento

O botão de salvar do modal permanece desabilitado enquanto o nome do grupo não for válido ou enquanto nenhum pagador estiver selecionado — não é possível salvar um grupo sem nome ou sem ao menos um pagador vinculado.

Mensagem de sucesso (criação): “Grupo criado. Seleção realizada automaticamente.”

Mensagem de sucesso (edição): “Grupo de pagadores editado com sucesso”

Mensagem de erro (nome duplicado): “Já existe um grupo de pagadores com este nome (mensagem ilustrativa; o texto exato é retornado pelo backend)”

7. Modal Dedicado de Vinculação de Pagadores

Além do cadastro/edição, a listagem oferece um modal específico apenas para gerenciar quais pagadores estão vinculados a um grupo já existente, acessado pelo ícone de vincular (usuário) na tabela.

Este modal apresenta a lista completa de pagadores vinculados ao grupo, com busca por nome, e as seguintes ações:

Ação	Comportamento
Vincular/Desvincular individual	Ícone por linha que alterna o vínculo do pagador com o grupo imediatamente (chamada direta ao backend, sem necessidade de salvar o modal)
Vincular todos	Vincula de uma só vez todos os pagadores disponíveis ao grupo
Desvincular todos	Remove de uma só vez o vínculo de todos os pagadores do grupo
Cadastrar pagador	Abre o formulário de cadastro de um novo pagador sem sair do modal

O botão “Vincular todos”/“Desvincular todos” alterna de rótulo e ícone conforme o estado atual: quando todos os pagadores disponíveis já estão vinculados, o botão passa a oferecer a ação de desvincular todos, e vice-versa.

Mensagem de sucesso (vincular individual): “Pagador vinculado”

Mensagem de sucesso (desvincular individual): “Pagador desvinculado”

Mensagem de sucesso (vincular todos): “Todos os pagadores foram vinculados”

Mensagem de sucesso (desvincular todos): “Todos os pagadores foram desvinculados”

8. Exclusão de Grupo de Pagadores

Disponível apenas para grupos que ainda não possuem boletos emitidos. Ao clicar no ícone de exclusão, é exibido um modal de confirmação simples, solicitando a confirmação do nome do grupo a ser removido.

Mensagem de sucesso: “Grupo excluído com sucesso”

9. Uso do Grupo na Emissão de Boletos

Um grupo de pagadores cadastrado pode ser selecionado no campo “Grupo de Pagadores” da tela de Emissão de Boletos, como alternativa à seleção de um pagador individual. Ao selecionar um grupo, o campo de pagador individual é desabilitado automaticamente, e vice-versa.

Um grupo sem nenhum pagador vinculado não pode ser selecionado para emissão.

Mensagem de aviso (grupo sem pagadores): “O grupo selecionado não possui pagadores vinculados.”

10. Referência Técnica de API

Ação	Endpoint	Método
Listar grupos de pagadores (paginado, com busca)	/grupos-pagadores	GET
Cadastrar grupo de pagadores	/grupos-pagadores	POST
Editar grupo de pagadores	/grupos-pagadores/{id}	PUT
Excluir grupo de pagadores	/grupos-pagadores/{id}	DELETE
Listar pagadores de um grupo (vinculados e disponíveis)	/grupos-pagadores/{id}/pagadores	GET
Vincular/desvincular pagador(es) a um grupo	/grupos-pagadores/{id}/pagadores	POST
Vincular todos os pagadores a um grupo	/grupos-pagadores/{id}/pagadores/vincular-todos	POST
Desvincular todos os pagadores de um grupo	/grupos-pagadores/{id}/pagadores/desvincular-todos	POST
Consultar contagem de pagadores vinculados/total de um grupo	/grupos-pagadores/{id}/pagadores/contagem	GET

Código de retorno relevante na exclusão de grupo:

Código	Situação
200/204	Grupo excluído com sucesso
409	Nome do grupo duplicado (ao cadastrar/editar) ou exclusão bloqueada por existirem boletos emitidos com o grupo