Pular para conteúdo

Pix dinamico (planejado)

Ainda nao implementado

Esta pagina descreve um desenho de arquitetura planejado para a v2.0. Nao existe nenhum codigo de Pix dinamico no PixCanvas hoje — nem modulo, nem interface concreta, nem adapter de PSP.

Por que ainda nao existe

O PixCanvas nasceu focado em Pix estatico: gerar, decodificar e validar payloads BR Code sem depender de nenhuma API externa. Pix dinamico exige comunicacao HTTP com um Provedor de Servico de Pagamento (PSP) — autenticacao OAuth2, mTLS e os verbos da API Pix do Banco Central (cob, cobv, consulta, webhook). Isso muda a natureza do pacote: deixa de ser uma biblioteca puramente local para depender de rede e credenciais de um PSP.

A decisao deliberada foi adiar essa complexidade para depois que o Pix estatico e o QR customizavel estiverem maduros e testados em producao.

O que ja existe hoje

O parser ja trata Pix dinamico como um caso conhecido, mesmo sem suporta-lo:

  • parse_pix rejeita explicitamente um BR Code dinamico (campo 01 = "12") levantando UnsupportedDynamicPixError, em vez de tentar decodificar um payload que nao e estatico.
  • validate_pix reporta o mesmo erro dentro de ValidationResult, sem exception, para quem prefere o modo sem excecao.

Ou seja: hoje o PixCanvas erra de forma clara quando ve Pix dinamico, em vez de dar um resultado incorreto silenciosamente.

Desenho planejado (v2.0)

Quando a v2.0 for implementada, o plano é:

  • Novo modulo pixcanvas/dynamic/, seguindo o mesmo padrao de isolamento do pixcanvas/qr/ (core continua zero-dependencia).
  • Interface abstrata PSPClient com os verbos padronizados da API Pix do Bacen: cob, cobv, consulta, webhook.
  • Primeiro adapter concreto sobre um PSP com onboarding self-service (ex. Banco Inter ou Efi), autenticando via OAuth2 + mTLS.
  • Extra opcional [dynamic] para instalar as dependencias HTTP/TLS necessarias — o core continua instalavel sem nenhuma dependencia externa.
  • Modelos imutaveis e Decimal para valores monetarios, seguindo o mesmo padrao ja usado em StaticPix.

A interface PSPClient sera desenhada antes de qualquer adapter concreto, para que a extensibilidade seja arquitetural e nao apenas prometida.

Acompanhando o progresso

Este trabalho depende de adocao real do Pix estatico primeiro. Acompanhe o roadmap no README e o CHANGELOG para atualizacoes.