PixCanvas 0.5.0

SDK Python moderno para Pix estatico, BR Code, validacao e QR customizavel.

PixCanvas

SDK Python para Pix estatico com foco em BR Code correto, validacao clara, tipagem forte e QR customizavel com salvaguardas de legibilidade.

📖 Documentação completa

Status: pre-alpha. A v0.5 organiza docs, exemplos e trilha de compatibilidade para Pix estatico, mas ainda nao deve ser usada em producao sem validacao propria.

Proposta

PixCanvas nasce para ser um SDK Python moderno para Pix estatico:

• core zero-dependencia para gerar BR Code estatico;
• decode e validacao estrutural de Pix estatico;
• API tipada e imutavel;
• erros claros para payloads invalidos;
• QR opcional via extras, sem poluir quem so precisa do Copia e Cola;
• documentacao honesta sobre compatibilidade bancaria.

Gerar payload Pix e simples. O objetivo do PixCanvas e entregar confiabilidade, DX e validacao de verdade.

English Summary

PixCanvas is a Python SDK for Brazilian static Pix payments. It generates BR Code payloads, parses and validates static Pix strings, and renders optional QR Codes with safe customization controls. Banking-app compatibility must be tested manually before production use.

Quickstart

pip install PixCanvas

from decimal import Decimal

from pixcanvas import create_static_pix

pix = create_static_pix(
    pix_key="[e-mail]",
    merchant_name="Fulano de Tal",
    merchant_city="Sao Paulo",
    amount=Decimal("100.00"),
    txid="PEDIDO123",
    description="Pedido 123",
)

print(pix.br_code)

O objeto retornado contem o payload br_code e os valores normalizados usados na geracao.

Mais exemplos em examples/:

• basic_static_pix.py
• parse_validate.py
• qr_png.py
• qr_custom_logo.py
• flask_qr_endpoint.py
• fastapi_qr_endpoint.py

Parse e validacao

Use parse_pix quando payload invalido deve interromper o fluxo com uma excecao especifica:

from pixcanvas import parse_pix

parsed = parse_pix("000201...")

print(parsed.pix_key)
print(parsed.amount)
print(parsed.txid)

Use validate_pix para conferencias em lote ou APIs que preferem resultado sem excecao:

from pixcanvas import validate_pix

result = validate_pix("000201...")

if result.is_valid:
    print(result.pix)
else:
    print(result.errors)

O validador detecta erros comuns como CRC invalido, campo obrigatorio ausente, GUI incorreta, moeda diferente de BRL e pais diferente de BR. Campos EMV desconhecidos geram warnings sem invalidar o payload.

QR Code

Instale o extra opcional de QR:

pip install "PixCanvas[qr]"

Renderize a partir do objeto StaticPix:

pix.to_png("pix.png")
svg = pix.to_svg()
encoded = pix.to_base64()
data_uri = pix.to_data_uri()

Ou use as funcoes com uma string BR Code:

from pixcanvas.qr import to_png, to_svg

to_png(pix.br_code, "pix.png")
svg = to_svg(pix.br_code)

A v0.3 usa Segno como dependencia opcional e gera PNG, SVG, PDF, EPS, base64 PNG e data URI PNG.

QR customizavel

Instale o extra artistico para gerar PNG com cores, gradiente, modulos customizados e logo central:

pip install "PixCanvas[qr-artistic]"

from decimal import Decimal

from pixcanvas import QRGradient, QRLogo, QRStyle

pix.to_styled_png(
    "pix-custom.png",
    style=QRStyle(
        fill_color="#111111",
        back_color="#FFFFFF",
        module_drawer="rounded",
        gradient=QRGradient(
            kind="linear",
            start_color="#000000",
            end_color="#003366",
        ),
    ),
    logo=QRLogo(
        "logo.png",
        size_ratio=Decimal("0.22"),
        padding_ratio=Decimal("0.06"),
        background_color="#FFFFFF",
        border_color="#111111",
        border_width=2,
        radius=12,
        fit="contain",
    ),
)

Por seguranca, o PixCanvas:

• aceita somente cores hex #RRGGBB no modo seguro;
• rejeita contraste abaixo de 4.5:1;
• preserva quiet zone minima de 4 modulos;
• limita logo central a 25% do tamanho do QR;
• sobe error correction automaticamente para Q em estilos pesados e H quando ha logo.

O centro aceita PNG/JPG/WebP e GIF. Como a saida de to_styled_png e PNG estatico, GIFs usam o primeiro frame como imagem central. QRLogo permite customizar padding, fundo, borda, raio, modo de encaixe (contain, cover, stretch) e se o alpha da imagem deve ser respeitado.

Para validar o PNG gerado por decoder local, instale o extra de validacao:

pip install "PixCanvas[validate]"

pix.to_styled_png("pix-custom.png", style=QRStyle(), validate=True)

validate=True confirma que o QR gerado decodifica exatamente para o mesmo BR Code. Isso aumenta a confianca tecnica, mas QR customizado ainda deve ser testado em apps bancarios reais antes de uso em producao.

QR artistico experimental

A v0.4.x inclui um modo experimental para usar uma imagem PNG/JPG/WebP como mascara, forma de marca ou fundo do QR:

from decimal import Decimal

from pixcanvas import QRArtisticSource, QRArtisticStyle

pix.to_artistic_png(
    "pix-art.png",
    source=QRArtisticSource("logo.png", fit="contain"),
    style=QRArtisticStyle(
        mode="brand_shape",
        accent_color="#003366",
        strength=Decimal("0.65"),
        module_drawer="rounded",
    ),
    validate=True,
)

Modos disponiveis:

• image_mask: usa a imagem como mascara de intensidade dos modulos.
• brand_shape: usa a silhueta/area da imagem como destaque visual.
• background_blend: usa a imagem como fundo de baixa opacidade.

SVG e suportado via extra separado:

pip install "PixCanvas[qr-svg]"

Esse modo e experimental: ele preserva finder patterns e quiet zone por padrao, usa error correction H, mas ainda precisa ser testado em apps bancarios reais antes de qualquer uso publico.

Normalizacao

PixCanvas normaliza entradas comuns antes de montar o BR Code:

• CPF/CNPJ podem ser enviados com ou sem pontuacao.
• E-mail e EVP sao normalizados para lowercase.
• Telefone brasileiro aceita +55, 55 ou formato local com sinais de telefone, como (11) 99999-9999.
• Nome e cidade removem acentos, viram uppercase e respeitam os limites do BR Code.
• description fica limitada a 23 caracteres; valores maiores usam os 20 primeiros caracteres + ....
• amount aceita Decimal, str decimal com ponto ou None; float e rejeitado.

Pix dinamico ainda nao esta disponivel nesta fase; veja o desenho planejado em Pix dinamico (planejado).

Instalacao

pip install PixCanvas
pip install "PixCanvas[qr]"
pip install "PixCanvas[qr-artistic]"
pip install "PixCanvas[qr-svg]"

Extras previstos:

• qr: renderizacao QR base com Segno.
• qr-artistic: QR customizavel com logo, cores e validacoes de legibilidade.
• qr-svg: conversao opcional de SVG para QR artistico experimental.
• validate: validacao opcional do QR renderizado por decoder local.

Pix dinamico via PSP adapters esta planejado para v2.0; ainda nao ha extra instalavel (veja Pix dinamico (planejado)).

Roadmap

Fase	Objetivo
Fase 0	Fundacao do pacote, README, CI, coverage 100%, PyPI preparado
v0.1	Core zero-dependencia para gerar Pix estatico
v0.2	Decode, parse e validacao estrutural
v0.3	QR base como dependencia opcional
v0.4	QR customizavel com salvaguardas de legibilidade
v0.4.x	QR artistico experimental com imagem fonte
v0.5	Docs, exemplos e tabela de compatibilidade bancaria
v1.0	API estavel
v2.0	Pix dinamico (PSP adapters) — em planejamento, sem prazo definido

Especificacao

Versao alvo documentada:

• Manual de Padroes para Iniciacao do Pix v2.9.0, divulgado pela IN BCB no. 658/2025.
• Manual do BR Code publicado pelo Banco Central do Brasil.

Compatibilidade bancaria

Compatibilidade real precisa ser testada em apps bancarios. Conformidade com a especificacao nao garante aceite por todos os PSPs.

Banco/app	Payload estatico	QR padrao	QR customizado seguro	QR artistico	Data	Observacao
Nubank	Aprovado	Aprovado	Aprovado	Aprovado	2026-07-07	App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico.
Inter	Aprovado	Aprovado	Aprovado	Aprovado	2026-07-07	App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico.
Banco do Brasil	Aprovado	Aprovado	Aprovado	Aprovado	2026-07-07	App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico.
Itau	Aprovado	Aprovado	Aprovado	Aprovado	2026-07-07	App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico.

Estados aceitos: Nao testado, Aprovado, Falhou, Parcial, Inconclusivo.

Nenhum banco deve ser marcado como aprovado sem data e teste manual. Testes acima cobrem os bancos disponiveis para teste no momento; mais bancos serao adicionados conforme testados.

Procedimento resumido de teste:

1. Teste o copia-e-cola.
2. Teste o QR padrao.
3. Teste o QR customizado seguro.
4. Teste QR artistico apenas como experimental.
5. Registre banco, data, tipo de QR e resultado.

Desenvolvimento local

Instale as dependencias de desenvolvimento:

uv sync --extra dev

Rode a suite de qualidade:

uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pytest

Exemplos tambem sao cobertos pela suite de testes.

Build da documentacao:

uv sync --extra dev --extra docs
uv run mkdocs build --strict

Versionamento

Veja CHANGELOG.md, VERSIONING.md e CONTRIBUTING.md.

Qualidade

Coverage de testes e gate permanente em 100%:

uv run pytest --cov=pixcanvas --cov-report=term-missing --cov-fail-under=100

Regras de desenvolvimento:

• cobertura abaixo de 100% bloqueia merge;
• core runtime sem dependencias externas;
• dinheiro sempre com Decimal, nunca float;
• API publica tipada;
• excecoes especificas para erros de dominio;
• QR e Pix dinamico sempre atras de extras opcionais.

Licenca

MIT. Veja LICENSE.