pix-engenharia-reversa

Laboratório público e auditável para aprender como o PIX funciona por dentro — e como construir um sistema de pagamentos instantâneos inspirado no mesmo modelo.

Este repositório transforma o artigo Engenharia reversa do PIX em código executável: você decodifica um BR Code campo a campo, simula o DICT e o SPI, e ainda encontra o blueprint de uma stack de produção para quem quiser criar o próprio arranjo — ou se integrar ao PIX real do Banco Central.

• Por que este repositório existe
• O que você vai aprender
• Arquitetura
• Estrutura do repositório
• Rodar o laboratório
• Python x stack real (não confunda)
• Como contribuir
• Segurança
• Sobre o autor
• Licença

O PIX é um dos maiores sistemas de pagamentos instantâneos do mundo — e, ao contrário do que muita gente imagina, o desenho dele é aberto: o Banco Central publica os manuais de padrões, as APIs e o manual de segurança. O que é fechado é a rede (SPI e DICT só aceitam participantes autorizados).

Este projeto usa essa documentação pública para ensinar, de forma didática e auditável:

1. como o PIX funciona por dentro (DICT, SPI, Conta PI, ISO 20022, BR Code);
2. como decodificar um pagamento real (TLV + CRC16 em Python puro);
3. como simular o arranjo em um mini-DICT + mini-SPI;
4. como construir o próprio sistema instantâneo (stack + infraestrutura no docs/ e em DEPLOY.md);
5. como se integrar ao PIX real do BCB (rota gateway → participante indireto → participante direto).

Aviso importante: este conteúdo é 100% educacional. Operar arranjo de pagamento sem autorização, forjar confirmações ou usar chaves/contas de terceiros é ilegal no Brasil (Lei nº 12.865/2013 e Regulamento do PIX, Resolução BCB nº 1/2020).

O blueprint completo (catálogo de serviços, modelo de dados, segurança, infraestrutura, testes e roadmap) está em docs/blueprint-pagamentos-instantaneos-stack.md.

pix-engenharia-reversa/
├── assets/             # banner e mídia do README
├── lab/                # Laboratório didático — Python puro, testado
│   ├── brcode/             # parser TLV do BR Code + CRC16-CCITT
│   ├── minipix/            # Mini-DICT (chave → conta) + Mini-SPI (liquidação)
│   └── tests/              # 12 testes unitários (stdlib)
├── stack/              # Esqueleto da stack de produção
│   ├── assets/             # diagramas
│   ├── docker-compose.yml  # Postgres + Redis (dev)
│   ├── services.md         # mapa dos serviços e fronteiras de domínio
│   └── README.md           # visão da stack
├── docs/               # blueprint completo da arquitetura
├── .github/workflows/  # CI (testes automáticos)
├── CONTRIBUTING.md     # guia para contribuir
├── SECURITY.md         # como reportar vulnerabilidades
├── DEPLOY.md           # como subir no ar
└── LICENSE             # MIT

Requisitos: Python 3.9+ (para a API opcional: FastAPI) e Docker (para o ambiente dev da stack).

# 1) testes do laboratório — sem nenhuma dependência
python -m unittest discover -s lab/tests -v

# 2) infra dev da stack (Postgres + Redis)
docker compose -f stack/docker-compose.yml up -d

# 3) API didática (opcional)
pip install -r lab/requirements.txt
uvicorn lab.minipix.api_fastapi:app --reload

Endpoints da API didática:

POST /dict/chaves          cadastra uma chave (tipo, chave → conta)
GET  /dict/chaves/{chave}  consulta a conta dona da chave
POST /spi/pagamentos       liquida um pagamento (idempotente via request_id)

O Python aqui é intencional: é a forma mais curta de ensinar os conceitos. A implementação real dos serviços (ledger, accounts, keys...) está especificada no blueprint — esse é o próximo passo natural deste repositório.

Este projeto é um bem público. Issues, correções de typos, testes novos e melhorias de documentação são muito bem-vindas — veja o CONTRIBUTING.md.

Encontrou uma vulnerabilidade ou algo errado? Não abra uma issue pública: escreva para pedro@pedrodapps.com — detalhes no SECURITY.md.

Pedro Magalhães — desenvolvedor e criador do canal Pedro dApps, onde explica IA, blockchain e engenharia de software de forma prática.

• GitHub: pedrosgmagalhaes
• Blog: pedrodapps.com · blog.pedrodapps.com
• YouTube: @pedro_dapps
• X/Twitter: @pedro_dapps

Distribuído sob a licença MIT — use, estude e evolua por sua conta e risco. Veja o arquivo LICENSE.