Diferenças

Aqui você vê as diferenças entre duas revisões dessa página.

--- pres:gerti:gestao_de_ativos:portal:er_005 [12/09/2026 18:16] – pramorim
+++ pres:gerti:gestao_de_ativos:portal:er_005 [14/09/2026 20:55] (atual) – pramorim
@@ Linha 4: / Linha 4: @@
 **Menu / Local de acesso**: Portal TCE-GO | Serviços | Consulta de Pendências e Geração de Boletos
+**Documento relacionado**: [[pres:gerti:gestao_de_ativos:integracao-bb| Integração com o Banco do Brasil — Emissão de Boletos: guia de uso e testes]]
 ===== Problema, Escopo e Fora de Escopo =====
@@ Linha 141: / Linha 143: @@
 |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|O sistema verifica a data de vencimento da parcela e, se houver, o novo vencimento de boleto emitido anteriormente.|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.1|Caso o vencimento esteja expirado e não haja novo vencimento vigente, o sistema emite novo título: incrementa a versão e o número do título, define o vencimento para 2 dias a partir da data atual e utiliza o valor atualizado (parcela + atualização monetária até a data atual + tarifa bancária).|RN08, RN09, RN22| |
-|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| |
+|03.2|Caso o vencimento original esteja expirado, mas o novo vencimento do título emitido anteriormente ainda esteja vigente, o sistema mantém esse título, sem emitir outro.|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|O sistema verifica se já existe boleto gerado para o número do título 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.1|Caso já exista boleto gerado para o número do título 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| |
@@ Linha 156: / Linha 158: @@
 ^Passo^Ação^Regra^Tela|
-|01|O sistema identifica que já existe boleto gerado anteriormente para a parcela selecionada.|RN17|Tela 03|
+|01|O sistema identifica que já existe boleto gerado para o número do título, dentro do vencimento original ou do novo vencimento vigente. O boleto existente não é alterado no Banco do Brasil.|RN09, RN17|Tela 03|
-|02|O sistema verifica se a data de vencimento foi prorrogada.|RN09| |
+|02|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.|RN10| |
-|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. A alteração é aceita pelo banco a partir de 30 minutos após a geração do boleto.|RN09, RN17| |
+|02.1|O sistema utiliza como destino do botão de impressão o link de segunda via persistido ou, na falta dele, monta a URL de redirecionamento a partir da linha digitável e do número de inscrição do pagador.|RN11, RN18| |
-|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 registra o envio de e-mail de monitoramento interno com os dados do boleto.|RN19| |
-|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 e a data de vencimento vigente.|RN10| |
+|04|O sistema exibe a Tela 04 com as informações da segunda via do boleto.|RN10|Tela 04|
-|03.1|Caso o vencimento tenha sido prorrogado e a data de vencimento devolvida pelo detalhamento não coincida com a nova data, o sistema repete o detalhamento após 30 segundos.|RN10| |
-|03.2|O sistema utiliza como destino do botão de impressão o link de segunda via persistido ou, na falta dele, monta a URL de redirecionamento a partir da linha digitável e do número de inscrição do pagador.|RN11, RN18| |
-|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 =====
@@ Linha 178: / Linha 176: @@
 |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 + Tarifa Bancária (RN21). Este valor é o que será cobrado no boleto gerado e é replicado na Tela 04. A tela indica separadamente o montante da tarifa incluída.|
+|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 + Tarifa Bancária (RN21). A atualização monetária (''VALR_CORRECAO'', na view ''VWEB_PARCMULTAS'') é calculada pela função Oracle ''fweb_correcao_monet'', que aplica o cálculo do GCAR (''PCAR_CALCULO'') ao valor da parcela, do vencimento original até a data atual, somente para parcela vencida; nas demais, é zero. A atualização soma-se ao valor nominal do boleto enviado ao Banco do Brasil (''valorOriginal'', lido de ''VALOR_BOLETA''), e a tarifa é somada à parte. Ex.: parcela R$ 100,00 + atualização R$ 0,15 + tarifa R$ 1,87 = R$ 102,02. Este valor é o que será cobrado no boleto gerado e é replicado na Tela 04. A tela indica separadamente o montante da tarifa incluída.|
-|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.|
+|RN09|**Boleto de Parcela Vencida** – Quando o vencimento da parcela — ou o novo vencimento de boleto emitido anteriormente (''DATA_VENCNOVA_D'') — estiver expirado na data da geração, o sistema emite **novo título**: incrementa a versão do boleto (''NUMR_VERSBOLETA_N'' + 1) e o número do título (RN22), grava em ''DATA_VENCNOVA_D'', na tabela ''PRO_PARCMULTAS'', o novo vencimento — 2 (dois) dias a partir da data atual — e registra o boleto com o valor atualizado (RN08). \\ – Enquanto esse novo vencimento estiver vigente, nova solicitação para a mesma parcela devolve a segunda via do título dessa versão (Fluxo 05). \\ – Também é emitido novo título quando o valor da boleta mudou desde a última emissão (''VALOR_PARCELA_ANTIGO'' ≠ ''VALOR_BOLETA''). \\ – O título anterior **não é alterado nem baixado** no Banco do Brasil e permanece registrado no convênio, sem efeito de cobrança ao pagador: os boletos do TCE-GO não são enviados a protesto nem recebidos após o vencimento (RN12). Se o convênio tarifar a entrada do boleto, cada novo título não pago é custo do Tribunal. Comportamento **herdado do legado** e mantido na migração para a API; o tratamento do título anterior está descrito em **[[#melhorias_previstas|Melhorias Previstas — Melhoria 01]]**.|
-|RN10|**Linha Digitável** – Exibida na Tela 04 com botão de cópia para a área de transferência. Na geração, é obtida da própria resposta do registro do boleto (''POST https://api.bb.com.br/cobrancas/v2/boletos'', campo ''linhaDigitavel''). Na segunda via, é obtida pelo detalhamento do boleto (''GET https://api.bb.com.br/cobrancas/v2/boletos/:id'', campo ''codigoLinhaDigitavel''). Quando o vencimento tiver sido prorrogado (RN09), a linha digitável só é exibida se a data de vencimento devolvida pelo detalhamento (''dataVencimentoTituloCobranca'') coincidir com a nova data; caso contrário, o detalhamento é repetido após 30 segundos, prazo em que o Banco do Brasil devolve a mesma resposta para consultas repetidas ao mesmo boleto.|
+|RN10|**Linha Digitável** – Exibida na Tela 04 com botão de cópia para a área de transferência. Na geração, é obtida da própria resposta do registro do boleto (''POST https://api.bb.com.br/cobrancas/v2/boletos'', campo ''linhaDigitavel''). Na segunda via, é obtida pelo detalhamento do boleto (''GET https://api.bb.com.br/cobrancas/v2/boletos/:id'', campo ''codigoLinhaDigitavel''). Como o boleto existente nunca tem o vencimento alterado (RN09), a linha digitável da segunda via é a mesma devolvida na geração do título.|
 |RN11|**Redirecionamento para Impressão** – A imagem do boleto não é disponibilizada pela integração: a API de Cobrança devolve, no campo ''urlImagemBoleto'', o link de emissão da segunda via no site do Banco do Brasil. A Tela 04 apresenta o botão "Imprimir no site Banco do Brasil", que encaminha o usuário a esse link, persistido conforme RN18. Na falta de link persistido, o encaminhamento é para ''https://boleto.apps.bb.com.br/segunda-via'', com a linha digitável e o número de inscrição do pagador na URL.|
 |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 v2, ativa desde 01/01/2026, em substituição à integração MPAG encerrada em 31/12/2025. Geração: ''POST /cobrancas/v2/boletos''; alteração de vencimento: ''PATCH /cobrancas/v2/boletos/:id''; detalhamento: ''GET /cobrancas/v2/boletos/:id''. Autenticação por OAuth 2.0 com escopo de cobrança, usando ''clientId'' e ''clientSecret'' configurados em ''ApiBancoBrasilHelper''. A comunicação exige TLS 1.2. A existência de boleto anterior é verificada pelo detalhamento: retorno de sucesso indica boleto existente; o código de "número do título não encontrado" indica ausência. A alteração só é aceita pelo banco a partir de 30 minutos após a geração do boleto, admite uma alteração por chamada e não devolve a linha digitável (RN10). O número de inscrição do pagador é enviado como texto, conforme o contrato vigente da API (''OpenAPI_BB_Cobranças_v2.json'', versão 3.2.2).|
+|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 v2, ativa desde 01/01/2026, em substituição à integração MPAG encerrada em 31/12/2025. Geração: ''POST /cobrancas/v2/boletos''; detalhamento: ''GET /cobrancas/v2/boletos/:id''. Autenticação por OAuth 2.0 com escopo de cobrança, usando ''clientId'' e ''clientSecret'' configurados em ''ApiBancoBrasilHelper''. A comunicação exige TLS 1.2. A existência de boleto anterior é verificada pelo detalhamento: retorno de sucesso indica boleto existente; o código de "número do título não encontrado" indica ausência. A alteração de boleto (''PATCH /cobrancas/v2/boletos/:id'') **não é utilizada** pela funcionalidade (RN09); pela API, só é aceita a partir de 30 minutos após a geração, admite uma alteração por chamada e não devolve a linha digitável. O número de inscrição do pagador é enviado como texto, conforme o contrato vigente da API (''OpenAPI_BB_Cobranças_v2.json'', versão 3.2.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.|
 |RN21|**Mensagem e Tarifa do Boleto** – O boleto é emitido com a mensagem: "Multa pertinente ao processo [nº]. Após prazo definido pelo TCE-GO o valor será corrigido pelo IPCA Acumulado. Tarifa de cobrança bancária de R$ [valor]." A tarifa vem de ''VALR_TARIBANCARIA_N'' e compõe o valor da boleta. O título é emitido como duplicata de serviço, com aceite "A" e sem permissão de recebimento parcial.|
-|RN22|**Número do Título do Cliente** – Identificador do boleto junto ao Banco do Brasil, formado por "000" + número do convênio com 7 dígitos + 10 dígitos finais do número de controle interno do TCE-GO (''NUMR_PEDIDO'', na view ''VWEB_BOLETA''). É a chave usada para detalhamento, alteração e recuperação da URL da imagem.|
+|RN22|**Número do Título do Cliente** – Identificador do boleto junto ao Banco do Brasil, formado por "000" + número do convênio com 7 dígitos + 10 dígitos finais do número de controle interno do TCE-GO (''NUMR_PEDIDO'', na view ''VWEB_BOLETA''). É a chave usada para detalhamento e recuperação da URL da imagem. Na emissão de novo título (RN09), os 2 (dois) últimos dígitos do número de controle são incrementados em 1.|
+===== Melhorias Previstas =====
+==== Melhoria 01 - Tratar o boleto anterior na geração de boleto de parcela vencida ====
+**Comportamento atual (herdado do legado)**: quando o vencimento da parcela — ou o novo vencimento de boleto emitido anteriormente — está expirado, o sistema emite um **novo título** no Banco do Brasil, com vencimento em 2 dias a partir da data atual e valor atualizado (RN08, RN09). O título anterior **não é alterado nem baixado** e permanece registrado no convênio do Tribunal.
+**Origem**: comportamento do site legado anterior à API de Cobrança v2. Na migração para a API ([[https://projetos.tce.go.gov.br/issues/35881|#35881]]), decidiu-se mantê-lo: a alteração do título existente enfrentou resistência técnica, não estava claro se a data de vencimento e o valor nominal do boleto podiam ser alterados pela API — a especificação vigente confirma que ambos são alteráveis —, e o escopo da demanda era apenas migrar a integração.
+**Impacto atual**: sem efeito de cobrança ao pagador — os boletos do TCE-GO não são enviados a protesto nem recebidos após o vencimento (RN12). Cada nova emissão, porém, deixa um título anterior em aberto no convênio.
+**Custo a confirmar**: a tarifa repassada ao pagador (RN21) só é recuperada quando o boleto é pago. Se o contrato do convênio tarifar a entrada (registro) do boleto, cada título emitido e não pago é custo do Tribunal — e, no comportamento atual, uma mesma parcela vencida pode gerar vários títulos.
+**Melhoria proposta** — uma das alternativas:
+  * **alterar o título existente** pela API (''PATCH /cobrancas/v2/boletos/:id''), atualizando a data de vencimento e, quando a atualização monetária mudar, o valor nominal; ou
+  * **baixar o título anterior** (''POST /cobrancas/v2/boletos/:id/baixar'') ao emitir o novo.
+**Pontos a confirmar antes da implementação**:
+  * **alterabilidade — confirmada na especificação da API** (''OpenAPI_BB_Cobranças_v2.json'', versão 3.2.2): o ''PATCH'' altera a data de vencimento (''"indicadorNovaDataVencimento": "S"'' com ''"alteracaoData": {"novaDataVencimento": "dd.mm.aaaa"}'') e o valor nominal (''"indicadorNovoValorNominal": "S"'' com ''"alteracaoValor": {"novoValorNominal": 0.00}''); os demais indicadores obrigatórios seguem com ''"N"''. Resta confirmar em homologação se as duas alterações podem ir na mesma chamada — a documentação do banco admite uma alteração por chamada, aceita só a partir de 30 minutos após a geração;
+  * **ajustar o contrato de alteração do código existente**: o ''BoletoAlterar'' do ''TCE.Compartilhado'' e do site legado já tem ''indicadorNovoValorNominal'' e ''novoValorNominal'', mas serializa ''novoValorNominal'' na raiz do corpo, e não dentro de ''alteracaoValor'' como exige a especificação — reaproveitado sem ajuste, o banco não recebe o novo valor;
+  * o desvio de alteração de vencimento já existe no código do site legado e do Catálogo de Serviços, mas está inalcançável desde a correção de 2025-12-22 (commit ''cf619de'', erro 500 relatado em [[https://projetos.tce.go.gov.br/issues/38054|#38054]]) — deve ser corrigido ou removido;
+  * quais eventos o convênio tarifa (entrada, liquidação, baixa, alteração) — define o custo atual dos títulos não pagos e se alterar o título existente, que pode ter tarifa própria, custa menos que emitir novo; consultar o contrato ou os movimentos do convênio pela API (''POST /convenios/{id}/listar-retorno-movimento'', campo ''valorTarifa'');
+  * priorização com a área de arrecadação.
+**Situação**: não iniciada. Não bloqueia a entrega do RF-005.
 ----
-//Gerado com: documentar-funcionalidade-v2.md — projeção parcial do PRD 1.4: seções Problema, Escopo e Fora de Escopo e Restrições, Dependências e Impactos; RN08, RN10, RN11, RN17, RN21 e RN22; Telas 03 e 04; Fluxos 03, 04 e 05. Não projetadas: Critérios de Aceite, Pendências e Dúvidas em Aberto, Histórico de Versões// \\
+//Gerado com: documentar-funcionalidade-v2.md — projeção parcial do PRD 1.4: seções Problema, Escopo e Fora de Escopo e Restrições, Dependências e Impactos; RN08, RN10, RN11, RN17, RN21 e RN22; Telas 03 e 04; Fluxos 03, 04 e 05. Atualizada manualmente para o PRD 1.5: RN08, RN09, RN10, RN17 e RN22; Fluxos 04 e 05; seção Melhorias Previstas, a partir da melhoria registrada no § 22 do PRD. Não projetadas: Critérios de Aceite, Pendências e Dúvidas em Aberto, Histórico de Versões// \\
 //Revisado por: @pramorim - Paulo Ricardo Amorim Silva//