ZaptVupt Delphi Pix SDK - Engine Multi-Banco & Multi-PSP (11 Bancos/PSPs)

ZaptVupt Delphi Pix SDK (v2.1.0)

Engine Clean-Room Multi-Banco e Multi-PSP em Object Pascal para sistemas desktop, PDVs, ERPs, daemons e servicos Windows desenvolvidos em Delphi 10.4 Sydney, 11 Alexandria e 12 Athens (Win32 e Win64).

Bancos e PSPs Suportados (11 Integracoes Online + EMVCo Offline)

• Bancos Nacionais BACEN Pix API v2 (OAuth2 + mTLS Nativo WinHTTP):
• Banco do Brasil (ForBancoDoBrasil) — OAuth2 Basic Form, parametro obrigatorio gw-dev-app-key, A1/PFX mTLS, criacao PUT /cob/{txid}, consulta GET /cob/{txid}, cancelamento PATCH /cob/{txid}, consulta E2EID GET /pix/{e2eid} e devolucao PUT /pix/{e2eid}/devolucao/{id}.
• Banco Inter (ForBancoInter) — OAuth2 body form /oauth/v2/token, suporte ao header x-conta-corrente para multi-contas PJ, A1 mTLS e ciclo completo BACEN v2.
• Sicoob (ForSicoob) — OpenID Connect Keycloak, header obrigatorio client_id em todas as chamadas Pix v2, A1 mTLS e ciclo completo BACEN v2.
• Sicredi (ForSicredi) — OAuth2 Basic Form + A1 mTLS cooperativo + ciclo completo BACEN v2.
• Itau (ForItau) — STS OAuth2 /api/oauth/token, headers x-itau-apikey e x-itau-correlationID, A1 mTLS e ciclo completo BACEN v2.
• Bradesco (ForBradesco) — QR Pix v2 (qrpix.bradesco.com.br) com OAuth2 Basic Form + A1/PFX mTLS.
• Santander (ForSantander) — OAuth2 + header client_id + A1 mTLS sobre Trust Pix API.
• Efi Bank / Gerencianet (ForEfiBank) — OAuth2 JSON grant_type + A1/P12/Windows Store mTLS + ciclo completo BACEN v2.
• Instituicoes de Pagamento / PSPs (Bearer / API Key, Sem mTLS):
• PagBank / PagSeguro (ForPagBank) — Orders API (POST /orders, GET /orders/{id}), cancelamento/estorno (POST /charges/{id}/cancel) e verificacao de webhook SHA-256 x-authenticity-token.
• Mercado Pago (ForMercadoPago) — Pix v1 (POST /v1/payments, GET /v1/payments/{id}), cancelamento (PUT status=cancelled), estorno (POST /refunds), X-Idempotency-Key e webhook HMAC-SHA256 x-signature.
• Asaas (ForAsaas) — Fluxo v3 em 3 etapas (GET/POST /customers, POST /payments billingType=PIX, GET /pixQrCode), cancelamento DELETE /payments/{id}, estorno POST /payments/{id}/refund e webhook token tempo-constante.
• Motor Offline & QR Vector/Bitmap (GenerateOfflineEMVCoCharge):
• Geracao estatica EMVCo BACEN com CRC16-CCITT (0x1021), matriz QR e renderizacao SVG / TBitmap em RAM sem DLLs externas.

Arquitetura do Pacote

1. Core Base (Vendor_ZVCore, incluido no ZIP):

• ZV.Core.Types.pas — validacao matematica Modulo 11 de CPF e CNPJ, conversao unificada de status Pix (BACEN/PagBank/MP/Asaas) e geracao UUID v4.
• ZV.Core.Json.pas — leitor JSON defensivo contra Access Violation em nos null ou ausentes.
• ZV.Core.Errors.pas — erro tipado TZVError com HTTP status, flag Retryable e payload bruto.
• ZV.Http.Client.pas — transporte IZVHttpTransport sobre WinHTTP (System.Net.HttpClient) com TLS 1.2/1.3, envio nativo de certificado PFX/A1 (SetClientCertificate) e selecao inteligente por ClientCertHint (Serial/Subject/CertName/Issuer).
• ZV.Http.OAuth.pas — gerenciador TZVOAuthTokenManager thread-safe com cache em memoria, margem preventiva de expiracao e invalidacao automatica em HTTP 401.
• ZV.Webhook.HMAC.pas e ZV.Webhook.Idempotency.pas — verificacao tempo-constante HMAC-SHA256 (Mercado Pago), SHA-256 raw body (PagBank x-authenticity-token), token Asaas e guarda anti-replay.
• ZV.Banking.Contracts.pas e ZV.Banking.EMVCo.pas — contratos IZVPixProvider + IZVPixLifecycleProvider e motor EMVCo offline.
• DelphiZXIngQRCode.pas + ZV.Core.QRCode.pas — gerador QR 100% Pascal Apache 2.0.

2. Camada Pix Multi-Banco (src/Source):

• ZV.Pix.BacenV2.pas — engine parametrizado BACEN Pix API v2 para BB, Inter, Sicoob, Sicredi, Itau, Bradesco, Santander e Efi Bank com retry automatico de token OAuth2 em HTTP 401.
• ZV.Pix.PagBank.pas, ZV.Pix.MercadoPago.pas, ZV.Pix.Asaas.pas, ZV.Pix.Efi.pas.
• ZV.Pix.Facade.pas — fachada TZVPixManager com fabricas tipadas (ForBancoDoBrasil, ForBancoInter, ForSicoob, ForSicredi, ForItau, ForBradesco, ForSantander, ForEfiBank, ForPagBank, ForMercadoPago, ForAsaas, ForBankConfig) e metodos de ciclo completo (CreateCharge, QueryCharge, CancelCharge, RefundCharge, QueryPixByEndToEndId).
• ZV.Pix.VclRender.pas — renderizacao VCL isolada em RAM sem escrita temporaria em disco.

Guia de Instalacao — ZaptVupt Delphi Pix SDK (v2.1.0)

Requisitos de Ambiente

• Delphi: 10.4 Sydney, 11 Alexandria ou 12 Athens (Professional, Enterprise ou Architect).
• Plataformas suportadas: Win32 e Win64.
• Sistema Operacional: Windows 10, Windows 11 ou Windows Server 2016/2019/2022/2025.
• Dependencias externas: Nenhuma DLL externa requerida (utiliza WinHTTP nativo via System.Net.HttpClient).

Metodo 1: Integracao Direta por Search Path (Recomendado para CI/CD e ERPs)

1. Extraia o pacote licenciado em uma pasta de bibliotecas do seu projeto, por exemplo:

C:\Dev\Libs\ZV_Delphi_PIX_SDK\

2. No seu projeto Delphi (Project -> Options -> Delphi Compiler -> Search path), adicione:

• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Source
• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Vendor_ZVCore\src\Core
• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Vendor_ZVCore\src\Http
• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Vendor_ZVCore\src\Webhook
• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Vendor_ZVCore\src\Banking
• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Vendor_ZVCore\src\Adapters

3. Em Include path, adicione:

• C:\Dev\Libs\ZV_Delphi_PIX_SDK\src\Vendor_ZVCore\src\Adapters

4. Declare no uses da sua unit:

• Sem UI (servicos/PDV headless): ZV.Core.Types, ZV.Banking.Contracts, ZV.Pix.BacenV2, ZV.Pix.Facade
• Com tela VCL: adicione ZV.Pix.VclRender para desenhar TBitmap ou TImage.

Configuracao mTLS para Bancos Nacionais (BB, Inter, Sicoob, Sicredi, Itau, Bradesco, Santander, Efi)

Voce pode fornecer o certificado PJ A1 de duas formas sem instalar OpenSSL externo:

1. Arquivo .pfx / .p12 direto: informe ACertPath := 'C:\Certs\seu_banco.pfx' e ACertPassword := 'senha'. O motor utiliza IHTTPRequest.SetClientCertificate nativo do WinHTTP.

2. Windows Certificate Store: deixe ACertPath vazio e informe ACertHint (parte do CN/Subject, Serial Number ou Emissor). O evento OnNeedClientCertificate localiza o certificado valido automaticamente.

Metodo 2: Compilacao via Pacotes (ZV.PixSDK.groupproj)

1. Abra src\Packages\ZV.PixSDK.groupproj na IDE do Delphi 12.

2. Compile na ordem do Project Group para Win32 e Win64:

• ZV.Core.dpk
• ZV.Http.dpk
• ZV.Webhook.dpk
• ZV.Banking.dpk
• ZV.PixSDK.D12.dpk

Execucao da Demo e Testes Multi-Banco

1. Inicie o simulador local Multi-Banco (11 PSPs/Bancos):

python demo\seed_mock_server.py --port 18088

2. Compile e execute:

• Console headless (aceita modo offline, mp, asaas, pagbank, bb, inter, sicoob, sicredi, itau, bradesco, santander, efi): demo\ZV_PixDemo.dpr
• Aplicacao VCL desktop: demo\ZV_PixDemo_VCL.dpr

3. Execute a suite automatizada Win32/Win64:

tests\ZV_Pix_Tests.dpr

Referencia de API — ZaptVupt Delphi Pix SDK (v2.1.0)

Contratos Centrais (ZV.Banking.Contracts)

• IZVPixProvider
• function GetCapabilities: TZVProviderCapabilities;
• function CreateDynamicCharge(const ARequest: TZVPixChargeRequest): TZVPixChargeResponse;
• function QueryCharge(const AChargeId: string): TZVPixStatusResponse;
• IZVPixLifecycleProvider = interface(IZVPixProvider)
• function CancelCharge(const AChargeId: string): TZVPixCancelResponse;
• function RefundCharge(const ARequest: TZVPixRefundRequest): TZVPixRefundResponse;
• function QueryPixByEndToEndId(const AEndToEndId: string): TZVPixStatusResponse;

Fabrica Tipada TZVPixManager (ZV.Pix.Facade)

• Bancos BACEN v2 (ZV.Pix.BacenV2):
• TZVPixManager.ForBancoDoBrasil(ClientId, ClientSecret, AppKey, PixKey, Env, CertPath, CertPassword, CertHint, BaseUrlOverride)
• TZVPixManager.ForBancoInter(ClientId, ClientSecret, PixKey, Env, AccountNumber, CertPath, CertPassword, CertHint, BaseUrlOverride)
• TZVPixManager.ForSicoob(ClientId, PixKey, Env, CertPath, CertPassword, CertHint, BaseUrlOverride, nil, ClientSecret)
• TZVPixManager.ForSicredi(ClientId, ClientSecret, PixKey, Env, CertPath, CertPassword, CertHint, BaseUrlOverride)
• TZVPixManager.ForItau(ClientId, ClientSecret, ApiKey, PixKey, Env, CertPath, CertPassword, CertHint, BaseUrlOverride)
• TZVPixManager.ForBradesco(ClientId, ClientSecret, PixKey, Env, CertPath, CertPassword, CertHint, BaseUrlOverride)
• TZVPixManager.ForSantander(ClientId, ClientSecret, PixKey, Env, CertPath, CertPassword, CertHint, BaseUrlOverride)
• TZVPixManager.ForEfiBank(ClientId, ClientSecret, PixKey, Env, CertHint, BaseUrlOverride, nil, CertPath, CertPassword)
• TZVPixManager.ForBankConfig(Config: TZVBacenBankConfig) (controle granular de Scope, OAuthUrlOverride, BaseUrlOverride, ClientCertPath, ClientCertHint).
• PSPs Sem mTLS:
• TZVPixManager.ForPagBank(BearerToken, Env, BaseUrlOverride) (POST /orders, GET /orders/{id}, POST /charges/{id}/cancel, VerifyPagBankWebhook).
• TZVPixManager.ForMercadoPago(AccessToken, Env, BaseUrlOverride) (POST /v1/payments, GET /v1/payments/{id}, PUT cancelled, POST /refunds, VerifyMercadoPagoWebhook).
• TZVPixManager.ForAsaas(ApiKey, Env, BaseUrlOverride) (/customers -> /payments -> /pixQrCode, DELETE, POST /refund, VerifyAsaasWebhook).

Exemplo 1: Banco do Brasil Pix v2 (OAuth2 + AppKey + mTLS PFX)

var
  Mgr: TZVPixManager;
  Req: TZVPixChargeRequest;
  Resp: TZVPixChargeResponse;
  RefResp: TZVPixRefundResponse;
begin
  Mgr := TZVPixManager.ForBancoDoBrasil(
    BBClientId,
    BBClientSecret,
    BBDevAppKey,
    '12345678000195',
    tzvProduction,
    'C:\Certs\empresa_a1.pfx',
    'SenhaCertificado'
  );
  try
    Req := TZVPixChargeRequest.Create(
      249.90,
      'Fatura #9012',
      'Cliente Corporativo',
      'financeiro@cliente.com.br',
      '28940174000153',
      dtCNPJ
    );
    Resp := Mgr.CreateCharge(Req);
    if Resp.Success then
      MemoBRCode.Text := Resp.CopyPasteBRCode;

    // Estorno total ou parcial direto via TxId ou EndToEndId
    // RefResp := Mgr.RefundCharge(TZVPixRefundRequest.Create(Resp.TxId, 249.90));
  finally
    Mgr.Free;
  end;
end;

Exemplo 2: Banco Inter / Sicoob / Itau via Configuracao Unificada

var
  Cfg: TZVBacenBankConfig;
  Mgr: TZVPixManager;
begin
  Cfg := TZVBacenBankConfig.Create(bbBancoInter, ClientId, ClientSecret, ChavePix, tzvProduction);
  Cfg.AccountNumber := '12345678'; // Header x-conta-corrente
  Cfg.ClientCertPath := 'C:\Certs\inter_a1.pfx';
  Cfg.ClientCertPassword := 'SenhaA1';
  Mgr := TZVPixManager.ForBankConfig(Cfg);
  try
    // Mgr.CreateCharge(...) / Mgr.QueryCharge(...) / Mgr.CancelCharge(...) / Mgr.RefundCharge(...)
  finally
    Mgr.Free;
  end;
end;

Matriz de Homologacao Honesta — ZaptVupt Delphi Pix SDK (v2.1.0)

> Nota de transparencia: Nenhum banco tradicional ou PSP nesta tabela simula falso PRODUCTION_VERIFIED em mock local. Todos os 11 motores online possuem implementacao HTTP/OAuth2/JSON/mTLS real validada em Win32 e Win64 contra simuladores fiéis de cada contrato (MOCK_CONTRACT_VERIFIED), aguardando apenas as credenciais PJ e certificado A1 do ambiente do cliente para execucao em producao.

SBOM & Auditoria de Dependencias (Clean-Room v2.1.0)

Este produto foi construido e auditado sob o protocolo Clean-Room ZaptVupt Engenharia. Nenhuma biblioteca comercial de terceiros ou DLL proprietaria e obrigatoria para compilar os fontes ou executar o binario final.

Itens Explicitamente Removidos vs Codigos Legados

• Removida dependencia obrigatoria de DevExpress VCL (cxButtons, dxSkins, ExemploPix.dxsettings).
• Removida dependencia de FastReport (frxClass, RelQrCodePix.fr3).
• Removidas DLLs de hardware/terceiros sem licenca de redistribuicao (mp2032.dll, SiUSBXp.dll, inpout32.dll, decryptFile.dll).
• Removido acoplamento a DLLs obsoletas do OpenSSL 1.0 (libeay32.dll, ssleay32.dll) e Pkg.Json.DTO.

Changelog — ZaptVupt Delphi Pix SDK

[2.1.0] — Release Multi-Banco BACEN v2, OAuth2 Cache & Ciclo Completo

• Implementado motor BACEN Pix API v2 parametrizado (ZV.Pix.BacenV2.pas) com suporte completo a Banco do Brasil (gw-dev-app-key), Banco Inter (x-conta-corrente), Sicoob (OpenID Connect + client_id), Sicredi, Itau (STS OAuth2 + x-itau-apikey + x-itau-correlationID), Bradesco, Santander (client_id) e Efi Bank (omBasicJson).
• Implementado TZVPagBankPixProvider (ZV.Pix.PagBank.pas) para PagBank / PagSeguro Orders Pix (/orders, /orders/{id}, /charges/{id}/cancel) e verificacao SHA-256 x-authenticity-token em TZVWebhookVerifier.
• Adicionado gerenciador TZVOAuthTokenManager (ZV.Http.OAuth.pas) thread-safe com cache de tokens em memoria, renovacao preventiva e invalidacao/retry automatico em HTTP 401.
• Habilitado suporte nativo a certificados mTLS .pfx/.p12 (ClientCertPath + ClientCertPassword) e selecao inteligente via ClientCertHint no OnNeedClientCertificate do WinHTTP sem OpenSSL externo.
• Estendido ciclo de vida completo via IZVPixLifecycleProvider (CancelCharge, RefundCharge e QueryPixByEndToEndId) nos 8 bancos BACEN, PagBank, Mercado Pago e Asaas.
• Atualizada demo CLI/VCL e simulador seed_mock_server.py cobrindo todas as 11 integracoes online + EMVCo offline.

[2.0.0] — Release Clean-Room Multi-PSP

• Reescrita completa sob namespace ZV.* desacoplada de formularios VCL, DevExpress, FastReport e DLLs terceiras.
• Implementado TZVMercadoPagoPixProvider, TZVAsaasPixProvider, motor offline TZVEMVCoPix CRC16-CCITT e renderizador VCL em RAM ZV.Pix.VclRender.

[1.0.0] — Legado Mercado Pago (Migrado)

• Versao historica monolitica baseada em uAPIPixMercadoPago.pas.