====== [ER_005] Requisitos - Consulta de Pendências e Geração de Boletos ======

**Descrição**: Funcionalidade que permite ao usuário consultar pendências de multas vinculadas a um CPF ou CNPJ, visualizar as parcelas em aberto de cada pendência e gerar o boleto bancário correspondente, com redirecionamento ao site do Banco do Brasil para impressão.

**Menu / Local de acesso**: Portal TCE-GO | Serviços | Consulta de Pendências e Geração de Boletos

===== Atores =====

^Nível^Perfil^Autenticação^Abrangência|
|**PÚBLICO**|Cidadão, Jurisdicionado, Partes Processuais, Instituições|Não obrigatória|Consulta de pendências de multa vinculadas a CPF ou CNPJ e geração de boleto bancário via integração com o Banco do Brasil.|

===== Telas =====

==== Tela 01 - Consulta de Pendências ====

Tela responsável por permitir a busca de pendências a partir do documento do interessado e, opcionalmente, de filtros avançados.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|CPF/CNPJ|Campo Texto com máscara|Sim|CPF: XXX.XXX.XXX-XX \\ CNPJ: XX.XXX.XXX/XXXX-XX|Vazio|Máscara aplicada automaticamente conforme o comprimento digitado. O documento informado deve ser válido (RN01).|
|Filtros Avançados (Opcional)|Seção expansível|Não|–|Recolhido|Exibido ao clicar em "Filtros Avançados (Opcional)". Permite informar Nº Processo, Nº Ofício e Ano Ofício em conjunto (RN02).|
|Nº Processo|Campo Texto (somente números)|Não|Numérico, 15 dígitos|Vazio|Exibido apenas dentro dos filtros avançados. Deve conter exatamente 15 dígitos (RN03).|
|Nº Ofício|Campo Texto (somente números)|Não|Numérico|Vazio|Exibido apenas dentro dos filtros avançados. Informado em conjunto com Ano Ofício (RN02).|
|Ano Ofício|Campo Texto (somente números)|Não|Numérico, 4 dígitos|Vazio|Exibido apenas dentro dos filtros avançados. Informado em conjunto com Nº Ofício (RN02).|
|Verificação de Segurança (Captcha)|Componente de Segurança|Sim|–|Vazio|Obrigatório para execução da busca (RN04). Pode ser atualizado pelo usuário.|
|Botão "Buscar Pendências"|Botão|Sim|–|–|Executa a consulta de pendências conforme os critérios informados.|

==== Tela 02 - Pendências Encontradas ====

Tela responsável por exibir a lista de pendências identificadas para o documento informado.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Cabeçalho – Documento consultado|Texto|Sim|CPF ou CNPJ formatado|–|Exibe o documento utilizado na consulta.|
|Mensagem informativa|Texto|Sim|–|–|Exibe a quantidade de pendências em aberto encontradas e instrução para o usuário clicar na pendência desejada.|
|Número do Processo|Link clicável|Sim|15 dígitos|–|Redireciona o usuário para o **[[pres:gerti:gestao_de_ativos:portal:er_002#fluxo_02_-_visualizar_detalhamento_do_processo|ER_002: Fluxo 02 – Visualizar Detalhamento do Processo]]** em nova aba (RN05).|
|Número do Ofício|Texto|Sim|Número do ofício|–|Exibido no card da pendência.|
|Situação|Badge|Sim|Em Aberto; Vencido|–|Indica a situação atual da pendência (RN06).|
|Valor Total|Moeda (R$)|Sim|Valor monetário|–|Valor total da multa vinculada ao ofício.|
|Vencimento|Data (dd/MM/yyyy)|Sim|Data válida|–|Data de vencimento da multa.|
|Parcelas|Numérico|Sim|Quantidade de parcelas|–|Quantidade total de parcelas do ofício.|
|Link "Clique para ver detalhes e gerar boleto"|Link|Sim|–|–|Aciona o **[[#fluxo_03_-_detalhar_pendencia|Fluxo 03]]**.|
|Link "Nova Consulta"|Link|Sim|–|–|Retorna à Tela 01 e limpa os resultados.|

==== Tela 03 - Detalhes da Pendência ====

Tela responsável por exibir as parcelas de uma pendência selecionada e permitir a geração do boleto.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Situação da Pendência|Badge|Sim|Em Aberto; Vencido|–|Situação geral da pendência (RN06).|
|Número do Processo|Link clicável|Sim|15 dígitos|–|Redireciona o usuário para o **[[pres:gerti:gestao_de_ativos:portal:er_002#fluxo_02_-_visualizar_detalhamento_do_processo|ER_002: Fluxo 02 – Visualizar Detalhamento do Processo]]** em nova aba (RN05).|
|Número do Ofício / Ano|Texto|Sim|Nº/Ano do ofício|–|Ex.: 00123/2024.|
|Valor Total|Moeda (R$)|Sim|Valor monetário|–|Valor total da multa.|
|Vencimento Geral|Data (dd/MM/yyyy)|Sim|Data válida|–|Data de vencimento geral da pendência.|
|Lista de Parcelas|Seleção (Radio)|Sim|Parcelas disponíveis|–|Seleção única. Cada parcela exibe: número, valor, atualização monetária, vencimento e situação (RN07).|
|Situação da Parcela|Badge|Sim|Em Aberto; Vencido|–|Indica a situação individual de cada parcela (RN06).|
|Valor da Parcela (calculado)|Moeda (R$)|Sim|Valor monetário|–|Exibido após seleção de parcela. Calculado como: Valor da Parcela + Atualização Monetária (RN08).|
|Botão "Gerar Boleto"|Botão|Sim|–|–|Aciona o **[[#fluxo_04_-_gerar_boleto|Fluxo 04]]** para a parcela selecionada.|
|Link "Voltar"|Link|Sim|–|–|Retorna à Tela 02.|

==== Tela 04 - Boleto Gerado com Sucesso ====

Tela responsável por confirmar a geração do boleto e exibir as informações para pagamento.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Mensagem de Confirmação|Texto|Sim|"Boleto Gerado com Sucesso!"|–|Confirma que o boleto foi registrado no sistema do Banco do Brasil.|
|Beneficiário|Texto|Sim|Tribunal de Contas do Estado|–|CNPJ do TCE-GO.|
|Pagador (Interessado)|Texto|Sim|Nome do interessado|–|CPF/CNPJ do interessado.|
|Número do Processo|Texto|Sim|15 dígitos|–|Processo vinculado ao boleto gerado.|
|Vencimento|Data (dd/MM/yyyy)|Sim|Data válida|–|Data de vencimento do boleto gerado (RN09).|
|Valor|Moeda (R$)|Sim|Valor monetário|–|Valor total do boleto (Parcela + Atualização Monetária).|
|Linha Digitável|Texto com botão "Copiar"|Sim|Código numérico|–|Código da linha digitável retornado pelo Banco do Brasil (RN10).|
|Botão "Acessar Banco do Brasil"|Botão com link externo|Sim|–|–|Redireciona o usuário ao site do Banco do Brasil para visualização e impressão do boleto (RN11).|
|Instruções para Pagamento|Lista informativa|Sim|–|–|Exibe as instruções fixas de pagamento (RN12).|

===== Fluxos =====

==== Fluxo 01 - Consultar Pendências ====

^Passo^Ação^Regra^Tela|
|01|O usuário acessa a funcionalidade "Consulta de Pendências e Geração de Boletos".| |Tela 01|
|03|O usuário informa o CPF/CNPJ obrigatoriamente.|RN01|Tela 01|
|03.1|Caso o CPF/CNPJ seja inválido, o sistema apresenta a mensagem de erro correspondente e interrompe a execução.|RN01| |
|04|Opcionalmente, o usuário expande a seção "Filtros Avançados" e informa Nº Processo, Nº Ofício e Ano Ofício.|RN02, RN03|Tela 01|
|05|O usuário informa o Captcha e aciona o botão "Buscar Pendências".|RN04| |
|07|O sistema valida o Captcha informado.|RN04| |
|07.1|Caso o Captcha seja inválido, o sistema apresenta a mensagem de erro e interrompe a execução.|RN04| |
|09|O sistema consulta as pendências com base nos critérios informados.|RN13| |
|09.1|Caso filtros avançados tenham sido informados, o sistema consulta a pendência específica correspondente ao Nº Processo, Nº Ofício e Ano Ofício.|RN02| |
|09.2|Caso filtros avançados não tenham sido informados, o sistema retorna todas as pendências em aberto vinculadas ao CPF/CNPJ informado.|RN13| |
|10|O sistema verifica se existem pendências com parcela não cancelada e com Data de Notificação preenchida.|RN14| |
|10.1|Caso não existam pendências, o sistema executa o **[[#fluxo_02_-_pendencias_nao_encontradas|Fluxo 02]]**.| | |
|11|O sistema exibe a Tela 02 com a lista de pendências encontradas.|RN06|Tela 02|

==== Fluxo 02 - Pendências Não Encontradas ====

^Passo^Ação^Regra^Tela|
|01|O sistema não localiza pendências para os critérios informados.|RN13, RN14|Tela 01|
|02|O sistema apresenta a mensagem: "Nenhuma pendência encontrada."|RN13| |
|03|O sistema permanece na Tela 01 permitindo nova tentativa.| |Tela 01|

==== Fluxo 03 - Detalhar Pendência ====

^Passo^Ação^Regra^Tela|
|01|O usuário clica em "Clique para ver detalhes e gerar boleto" em uma pendência da lista.| |Tela 02|
|02|O sistema consulta as parcelas do ofício selecionado, ordenadas por data de vencimento.|RN14| |
|03|O sistema exibe a Tela 03 com os dados da pendência e a lista de parcelas disponíveis.|RN07|Tela 03|
|04|O usuário seleciona uma parcela.|RN07|Tela 03|
|05|O sistema calcula e exibe o valor total da parcela selecionada: Valor da Parcela + Atualização Monetária.|RN08|Tela 03|
|06|O usuário aciona o botão "Gerar Boleto".| | |
|07|O sistema executa o **[[#fluxo_04_-_gerar_boleto|Fluxo 04]]**.| | |

==== Fluxo 04 - Gerar Boleto ====

^Passo^Ação^Regra^Tela|
|01|O sistema recebe a solicitação de geração de boleto para a parcela selecionada.| |Tela 03|
|02|O sistema consulta os dados da boleta correspondente via ''TCE.Compartilhado → ServicoDeOficioWeb → GeraBoleta'' → ''RepositorioDeOficioWeb → ConsultaBoleta'' → view ''VWEB_BOLETA''.| | |
|03|O sistema verifica a data de vencimento da parcela.|RN09| |
|03.1|Caso a data de vencimento esteja expirada e o valor não tenha sido alterado no mês corrente, o sistema prorroga a data de vencimento para 2 dias a partir da data atual e incrementa a versão do boleto.|RN09| |
|03.2|Caso a data de vencimento esteja expirada e o valor tenha sido alterado, o sistema prorroga somente a data de vencimento para 2 dias a partir da data atual.|RN09| |
|04|O sistema verifica se já existe boleto gerado anteriormente para esta parcela via integração com a API do Banco do Brasil.|RN17| |
|04.1|Caso já exista boleto gerado e o valor não tenha sido alterado, o sistema executa o **[[#fluxo_05_-_gerar_segunda_via_do_boleto|Fluxo 05]]**.|RN17| |
|04.2|Caso não exista boleto gerado anteriormente, o sistema realiza a geração do boleto junto à API do Banco do Brasil.|RN17| |
|05|O sistema envia os dados do boleto à API do Banco do Brasil (''POST https://api.bb.com.br/cobrancas/v2/boletos'').|RN17| |
|06|O sistema salva a URL da imagem do boleto retornada pelo Banco do Brasil na tabela ''PRO_URLIMAGEMBOLETO'' (campos: PROOFIC_ID, NUMERO_TITULO_CLIENTE, URL_IMAGEM_BOLETO).|RN18| |
|07|O sistema registra o envio de e-mail de monitoramento interno com os dados do boleto gerado.|RN19| |
|08|O sistema exibe a Tela 04 com as informações do boleto gerado: Beneficiário, Pagador, Processo, Vencimento, Valor e Linha Digitável.|RN10|Tela 04|
|08.1|Caso a API do Banco do Brasil retorne erro na geração, o sistema apresenta a mensagem: "Problema ao acessar endereço [URL] hospedado nos servidores do Banco do Brasil. Tente novamente mais tarde. Se o problema persistir entre em contato com o suporte do TCE-GO." e redireciona para a Tela 01.| | |

==== Fluxo 05 - Gerar Segunda Via do Boleto ====

^Passo^Ação^Regra^Tela|
|01|O sistema identifica que já existe boleto gerado anteriormente para a parcela selecionada.|RN17|Tela 03|
|02|O sistema verifica se a data de vencimento foi prorrogada.|RN09| |
|02.1|Caso a data tenha sido prorrogada, o sistema aciona a alteração do boleto junto à API do Banco do Brasil (''PATCH https://api.bb.com.br/cobrancas/v2/boletos/:id''), atualizando a data de vencimento.|RN09| |
|02.1.1|Caso a alteração falhe, o sistema apresenta a mensagem de erro retornada pela API e redireciona para a Tela 01.| | |
|03|O sistema aciona o detalhamento do boleto na API do Banco do Brasil (''GET https://api.bb.com.br/cobrancas/v2/boletos/:id'') para obter o código da linha digitável.|RN17| |
|03.1|O sistema monta a URL de redirecionamento e o código da linha digitável a partir dos dados retornados pelo detalhamento.|RN17| |
|04|O sistema registra o envio de e-mail de monitoramento interno com os dados do boleto.|RN19| |
|05|O sistema exibe a Tela 04 com as informações da segunda via do boleto.|RN10|Tela 04|

===== RN – Regras de Negócio =====

^ID^Descrição^
|RN01|**Validação de CPF e CNPJ** – O CPF/CNPJ informado é obrigatório e deve ser válido. A máscara é aplicada automaticamente conforme o comprimento digitado (CPF: XXX.XXX.XXX-XX / CNPJ: XX.XXX.XXX/XXXX-XX). A validação ocorre conforme o comprimento: \\ – Até 11 dígitos: aplica validação de CPF → mensagem de erro: "CPF informado é inválido." \\ – Acima de 11 dígitos: aplica validação de CNPJ → mensagem de erro: "CNPJ informado é inválido." \\ Validação executada em: ''TCE.WebSites → BoletoController → ValidaCpfOuCnpj''.|
|RN02|**Filtros Avançados Opcionais** – O usuário pode informar, opcionalmente, Nº Processo, Nº Ofício e Ano Ofício para obter uma pendência específica. Quando não informados, o sistema retorna todas as pendências em aberto vinculadas ao CPF/CNPJ.|
|RN03|**Formato do Número do Processo** – O Nº Processo deve conter exatamente 15 dígitos numéricos. Exemplo: 202500047004104.|
|RN04|**Captcha Obrigatório** – A busca de pendências somente poderá ser executada após a validação do Captcha de segurança. O campo é obrigatório.|
|RN05|**Link para Detalhamento do Processo** – O número do processo exibido nas Telas 02 e 03 é um link clicável que abre em nova aba o **[[pres:gerti:gestao_de_ativos:portal:er_002#fluxo_02_-_visualizar_detalhamento_do_processo|ER_002: Fluxo 02 – Visualizar Detalhamento do Processo]]**.|
|RN06|**Situação da Pendência e das Parcelas** – A situação é exibida como badge e pode assumir os valores: "Em Aberto" ou "Vencido". Aplica-se tanto ao nível da pendência (Tela 02) quanto ao nível de cada parcela (Tela 03).|
|RN07|**Seleção Única de Parcela** – A seleção de parcela para geração de boleto é exclusiva (radio button). Somente uma parcela pode ser selecionada por vez. A consulta e exibição das parcelas seguem as regras definidas em RN14.|
|RN08|**Cálculo do Valor Total da Parcela** – Ao selecionar uma parcela, o sistema calcula e exibe o valor total: Valor da Parcela + Atualização Monetária. Este valor é o que será cobrado no boleto gerado.|
|RN09|**Prorrogação Automática de Vencimento** – Quando a data de vencimento da parcela estiver expirada na data da geração do boleto, o sistema prorroga automaticamente a data de vencimento para 2 (dois) dias a partir da data atual. \\ – Se o valor da parcela não foi alterado no mês corrente (ValorParcelaAntiga == Valor), o sistema também incrementa a versão do boleto (NUMR_VERSBOLETA_N + 1) na tabela ''PRO_PARCMULTAS'' e registra a nova data de vencimento no campo ''DATA_VENCNOVA_D''. \\ – Se o valor da parcela foi alterado, o sistema atualiza apenas a data de vencimento no boleto existente via API do Banco do Brasil.|
|RN10|**Linha Digitável** – O código da linha digitável é obtido via API de Detalhamento do Banco do Brasil (''GET https://api.bb.com.br/cobrancas/v2/boletos/:id''). É exibido na Tela 04 com botão de cópia para área de transferência.|
|RN11|**Redirecionamento para Impressão** – A imagem do boleto não é disponibilizada diretamente pela integração. O sistema exibe um botão "Acessar Banco do Brasil" que redireciona o usuário ao site do Banco do Brasil para visualização e impressão do boleto.|
|RN12|**Instruções para Pagamento** – As seguintes instruções são exibidas fixamente na Tela 04: \\ – "Este boleto pode ser pago até a data de vencimento, após o vencimento, o boleto não pode ser pago." \\ – "O pagamento pode ser efetuado via internet banking em qualquer banco ou casas lotéricas." \\ – "Guarde o comprovante de pagamento."|
|RN13|**Consulta de Pendências** – A consulta de pendências é realizada via ''TCE.Compartilhado → ServicoDeOficioWeb → ConsulteSeExisteOficio'' → ''RepositorioDeOficioWeb → ConsulteSeExisteOficio'', que verifica na base de dados o ofício correspondente ao CPF/CNPJ e, quando informados, ao Nº Processo, Nº Ofício e Ano Ofício. Ofícios com situação "CANCELADO" não são retornados.|
|RN14|**Consulta de Parcelas** – A consulta de parcelas é realizada via ''TCE.Compartilhado → ServicoDeOficioWeb → ConsulteParcelas'' → ''RepositorioDeOficioWeb → ConsulteParcelas''. As parcelas são exibidas ordenadas por data de vencimento em ordem crescente. Parcelas canceladas não devem ser retornadas. A exibição é paginada com 5 (cinco) parcelas por vez (RN20).|
|RN17|**Integração com API de Cobrança do Banco do Brasil** – A geração e o gerenciamento de boletos utilizam a API de Cobrança do Banco do Brasil (v2), ativa a partir de 01/01/2026, substituindo a integração MPAG encerrada em 31/12/2025. \\ – Geração: ''POST https://api.bb.com.br/cobrancas/v2/boletos'' \\ – Alteração de vencimento: ''PATCH https://api.bb.com.br/cobrancas/v2/boletos/:id'' \\ – Detalhamento: ''GET https://api.bb.com.br/cobrancas/v2/boletos/:id'' \\ A autenticação é realizada via OAuth 2.0 com escopo de cobrança, utilizando ''clientId'' e ''clientSecret'' configurados em ''ApiBancoBrasilHelper''. A comunicação exige TLS 1.2.|
|RN18|**Persistência da URL do Boleto** – Após geração bem-sucedida do boleto, o sistema salva a URL da imagem retornada pelo Banco do Brasil na tabela Oracle ''PRO_URLIMAGEMBOLETO'' (campos: PROOFIC_ID, NUMERO_TITULO_CLIENTE, URL_IMAGEM_BOLETO). Esta URL é consultada nas gerações de segunda via antes de acionar novamente a API do Banco do Brasil.|
|RN19|**Monitoramento por E-mail** – A cada geração ou segunda via de boleto, o sistema envia automaticamente um e-mail de monitoramento interno para a lista de destinatários configurada em ''ApiBancoBrasilHelper'', a partir do remetente ''informatica@tce.go.gov.br'', com os dados do boleto gerado: data de vencimento, valor, nosso número, nome do pagador, CPF/CNPJ, Id do Ofício e código do processo.|
|RN20|**Paginação de Parcelas** – A lista de parcelas exibida na Tela 03 é paginada com 5 (cinco) parcelas por página.|