ZaptVupt Delphi Boleto & CNAB 240/400 SDK - FEBRABAN Multi-Banco & Boleto Hibrido Pix

ZaptVupt Delphi Boleto & CNAB 240/400 SDK (v1.0.0)

Engine Clean-Room Multi-Banco para emissao de boletos FEBRABAN (codigo de barras 44 digitos + linha digitavel 47 digitos com rollover pos-22/02/2025), arquivos CNAB 240 e CNAB 400 (remessa e retorno), registro/consulta/baixa online via API OAuth2 + mTLS com Boleto Hibrido Pix (EMVCo), renderizacao vetorial ITF-25 SVG/Bitmap e Ficha de Compensacao HTML5 imprimivel — 100% em Object Pascal nativo para Delphi 10.4 Sydney, 11 Alexandria e 12 Athens (Win32 e Win64).

Bancos e PSPs Cobertos

1. Motor Offline FEBRABAN & CNAB 240/400 (8 Bancos Nacionais)

• 001 — Banco do Brasil (ForBancoDoBrasil): Carteira 17/18, convenio 6/7 digitos, CNAB 240 & CNAB 400.
• 033 — Santander (ForSantander): Carteira 101/102, Mod11 Nosso Numero 13 digitos, CNAB 240 & CNAB 400.
• 104 — Caixa Economica Federal (ForCaixa): SIGCB Carteira 14, Campo Livre 25 posicoes com DVs Mod11, CNAB 240 & CNAB 400.
• 237 — Bradesco (ForBradesco): Carteira 09/19, Mod11 Base 7 Nosso Numero (P para resto 1), CNAB 240 & CNAB 400.
• 341 — Itau Unibanco (ForItau): Carteira 109/112, Mod10 DAC agencia/conta/carteira/nosso numero, CNAB 240 & CNAB 400.
• 077 — Banco Inter (ForBancoInter): Carteira 112, Campo Livre estruturado + CNAB 240/400 e Bolepix API v3.
• 756 — Sicoob (ForSicoob): Carteira 1, coeficientes especiais 3-1-9-7 para DV Nosso Numero, CNAB 240 & CNAB 400.
• 748 — Sicredi (ForSicredi): Carteira A/1, Campo Livre com posto/byte geracao + Mod11, CNAB 240 & CNAB 400.

2. Registro Online & Boleto Hibrido Pix (9 Bancos / PSPs)

• Banco do Brasil Cobrancas v2 (OAuth2 Basic Form + gw-dev-app-key + mTLS)
• Banco Inter Bolepix v3 (OAuth2 Body Form + x-conta-corrente + mTLS)
• Sicoob Cobranca Bancaria v3 (OpenID Connect + client_id + mTLS)
• Sicredi Cobranca v1 (OAuth2 Basic Form + mTLS)
• Itau Bolecode v2 (STS OAuth2 + x-itau-apikey + x-itau-correlationID + mTLS)
• Bradesco Boleto Hibrido v1 (OAuth2 Basic Form + mTLS)
• Santander Collection v2 (OAuth2 Body Form + client_id + mTLS)
• Efi Bank Bolix v1 (OAuth2 Basic JSON + mTLS)
• Asaas Boleto v3 (API Key access_token)

3. Engine Visual Clean-Room (Sem FastReport/DevExpress)

• ITF-25 Vector SVG (RenderITF25Svg): codigo de barras intercalado 2 de 5 conforme padrao FEBRABAN (start NNNN, stop WNN).
• ITF-25 + Ficha em TBitmap (RenderBoletoBitmap): renderizacao direta em RAM para formularios VCL sem arquivos temporarios.
• QR Code Pix Hibrido (RenderPixQrSvg): geracao pura em Pascal com DelphiZXIngQRCode.
• Ficha de Compensacao HTML5 (RenderBoletoHtml): layout pronto para impressao A4 / Save-as-PDF no navegador ou WebView2.

Arquitetura Modular

1. Vendor_ZVCore (ZV.Core.*, ZV.Http.*, ZV.Banking.Febraban, ZV.Banking.EMVCo, ZV.Core.QRCode): base compartilha FEBRABAN Mod10/Mod11/Rollover 2025, HTTP WinHTTP com mTLS, OAuth2 cache thread-safe e QR Code Apache 2.0.

2. ZV.Boleto.Types: enumeracoes, configuracao TZVCedenteConfig, titulo TZVBoletoTitle e construtor posicional TZVCnabLineBuilder (240 / 400 posicoes ASCII sem acentuacao).

3. ZV.Boleto.BankProfiles: calculo de DV do Nosso Numero e Campo Livre 25 posicoes de cada banco + montagem de EMVCo Hibrido Pix local.

4. ZV.Boleto.Cnab240 & ZV.Boleto.Cnab400: geracao de Remessa e leitura estruturada de Retorno (ParseCnab240Retorno, ParseCnab400Retorno).

5. ZV.Boleto.ApiEngine: registro, consulta e baixa/cancelamento online nas 9 APIs suportadas com renovacao automatica em HTTP 401.

6. ZV.Boleto.Renderer & ZV.Boleto.Facade: fachada unica TZVBoletoManager.

Guia de Instalacao — ZaptVupt Delphi Boleto & CNAB 240/400 SDK (v1.0.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: Zero DLLs externas obrigatorias (System.Net.HttpClient / WinHTTP nativo; zero OpenSSL/FastReport/DevExpress).

Metodo 1: Search Path Direto (Recomendado para ERPs e CI/CD)

1. Descompacte o pacote em uma pasta curta, por exemplo:

C:\Dev\Libs\ZV_Delphi_Boleto_CNAB_SDK\

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

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

3. Em Include path, adicione:

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

4. No uses das units da sua aplicacao, inclua:

ZV.Core.Types, ZV.Banking.Febraban, ZV.Boleto.Types, ZV.Boleto.Facade

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

1. Abra src\Packages\ZV.BoletoSDK.groupproj no Delphi 12.

2. Compile na ordem para Win32 e Win64:

• ZV.Core.dpk
• ZV.Http.dpk
• ZV.Banking.dpk
• ZV.BoletoSDK.D12.dpk

Executando o Simulador Multi-Banco & Demos Localmente

1. Inicie o servidor mock deterministico na porta 18920:

python demo\seed_mock_server.py --port 18920

2. Compile e execute a demo CLI (aceita modos offline, api-bb, api-inter, api-sicoob, api-sicredi, api-itau, api-bradesco, api-santander, api-efi, api-asaas):

demo\ZV_BoletoDemo.dpr

3. Compile e execute a demo VCL desktop (visualizacao do boleto em TBitmap, CNAB 240/400 e exportacao HTML):

demo\ZV_BoletoDemo_VCL.dpr

4. Rode a suite completa automatizada (Win32 e Win64 com deteccao de leaks):

tests\ZV_Boleto_Tests.dpr

Referencia de API — ZaptVupt Delphi Boleto & CNAB SDK (v1.0.0)

1. Nucleo FEBRABAN (ZV.Banking.Febraban.TZVFebrabanHelpers)

• CalcDueDateFactor(ADueDate: TDateTime): Integer — Calcula o fator de vencimento FEBRABAN de 4 digitos com rollover automatico apos 22/02/2025 (1000..9999).
• CalcMod10(const ADigits: string): Integer — Modulo 10 oficial dos campos da Linha Digitavel.
• CalcMod11BarcodeDAC(const ADigits43: string): Integer — Digito verificador geral (DAC na 5a posicao do codigo de barras; restos 0/1/10 retornam 1).
• BuildBarcode44(const ABankCode3, ACurrency1: string; AFactor4: Integer; AAmountBRL: Double; const AFreeField25: string): string — Monta codigo de barras de 44 digitos valido.
• ValidateBarcode44(const ABarcode44: string): Boolean — Valida tamanho, digitos e DAC.
• BuildLinhaDigitavelFromBarcode(const ABarcode44: string; AFormatted: Boolean = False): string — Converte codigo 44d em Linha Digitavel de 47 digitos (com ou sem pontuacao).
• ExtractBarcodeFromLinhaDigitavel(const ALinha47: string): string — Conversao reversa 47d -> 44d validada.
• SanitizeFebrabanAscii(const AText: string): string — Remove acentos (usando tabela Unicode segura independente de codepage) e converte para ASCII caixa alta seguro para remessas CNAB.

2. Fachada Principal (ZV.Boleto.Facade.TZVBoletoManager)

Fabricas Tipadas por Banco / PSP

• TZVBoletoManager.ForBancoDoBrasil(...)
• TZVBoletoManager.ForSantander(...)
• TZVBoletoManager.ForCaixa(...)
• TZVBoletoManager.ForBradesco(...)
• TZVBoletoManager.ForItau(...)
• TZVBoletoManager.ForBancoInter(...)
• TZVBoletoManager.ForSicoob(...)
• TZVBoletoManager.ForSicredi(...)
• TZVBoletoManager.ForEfiBank(...)
• TZVBoletoManager.ForAsaas(...)
• TZVBoletoManager.ForBankConfig(ACedente, ATransport)

Operacoes Offline FEBRABAN & CNAB

• GetBankProfile: TZVBoletoBankProfile
• PrepareTitle(var ATitle: TZVBoletoTitle) — Calcula Nosso Numero + DV, Campo Livre 25 posicoes, Codigo de Barras 44d, Linha Digitavel 47d e QR Hibrido Pix local quando UseHybridPix = True.
• GenerateCnab240Remessa(const ATitles: TArray<TZVBoletoTitle>; AIncludeSegmentR: Boolean = True): string
• SaveCnab240Remessa(const ATitles: TArray<TZVBoletoTitle>; const AFilePath: string; AIncludeSegmentR: Boolean = True)
• ParseCnab240Retorno(const AContent: string): TZVCnabReturnSummary
• GenerateCnab400Remessa(const ATitles: TArray<TZVBoletoTitle>): string
• SaveCnab400Remessa(const ATitles: TArray<TZVBoletoTitle>; const AFilePath: string)
• ParseCnab400Retorno(const AContent: string): TZVCnabReturnSummary

Operacoes Online API (OAuth2 Cache + Retry 401 + mTLS Nativo)

• RegisterOnline(var ATitle: TZVBoletoTitle): TZVBoletoRegisterResponse
• QueryOnline(const AExternalIdOrNosso: string): TZVBoletoQueryResponse
• CancelOnline(const AExternalIdOrNosso: string): TZVBoletoCancelResponse

Renderizacao Visual Clean-Room

• RenderITF25Svg(const ABarcode44: string; AHeightPx: Integer = 58): string
• RenderPixQrSvg(const APixPayload: string; APixelSize: Integer = 4): string
• RenderBoletoHtml(const ATitle: TZVBoletoTitle): string
• RenderBoletoBitmap(const ATitle: TZVBoletoTitle; ATarget: TBitmap)

Matriz de Homologacao Honesta — ZaptVupt Delphi Boleto & CNAB SDK (v1.0.0)

> Nota de transparencia: Todos os calculos offline (FEBRABAN, Modulo 10/11, Fator Pos-2025, CNAB 240/400, ITF-25 e HTML) operam 100% em producao local (PRODUCTION_READY_VERIFIED). Todas as integracoes online de API possuem cliente HTTP/OAuth2/mTLS completo validado em Win32 e Win64 contra simuladores fiéis dos contratos oficiais (MOCK_CONTRACT_VERIFIED), aguardando credenciais PJ do comprador para emissao contra ambiente real dos bancos.

SBOM & Auditoria de Dependencias (Clean-Room v1.0.0)

Este pacote segue o protocolo Clean-Room ZaptVupt Engenharia. Compila do zero em Win32 e Win64 usando exclusivamente RTL/VCL nativa da Embarcadero e fontes autorais auditados.

Dependencias Explicitamente Excluidas

• Zero dependencia de FortesReport (RLReport, RLBoleto) ou FastReport (frxClass, .fr3).
• Zero dependencia de DevExpress VCL (cxGrid, cxButtons, dxSkins).
• Zero dependencia de suites monoliticas de terceiros (ACBrBoleto, Indy legado, libeay32.dll, ssleay32.dll).

Changelog — ZaptVupt Delphi Boleto & CNAB 240/400 SDK

v1.0.0 (2026-11-13)

• Lancamento inicial Clean-Room do SDK Multi-Banco de Boletos e CNAB para Delphi 10.4 / 11 / 12 (Win32 e Win64).
• Adicionada unit compartilhada ZV.Banking.Febraban ao Vendor_ZVCore com Modulo 10/11, DAC 44 digitos, conversao reversa 44<->47 digitos e regra obrigatoria de Fator de Vencimento FEBRABAN pos-22/02/2025 (1000..9999).
• Adicionado suporte aos 8 maiores bancos brasileiros no motor FEBRABAN + CNAB 240 & 400 (Banco do Brasil 001, Santander 033, Caixa 104, Bradesco 237, Itau 341, Banco Inter 077, Sicoob 756, Sicredi 748).
• Adicionado motor online OAuth2 Cache + Retry HTTP 401 + mTLS A1/Store para 9 bancos/PSPs (BB Cobrancas v2, Inter Bolepix v3, Sicoob v3, Sicredi v1, Itau Bolecode v2, Bradesco Hibrido v1, Santander v2, Efi Bank Bolix v1 e Asaas v3).
• Adicionado renderizador nativo ITF-25 vetorial SVG, TBitmap VCL em RAM, QR Code Pix Hibrido e Ficha de Compensacao HTML5 imprimivel.
• Incluido simulador deterministico multi-banco demo/seed_mock_server.py, demo CLI, demo VCL e suite automatizada completa.