Como instalar o Pix Verifier

Ja falei um post anterior que o Pix Verifier surgiu da minha necessidade de garantir que minha equipe pudesse conferir os pagamentos realizados pelos clientes via tranferência Pix sem que eu precisasse abrir o aplicativo do banco toda hora ou deixar o Internet Banking aberto, sem falar nos comprovantes falsos que os golpistas usam para lesar os comerciantes.

Hoje em dia os bancos e principalmente fintechs costumam liberar o acesso a APIs (Application Programming Interface) para que os sistemas dos clientes, como ERPs por exemplo, possam conenctar-se ao banco a fim e integrar os fluxos. E foi se valendo dessa premissa que desenvolvi o Pix Verifier. Basicamente o que ele faz é baixar as transferências recebidas e salvar em um banco de dados local para exibição em uma página web interna que você e sua equipe terão acesso.

Nesse post então, vamos fazer a instalação e configuração da ferramenta. Um aviso importante: No momento o Pix Verifier funciona apenas com contas PJ do Banco Inter, pretendo futuramente incluir o suporte a outros bancos também. Coloca nos comentários qual banco/fintech você usa, assim eu consigo balizar a demanda.

Instalação das dependências

Para essa instalação usarei como base um sistema Windows 11, funciona no 10 também. Se você usar Linux não tem problema, as ferramentas serão as mesmas.

Com o intuíto de fazer a distribuição mais simples para qualquer pessoa conseguir instalar sem muitas dificuldades, além também de ser o padrão de mercado, o Pix Verifier foi conteinerizado, por isso vamos começar instalando o Docker.

Acesse a página abaixo e faça do download do Docker Desktop:

https://www.docker.com/products/docker-desktop/

A instalação é bem no formato Windows, Next, Next, Next, Install. Caso não identifique ele vai pedir para instalar também o WSL2 (Windows Subsystem for Linux 2), ao final é só reiniciar o Windows e pronto. Iniciando o Docker Desktop você verá uma tela como essa:

Clique no botão Sign In, na barra superior para ser redirecionado ao site do Docker Hub e fazer o login ou criar uma conta nova. Essa conta será necessária para que possamos baixar as imagens que usaremos mais adiante.

Criando aplicação no Internet Banking

Agora com o Docker instalado e pronto, precisamos criar uma aplicação no Banco Inter para que o Pix Verifier consiga acessar as APIs. Para isso acesse o Internet Banking, clique no menu Conta Digital e depois Aplicações, Nova Aplicação.

Na próxima tela, você vai fornecer um nome para a aplicação e uma breve descrição, conforme a imagem abaixo.

Clique em próximo e escolha a opção API Banking, onde iremos selecionar os escopos que a aplicação terá acesso. Isso é uma forma do banco de aumentar a segurança, pois assim uma única aplicação não tem acesso a tudo, a menos que você queira, mas não é recomendado. Selecione o escopo Consultar extrato e saldo e depois clique em Criar Aplicação.

ATENÇÃO: Depois que você clicar em Criar Aplicação e informar os tokens enviados por e-mail/sms vai ser exibida uma tela com o link para você fazer o download do certificado e chave, faça o download antes de fechar a tela pois não tem como fazer o download depois! Caso perca, terá de criar uma nova aplicação para que seja gerado um novo certificado!

Pronto! Feito esse procedimento aguarde alguns mintutos até que sua aplicação fique o status ativo. Clique nos três pontinhos na coluna Ações, depois em Detalhar aplicação para copiar do Client ID e o Client Secret, e com isso terminamos a parte do banco, agora vamos continuar com a instalação do Pix Verifier.

Baixando as imagens

O Docker funciona com o conceito de conteiners, é como se aplicação ficasse isolada do restante do sistema, é similar ao conceito de máquinas virtuais, mas aqui você não vai precisar fixar quando de memória ram, disco e processador vai estar disponível (apesar de ser possível mas não é o nosso caso) para o nosso programa que roda dentro do container. É como se o programa estivesse instalado sozinho no computador, sem nenhum outro programa competindo por recursos, mas na verdade o Docker está por baixo gerenciando os recursos.

Então é como se fosse um sistema operacional só com um programa instalado e com tudo o que é necessário para esse programa funcionar, e com isso podemos instalar esse sistema em qualquer lugar sem se preocupar com dependências, o container já vai com tudo junto simplificando muito o processo de instalação. Para o Pix Verifier precisaremos baixar duas dessas imagens, uma de um banco de dados, e outra do Pix Verifier em si. Se você tiver instalado o Docker Desktop corretamente e feito o login no Docker Hub vai ser bastante simples.

Em algum lugar do seu computador crie uma pasta chamada Pix Verifier e dentro crie o arquivo docker-compose.yml com o conteúdo abaixo:

services:
  postgresql:
    image: postgres:16-alpine3.19
    hostname: postgresql
    container_name: postgresql
    restart: unless-stopped
    environment:
      - TZ=America/Fortaleza
      - POSTGRES_DB=pix
      - POSTGRES_USER=pixverifier
      - POSTGRES_PASSWORD=pix*verifier
    volumes:
      - PostgreSQL_Data:/var/lib/postgresql/data
      - ./sql:/docker-entrypoint-initdb.d
    networks:
      - pixverifier_network

  pix-verifier:
    image: filipebezerrasantos/pix-verifier:v1.2
    hostname: pix-verifier
    container_name: pix-verifier
    restart: unless-stopped
    depends_on:
      - postgresql
    environment:
      - TZ=America/Fortaleza
      - DB_HOST=postgresql
      - DB_NAME=pix
      - DB_USER=pixverifier
      - DB_PASS=pix*verifier
    volumes:
      - Pix-Verifier_Certs:/var/www/html/services/certs
    networks:
      - pixverifier_network
    ports:
      - 80:80

volumes:
  PostgreSQL_Data:
    name: PostgreSQL_Data
  Pix-Verifier_Certs:
    name: Pix-Verifier_Certs

networks:
  pixverifier_network:
    name: pixverifier_network

Nesse arquivo estamos criando um serviço que vai usar dois containers, um chamado postgresql que é o nosso banco de dados onde vamos salvar as transações que o Pix Verifier buscar, e o outro é o Pix Verifier em si. Para melhorar a segurança recomendo alterar as linhas a seguir:

postgresql:
environment:
– TZ=America/Fortaleza => Aqui você altera seu fuso horário, só vai ter alguma efeito se você estiver na região Norte ou Fernando de Noronha onde não é UTC-3;
– DB_HOST=postgresql => NÃO ALTERE;
– DB_NAME=pix => NÃO ALTERE;
– DB_USER=pixverifier => Aqui você vai criar um usuário para o banco de dados;
– DB_PASS=pix*verifier => E aqui a senha para esse usuário;

pix-verifier:
Aqui se você alterou o usuário/senha acima do banco de dados, precisa repetir nos campos abaixo:
environment:
– TZ=America/Fortaleza => Novamente mude se seu fuso horário for diferente;
– DB_HOST=postgresql => NÃO ALTERE;
– DB_NAME=pix => NÃO ALTERE;
– DB_USER=pixverifier => O usuário que você criou;
– DB_PASS=pix*verifier => A senha que você criou;

Dentro da pasta que foi criada crie uma nova pasta chamada sql e dentro dela vamos criar o arquivo database.sql. Coloque o conteúdo abaixo dentro desse arquivo que acabou de criar:

--
-- PostgreSQL database
--


SET statement_timeout = 0;
SET lock_timeout = 0;
SET idle_in_transaction_session_timeout = 0;
SET client_encoding = 'UTF8';
SET standard_conforming_strings = on;
SELECT pg_catalog.set_config('search_path', '', false);
SET check_function_bodies = false;
SET xmloption = content;
SET client_min_messages = warning;
SET row_security = off;

\connect pix

SET statement_timeout = 0;
SET lock_timeout = 0;
SET idle_in_transaction_session_timeout = 0;
SET client_encoding = 'UTF8';
SET standard_conforming_strings = on;
SELECT pg_catalog.set_config('search_path', '', false);
SET check_function_bodies = false;
SET xmloption = content;
SET client_min_messages = warning;
SET row_security = off;

COMMENT ON SCHEMA public IS 'standard public schema';

SET default_tablespace = '';

SET default_table_access_method = heap;

CREATE TABLE public.inter (
    clientid character varying,
    clientsecret character varying,
    oauthtoken character varying,
    tokencreation timestamp without time zone
);

CREATE TABLE public.receivedpix (
    e2eid character varying NOT NULL,
    datainclusao timestamp without time zone NOT NULL,
    valor numeric(7,2) NOT NULL,
    nomepagador character varying NOT NULL,
    descricaopix character varying,
    cpfcnpjpagador character varying NOT NULL,
    nomeempresapagador character varying NOT NULL,
    idtransacao character varying NOT NULL
);

CREATE TABLE public.settings (
    key character varying NOT NULL,
    value character varying
);


CREATE TABLE public.users (
    user_id uuid DEFAULT gen_random_uuid() NOT NULL,
    username character varying NOT NULL,
    user_pwd character varying NOT NULL,
    role character varying(10) DEFAULT USER
);

INSERT INTO public.inter VALUES (NULL, NULL, NULL, NULL);
INSERT INTO public.settings VALUES ('ignoredList', '');
INSERT INTO public.settings VALUES ('ULTIMA_ATUALIZACAO', '');
INSERT INTO public.users VALUES ('7e67a531-15e7-429e-ac2a-a21024b89464', 'admin', '$2y$10$AVf3DEkvsBgfN5GxnFFHz.yU/QKLWPGnx3YT1I/8UTGU9J95kk8aq', 'admin');

ALTER TABLE ONLY public.receivedpix
    ADD CONSTRAINT receivedpix_pk PRIMARY KEY (idtransacao);

ALTER TABLE ONLY public.settings
    ADD CONSTRAINT settings_pk PRIMARY KEY (key);

ALTER TABLE ONLY public.users
    ADD CONSTRAINT users_unique UNIQUE (user_id);

O arquivo acima serve para criar a nossa estrutura de banco da dados, ele será executado automaticamente na primeira vez que iniciarmos o Pix Verifier. Antes de continuar verifique se você tem a seguinte estrutura de diretórios, se tiver tudo ok, vamos iniciar o serviço.

Pix Verifier /
—–docker-compose.yml
—–sql /
———-database.sql

Inicianto o serviço

Inicie o Docker caso tenha fechado, dentro da pasta Pix Verifiqer clique com o botão direito para abrir o menu suspenso e depois clique em Abrir no Terminal.

Quando abrir a janela do Terminal do Windows, digite o comando abaixo:

docker compose up -d

Agora é só aguardar o Docker baixar as imagens e subir os serviços.

Se você voltar lá no Docker Desktop deverá ver algo semelhante a imagem abaixo, agora acesse no seu navegador http://localhost, se aparecer a página inicial do Pix Verifier significa que está tudo ok, restando apenas agora a configuração final para começar a funcionar.

Configuração

A configuração é bem simples, basicamente precisaremos importar os certificados que foram baixados no momento da criação da aplicação no Internet Baking e fornecer o Client ID e Client Secret.

Na página inicial, no campo superior direito tem o botão Administração, clicando nele você será direcionado para a página de login, onde o usuário padrão é admin, que ja vai estar preenchido e a senha padrão é 123mudar. A página de administração é bem simples, e está divida por abas.

Na aba Usuário, você deve criar uma nova senha para que não haja acesso não autorizado. Finalizadas as configurações é só voltar na aba Home, clicar em Iniciar e pronto.

Na tela incial no canto superior direito temos o Status do serviço, esse status indica se o serviço local que faz o acesso a API do Banco Inter está funcionando, e não se a API do banco propriamente dita está disponivel, logo pode ocorrer do banco ficar fora de serviço, e o status continuar verde, porém nos logs dentro da Administração, vai indicar as falhas de conexão.

Vale ressaltar também que a atualização página não é automática, é preciso clicar em Atualizar para que o sistema busque no banco de dados as transferências que já foram baixadas. Com isso chegamos ao fim da instalação e configuração do Pix Verifier.

Considerações Finais

Esse projeto foi pensando para ser executado localmente no computador da loja ou estabelecimento que se queira fazer o acompanhamento das transferências, logo ao acessar o Pix Verifier não se exige nenha autenticação por parte do usuário. Se você tiver mais de um computador na sua rede local, você pode habilitar para que os outros computadores também tenham acesso, fazendo essa instalação em apenas um computador, que será o servidor e seguir os três passos abaixo:

Definir um IP fixo no servidor – Ler mais…

Normalmente as redes locais são configuradas para usarem DHCP, ou seja cada vez que o computador se conecta na rede, o roteador que fornece um IP, isso é um problema quando estamos rodando algum serviço, pois cada vez que o computador reiniciar ele pode receber um IP diferente, exigindo que todas as outras pessoas na rede saibam qual o IP atual do servidor.

Liberar a porta 80 no firewall do Windows – Ler mais…

Por questões de segurança o Windows bloqueia todas as conexões de entrada, isso quer dizer que mesmo definindo um IP fixo na rede e rodando o serviço, outras pessoas não conseguiriam acessar o Pix Verifiver. Para contornar, é preciso liberar porta 80 no firewall do Windows. Assim o acesso poderá ser feito normalmente.

Habilitar o Docker para inicar junto com o Windows – Ler mais…

No docker-compose.yml está definido para que o Pix Verifier inicie automaticamente, mas só será iniciado se Docker Desktop estiver em execução, logo precisamos habilitar para que o Docker execute automaticamente assim que logar no Windows. Mais abaixo eu mostro como fazer isso.

Os dois primeiros pontos acima citados eu não vou cobrir aqui nesse tutorial, pois se pesquisar no Google por “Como deixar meu IP fixo na rede” e “Como liberar a porta 80 no firewall do windows” vai aparecer inúmeros sites e vídeos no YouTube ensinando como fazer. Quanto ao Docker iniciar automaticamente é bastante simples.

No Docker Desktop, clique na engrenagem na barra superior, depois marque a caixa Start Docker Desktop when you sign in to your computer, depois clique em Apply & Restart conforme a imagem a seguir.

Espero que esse projeto lhe ajude de alguma forma, tenho planos de adicionar suporte para mais bancos e fintechs, começei com o Banco Inter pois é o banco que trabalho atualmente. Alguns bancos são mais chatos para liberar acesso a API e exigem muitos requisitos em prol da segurança deles, o que pode acabar dificultando a implementação, além que esse é um projeto pessoal e open source, eu trabalho nele no meu tempo livre que é bastante escasso 😓 e por isso que eu peço que caso esse projeto faça alguma diferença no seu dia-a-dia, considere uma doação para me apoiar. Qualquer valor é bem vindo e aceito de coração! 🥰

Não se esqueça de deixar nos comentários qualquer dificuldade, sugestão de funcionalidades e bancos para incluir suporte. Fico por aqui e até a próxima!