bitts / pagtesouro

Sistema para geração de pagamentos digitais utilizando API do PagTesouro e PHP (Formulário simples e Componente Joomla!)

PagTesouro

Formulário de integração com API do PagTesouro

Necessita de Colaboradores!!!

Formulário de Integração com o PagTesouro

Acompanhamento do projeto

• Interface Administrativa:

  • Cadastro de Tokens (Banco de Dados)

    Melhorias: atualmente salvando dados no formato string, com o JSON contendo os dados cadastrados (mudar para tabelas específicas?)

  • Exibir dados cadastrados pelos usuário no formato padrão do Joomla de apresentação de listagens

  • Exibir mensagem de atualizações com base no GitHub e versão publicada

  • Personalização do CSS do formulário atráves da interface administrativa em nova aba de apresentação de opções

    Obs.: Verificar editores de css possíveis de integração e compatíveis com Joomla

• Interface Usuário:

  • Salvar dados submetidos no formulário em banco de dados
  • Consultar documento

Créditos

Author / Autores

Marcelo Valvassori Bittencourt (bitts)

Init Project / Software Tester

Júlio César Vieira Malliotti (Malliotti)

Colaboração Direta

Marcos Luiz Rezende de Melo (mlrmelo)

Colaboração Indireta

Rafael Menezes (rafaelms87)

Sistema de Pagamento do Tesouro

O PagTesouro é um componente de processamento de pagamentos digitais gerido pela Secretaria do Tesouro Nacional (STN), um órgão vinculado ao Ministério da Economia e que tem como missão principal gerenciar as contas públicas de forma eficiente e transparente. No contexto do processo de Gerenciamento das Receitas da União, o componente PagTesouro atua no cenário de recolhimento de receitas de Órgãos e entidades da administração Pública Federal como taxas (custas judiciais, emissão de passaporte, etc.), aluguéis de imóveis públicos, serviços administrativos e educacionais, multas, entre outros, permitindo o pagamento em forma digital, assim como a impressão do boleto de pagamento. O pagamento pode ser feito pelas formas Pix, cartão de crédito e boleto de GRU Simples.

Sobre o Sistema de Integração

Sistema simples para geração de GRU utilizando a API do PagTesouro. Projeto iniciado por Malliotti, transformado adaptado por Marcelo para utilização de PHP, ocultando assim dados como a url de requisição e a própria chave de autorização de acesso da Organização Militar vinculada.

Aqueles interessados em realizar melhorias, fiquem a vontade, este é um projeto aberto e a utilização do Github visa centralizar melhorias para beneficio de todos.

Procure manter o projeto de forma que os clientes necessitem editar somente o arquivo JSON (facilitando assim atualização).

Documentação de Referência

https://valpagtesouro.tesouro.gov.br/simulador/#/pages/api

https://pagtesouro.tesouro.gov.br/docs/api-psp/

Versions

• [03/02/2021] 1.0 - Modificações básicas para funcionamento da API utilizando cURL do PHP, enviado os dados do formulário para classe PHP que trata os dados, inclui as chaves de autorização e URL para realizar as requisições ao PagTesouro.

• [19/02/2021] 1.1 - Alterado sistema para funcionar com vários Tokens

• [20/02/2021] 1.2 - Alteração para configurações em arquivo json

  • [Validado] Alterado para cadastramento dos dados de Tokens e Serviços para o arquivo pagtesouro.json
  • [Validado] Adicionado novas formas de envio dos dados ao PagTesouro (file_get_contents e fopen, além do curl como última alternativa já que em muitos servidores algumas dessas bibliotecas podem não estarem habilitadas por default no PHP)
  • [Validado] Adição de arquvio .htaccess com regras básicas para segurança ou para eviar erros de chamada

• [22/02/2021] 1.3 - [Validado] Funcional para diversos Token

• [01/02/2021] 1.4 - [Validado] Sistema para hospedagem simples

• [16/03/2021] 2.0 Funciona como componente do Joomla!

• Veja Documentação de como Instalar no Joomla!

• [28/03/2021] 2.1 - Diversas melhoras:

  • Exportar cadastro realizado na interface Administrativa (backup do pagtesouro.json)

  • No formulário de geração o(s) Serviço(s) agora é(são) apresentados por UGE (optgroup do select)

  • Diversas melhoras na interface de administração para se adptar mais ao padrão Joomla!

  • Aplicação de mascara nos campos do formulário de geração

  • Formulário de geração mais compacto

  • Na interface administrativa aba para acompanhar atualizações do Componente do PagTesouro

  • Também na interface administrativa aba com conteudo do arquivo README.me mais atual direto do Github

• [05/03/2022] 2.2 - Correções para possível publicação no site Extensions Directory

• [15/03/2022] 2.2 - Publicação no site Extensions Directory

  • Modificação da abertura do retorno do Pagtesouro de iframe para windows.open (abertura em nova janela)

• [14/06/2022] 3.0 - Melhorias na interface de administração modificando a sistemática para salvamento das informações em Banco de Dados.

Primeiros passos antes da implementação

Passo a Passo - Material de Rafael Menezes

Resumo

Siga os passos abaixo para que o sistema esteja funcional:

1 - Gere os Códigos Necessários (Setor Financeiro)

A - Solicite o Setor Financeiro de sua organização (usuário SIAFI válido) que gere um Token para cada uma das UGs sobre sua gerência, no SISGRU. Aba PagTesouro / Autorização de uso do PagTesouro / inserir o código da UG, o período para utilização e setar situação "ativo".

B - Solicite o Setor Financeiro (usuário SIAFI válido) que gere os Códigos de Serviço correspondentes para cada UG., no SISGRU. Aba PagTesouro / Catálago de serviços / Inserir o código da UG, código de recolhimento da GRU e o tipo de serviço. Após isso, selecione Incluir.

Uso para sistema Joomla

• Acessar painel administrativo do Joomla
• Ir no Menu > Extesions > Manager > Install
• Na opção "Upload Package File" você precisa fazer o download do arquivo da versão 2.2 para o seu computador e depois escolher o arquivo para instalação;
• Vá no Menu "Components" > "PagTesouro", para adicionar ou remover seus Tokens e Serviços
• Em caso de dificuldades veja documentação do sistema ou a interpretação das mensagens do sistema

Uso para hospedagem simples

• Realize o download do sistema na versão v1.4
• Adicionar os arquivos em um pasta dentro do Joomla
• Editar arquivo pagtesouro.JSON

Caso você utilize Joomla é quer colocar o conteudo deste formulário de forma integrada em seu site

• Criar dentro do Joomla um conteudo do tipo iframe e aponte para o arquivo index.php
• O arquivo pagtesouro.html é a template do formulário e PODE (não precisa) ser modificada para adequar-se melhor a realidade de onde deseja integrar o sisteminha
• Evite modificar arquivos como o pagtesouro.php ou o pagtesouro.html, se você realmente não sabe o que esta fazendo
• A descrição pode ser alterada no arquivo pagtesouro.json para facilitar o uso pelo cliente, no caso de varias UGs você pode editar para "UG 6666-6 | 701 - Indenizações" ao invés de utilizar somente "701 - INDENIZAÇÕES"
• Abaixo alguns detalhes do arquivo de configuração para hospedagens simples onde é preciso editar o arquivo (ARQUIVO: pagtesouro.json)

[
    {
        "token" : "Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxNjAwODYifQ.fY4bWesL85B_vFSOmRUyfrawte-SjSuqKcFQTfyfMQVFKyl6gfJKX63o_wElLkb3MHXl5xmQG9zlQasv5V561uq-R8uV6Gi35iXy36hk6wdc8LyLk-WgVD5TN4fyCCrZ5VH6tuayM7xmZ3fPyPdfJFknCCao48E2skbptEHS-8VUjFKAUObd_oFblDsyc8jC0cYPfX7p8IbO1kdeibqBbu-wpnGczsmoWftMkmS82Y-U9EqcRcY5IN10IcVFg_IJ7Mo5SeH3snfrcOMVP-DMjUH0MefmHUqN0eMGlBbeZK1rHxvRXfB7Ual9PORzyhuTO5kzIYK90EW1sT2qNl4TXA",
        "servicos" : [
            {
                "codigo" : 701,
                "descricao": "701 - INDENIZAÇÕES"
            },
            {
                "codigo": 702,
                "descricao" : "702 - INDENIZAÇÕES USO IMOVEIS"
            }
        ]
    },
    {
        "token" : "Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxNjAwODYifQ.fY4bWesL85B_vFSOmRUyfrawte-SjSuqKcFQTfyfMQVFKyl6gfJKX63o_wElLkb3MHXl5xmQG9zlQasv5V561uq-R8uV6Gi35iXy36hk6wdc8LyLk-WgVD5TN4fyCCrZ5VH6tuayM7xmZ3fPyPdfJFknCCao48E2skbptEHS-8VUjFKAUObd_oFblDsyc8jC0cYPfX7p8IbO1kdeibqBbu-wpnGczsmoWftMkmS82Y-U9EqcRcY5IN10IcVFg_IJ7Mo5SeH3snfrcOMVP-DMjUH0MefmHUqN0eMGlBbeZK1rHxvRXfB7Ual9PORzyhuTO5kzIYK90EW1sT2qNl4TXA",
        "servicos" : [
            {
                "codigo" : 701,
                "descricao": "701 - INDENIZAÇÕES"
            },
            {
                "codigo": 702,
                "descricao" : "702 - INDENIZAÇÕES USO IMOVEIS"
            }
        ]
    }   
]

• Valide o seu arquivo JSON em https://jsonlint.com/

Em utilização por

• CMA - Colégio Militar de Manaus

• AMAN - Academia Militar das Agulhas Negras

• EsSLog - Escola de Sargentos de Logística

• 1º BIS - 1º Batalhão de Infantaria de Selva (Amv)

• 12º BSup - 12º Batalhão de Suprimento

• CCFEx - Centro de Capacitação Física do Exército

• CMA - Comando Militar da Amazônia

• EsAO - Escola de Aperfeiçoamento de Oficiais

• EsACosAAe - Escola de Artilharia de Costa e Antiaérea

• CRO 12 - Comissão Regional de Obras da 12ª Região Militar

• EsIE - Escola de Instrução Especializada

• 2ª Bda Inf Sl - 2ª Brigada de Infantaria de Selva

• CEP/FDC - Centro de Estudos de Pessoal e Forte Duque de Caxias

• IME - Instituto Militar de Engenharia

• CML - Comando Militar do Leste

• HCE - Hospital Central do Exército

• CMRJ - Colégio Militar do Rio de Janeiro

• CMM - Colégio Militar de Manaus

• 54º BIS - 54º Batalhão de Infantaria de Selva

• 16ª Bda Inf Sl - 16ª Brigada de Infantaria de Selva

• HGuT - Hospital de Guarnição de Tabatinga

• 2ª RM - 2ª Região Militar

• HGuPV - Hospital de Guarnição de Porto Velho

• 36º BI Mec - 36º Batalhão de Infantaria Mecanizado.

• 17ª Bda Inf Sl - Comando da 17ª Brigada de Infantaria de Selva

• 1° Esqd C L - 1° Esquadrão de Cavalaria Leve

• 7º BEC - 7º Batalhão de Engenharia de Construção

• 8º BIS - 8º Batalhão de Infantaria de Selva

• HMAM - Hospital Militar de Área de Manaus

• 47º BI - 47º Batalhão de Infantaria

• 6º BIS - 6º Batalhão de Infantaria de Selva

• 7° BIB - 7° Batalhão de Infantaria Blindado

• 4º BIS - 4º Batalhão de Infantaria de Selva

• 4º BAvEx - 4º Batalhão de Aviação do Exército

• 12ª RM - 12ª Região Militar

• HGeRJ - Hospital Geral do Rio de Janeiro.

pagtesouro's Issues

Publicação do Componente no https://extensions.joomla.org/ (resposta)

Marcelo Valvassori Bittencourt 18.02.2022 15:59:15

What are the application problems?

---

Jeroen Moolenschot 24.02.2022 22:52:37

Hi Marcelo,
Thank you for changing the description into English. 
I have renamed your listing in the JED into "PagTesouro".
There are some errors which need to be fixed before we can publish this extension.

US1 - Update Servers missing or incorrect in XML file(s).

The update servers tag in your XML file(s) is missing or incorrect. This is a requirement of all extensions uploaded after 10th January 2017

---

PH2 - Files missing JEXEC security

Security is extremely important in Open Source Software, so to help prevent execution of files outside of the framework, the following code is required in all of your PHP files unless they are external library files:

no direct access defined( '_JEXEC' ) or die( 'Restricted access' ); 

This code is missing at the start of the following files:

/pagtesouro-save.php

/pagtesouro.php

/site/call.php

/site/class.pagtesouro.php

/site/pagtesouro.php

When you have fixed this issues please, reupload the package and open a new ticket so we can recheck an approve your extension.

Kind regards,

Jeroen Moolenschot

---

Tradução

Jeroen Moolenschot 24.02.2022 22:52:37

 Olá Marcelo,
 Obrigado por mudar a descrição para o inglês. 
 Eu renomeei sua listagem no JED para "PagTesouro".
 Existem alguns erros que precisam ser corrigidos antes que possamos publicar esta extensão.

---

US1 - Servidores de atualização ausentes ou incorretos no(s) arquivo(s) XML.

A tag de servidores de atualização em seu(s) arquivo(s) XML está ausente ou incorreta. Este é um requisito para todas as extensões enviadas após 10 de janeiro de 2017

---

PH2 - Arquivos sem segurança JEXEC

A segurança é extremamente importante no software de código aberto, portanto, para ajudar a evitar a execução de arquivos fora da estrutura, o seguinte código é necessário em todos os seus arquivos PHP, a menos que sejam arquivos de biblioteca externa:

 nenhum acesso direto definido( '_JEXEC' ) or die( 'Acesso restrito' );

Este código está ausente no início dos seguintes arquivos:

/pagtesouro-save.php

/pagtesouro.php

/site/call.php

/site/class.pagtesouro.php

/site/pagtesouro.php

Quando você corrigir esses problemas, reenvie o pacote e abra um novo ticket para que possamos verificar novamente e aprovar sua extensão.

Atenciosamente,

Jeroen Moolenschot

Remover a máscara do campo referência

O campo Referência é um campo opcional com até 20 posições numéricas.
Está com máscara "mm/aaaa", como se fosse relativo a um mês/ano, mas é simplesmente um código numérico

Registro/Apresentação dos Serviços por UGE

Na tela do registro do token, a gente cadastra apenas o token e os serviços associados.
Há algumas OMs que são UGE de várias OMs (Ex: 1ª RM é UGE de mais de 10 OMs, incluindo o 2º CTA).
Seria interessante ter:

• No Registro do token, haver os campos para cadastro da OM e Código de UGE
• Na tela de pagamento, para o caso citado, o Usuário poder escolher de qual OM se trata.

Botão abrir arquivo de backup

Existe um problema ao utilizar new FileReader() ao selecionar o arquivo para restore uma segunda vez.
Para isso atualmente o sistema, após abrir um arquivo a primeira vez, desaparece! Reaparecendo somente quando é recarregado a interface de administração (mascarando assim este bug).

Para colocar o botão no menu do topo é necessário concertar este bug.

Sugestões atuais:

• após carregar o arquivo de backup destruir e recriar botão e sua ação;
• estudar melhor metodos de callback do FileReader;
• levar para backend e tratar com php a abertura do arquivo, retornando seu conteudo para interface;

Erro ao recuperar o arquivo JSON

Ao fazer uma recuperação do Arquivo JSON backupeado, ele apaga os Tokens e códigos de serviço existentes, mas mantém o CodUG e o nome OM, acrescentando, ao final, o que foi restaurado.
Assim, ficam as OMs, sem códigos MAIS o que foi restaurado...
Quando tem que instalar uma versão nova, ele apaga os dados que existem e coloca os códigos de exemplo.
Ao recuperar o JSON, vai ficar:

• Os exemplos +
• O recuperado
  Obrigando o usuário a apagar o exemplo

Alterar apontamento do formulário

Da maneira como está, a chamada ao formulário é feita através da administração do Joomla (/?option=com_pagtesouro).
O ideal é que possa ser feita a chamada através de um apelido (Ex: /pagtesouro), como qualquer artigo ou módulo do Joomla. Isto, inclusive faz parte das questões de segurança (usar resescrita de URL e URLs aigáveis).
Aqui no 2º CTA, adotamos uma maneira simples, mas eficaz de proteger a administração: temos 2 URL para a página:

• admin..eb.mil.br → acessível apenas na EBNet, onde se pode acessar a pasta /administrator
• www..eb.mil.br → acessível na Internet, onde NÃO se pode acessar a pasta /administrator
  São 2 VirtualHost no apache, onde o www aponta para uma subpasta que contém apenas links para TUDO que está na pasta principal EXCETO a pasta /administrator.
  Da maneira como está, ele faz a chamada para a pasta /administrator/componentes/com_pagtesouro, então ele não encontra o formulário na internet e traz a página em branco
  Esta é uma condição essencial para que possa ser adotado como padrão de uso pelo 2º CTA (provavelmente, o mesmo aconteça nos outros CT/CTA)
  Uma sugestão:
  Normalmente, os componentes criam uma entrada na lista de "tipos de ítens de menu", que faze a carga do formulário correspondente.
  Ou, se for mais fácil, criar um apontamento direto para o formulário, usando o alias (apelido) dele.

Colocar labels nos campos

No preenchimento dos campos na tela de administração, colocar labels nos campos:

• Código da UGE
• Nome da UGE
• Token
• Código do Serviço Cadastrado
• Descrição do Serviço Cadastrado
  OBS: Estes dois mostraram-se importantes, pois tem OM cadastrando o Código de Recolhimento, que é outro e não faz parte do JSON a ser enviado
  Talvez uma boa ideia, também, seja a de incluir o CODOM, mesmo sendo desnecessário para a API, para que as OMs não confundam o CODOM com o CODUG, ou então fazer essa advertência (observei essa confusão, também)

Salvando dados do Formulário em Base de Dados

Salvar os dados do formulário de geração do PagTesouro para tabela da base de dados Joomla.

Anexar a issue documentação referente a criação de tabelas na instalação do componente.

Centralizar campo CPF

Apenas estética...
Como está, parece que a página está mal formatada (dá a impressão que o campo nome não coube no espaço e foi jogado pra baixo)

Prevenir ataque CSRF

Implementação de bloqueio cross-site request forgery (falsificação de solicitação entre sites)

Método: utilização de token
Esse método consiste em incluir um token (string) aleatório em cada solicitação, ou seja, será adicionado um campo oculto a cada formulário existente com o token como valor.

Esse token é gerado pelo PHP e armazenado em uma sessão para quando existir uma requisição, o sistema fazer a comparação com o valor que foi preenchido automaticamente (ou mal-intencionada) no formulário.

$_SESSION['token'] = md5(uniqid(rand(), true));)

Ou

function generateRandomString($length = 15) {
    $characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
    $charactersLength = strlen($characters);
    $randomString = '';
    for ($i = 0; $i < $length; $i++)
        $randomString .= $characters[rand(0, $charactersLength - 1)];

    return $randomString;
} 
$_SESSION['Token'] = generateRandomString();

<input type="hidden" name="token" value="<? php echo $_SESSION['token']?>" />

Restore/Backup do cadastro

• Botão para backup da dos dados cadastrados
• Botão para selecionar e restaurar arquivo de backup

Correção no tutorial

No tutorial na wiki do GitHub (https://github.com/bitts/PagTesouro/wiki/Componente-Joomla) consta que o nome do arquivo para fazer Download é INSTALADOR.zip e o link aponta para o arquivo comPagTesouro (https://github.com/bitts/PagTesouro/releases/download/v2.1/com_PagTesouro.zip), embora o arquivo no site principal seja PagTesouro-main.zip
OBS: O padrão das extensões Joomla é:
com_ → componente
mod_ → módulo
plg_ → plugin
pkg_ → pacote

Validação de arquivo de backup em sua restauração

• Validar arquivo pagtesouro.json (ou arquivo de backup) ele deve estar no padrão novo para que funcione corretamente.
• Exibir mensagem de erro informando que o arquivo não esta no padrão correto.

Obs.: Quando o arquivo no padrão correto do objeto javascript, assim que carregada a interface de administração, o formulário de cadastro de UGEs/Tpkens/Serviços fica preenchido com os dados (já funcional).

Erro na abertura do formulário

Estou tendo o seguinte erro quando abro o formulário para gerar a GRU no Joomla:

json_decode(): Argument #1 ($json) must be of type string, stdClass given
/var/www/html/joomla/components/com_pagtesouro/class.pagtesouro.php:435

Alguém já teve esse problema?

Utilização de mascara em determinados campos

Utilização de mascara em determinados campos para previnir erro de digitação de usuários:
Campos necessários:

• Competência mm/yyyy
• Referência mm/yyyy
• CPF/CNPJ

Necessário aplicar mascara e remove-las de antes de serem submetidas ao servidor do PagTesouro.

Calendário (datepicker) para campos de data

Colocar ação de datepicker nos input que contem seleção de data