🎫 BoletoSDK

Brazilian bank slip (boleto) & CNAB processing library with type safety, validation, and ready-to-render assets.

Parse, generate, and validate CNAB 240/400 files with consistent APIs.

🌟 Highlights

• CNAB 240/400 parsing, generation, and validation
• Boleto assets: barcode, PIX QR, HTML/PDF (pt-BR labels)
• Bank constants, layout validation, and robust tests

🧾 Boleto Generation

import {
  buildBoletoHtml,
  generateBarcode,
  generateBoletoEmail,
  generateBoletoPdfBuffer,
  generatePixQRCode,
} from '@linkiez/boleto-sdk';

const barcode = generateBarcode({
  bankCode: '341',
  currencyCode: '9',
  dueDate: new Date('2026-02-28'),
  amount: 150.5,
  freeField: '1234567890123456789012345',
});

const pix = generatePixQRCode({
  key: '12345678000195',
  amount: 150.5,
  merchantName: 'ACME CORP',
  merchantCity: 'SAO PAULO',
  transactionId: 'INV001',
});

const boletoData = {
  beneficiary: {
    name: 'ACME CORP',
    document: '12345678000195',
    address: 'Avenida 1, 1000',
  },
  payer: {
    name: 'Joao da Silva',
    document: '12345678901',
    address: 'Rua 2, 200',
  },
  payment: {
    documentNumber: 'DOC-001',
    ourNumber: '12345678',
    amount: 150.5,
    dueDate: new Date('2026-02-28'),
    barcode: barcode.barcode,
    digitableLine: barcode.digitableLine,
    pix: { payload: pix.payload },
  },
  bank: { code: '341', name: 'ITAU UNIBANCO SA' },
};

const html = buildBoletoHtml(boletoData, { layout: 'detailed' });
const pdf = await generateBoletoPdfBuffer(boletoData, { includePixQr: true });

🚀 Quick Start

npm install @linkiez/boleto-sdk

import { parseCnab, generateCnab } from '@linkiez/boleto-sdk';

const parsed = parseCnab(content);
const output = generateCnab(parsed);

import {
  generateBarcode,
  generatePixQRCode,
  generateBoletoPdfBuffer,
} from '@linkiez/boleto-sdk';

const { barcode, digitableLine } = generateBarcode({
  bankCode: '341',
  dueDate: new Date('2025-02-10'),
  amount: 150.5,
  freeField: '1234567890123456789012345',
});

const pix = generatePixQRCode({
  key: '12345678000195',
  amount: 150.5,
  merchantName: 'ACME CORP',
  merchantCity: 'SAO PAULO',
  transactionId: 'INV001',
});

const pdf = await generateBoletoPdfBuffer({
  beneficiary: { name: 'ACME CORP', document: '12345678000195', address: 'Avenida 1' },
  payer: { name: 'Joao da Silva', document: '12345678901', address: 'Rua 2' },
  payment: {
    documentNumber: 'DOC-001',
    ourNumber: '12345678',
    amount: 150.5,
    dueDate: new Date('2025-02-10'),
    barcode,
    digitableLine,
    pix: { payload: pix.payload },
  },
  bank: { code: '341', name: 'ITAU UNIBANCO SA' },
});

🏦 Bank Adapters (Itaú)

import { createItauAdapter } from '@linkiez/boleto-sdk';

const adapter = createItauAdapter();

adapter.assertSupportedWallet('109');

const ourNumber = adapter.buildOurNumber('12345678');
// { baseNumber: '12345678', checkDigit: 2, formatted: '123456782' }

For complete examples, see Adapters Guide.

📚 Documentation

Core

• API Reference
• CNAB240 Guide
• CNAB400 Usage Guide
• Boleto Generation Guide
• Adapters Guide
• Examples

Specs and Validation

• CNAB240 FEBRABAN Spec
• CNAB400 Positions Validation
• Segment Positions Validation
• Business Rules
• Business Rules Sources

Supporting Docs

• Bank Differences
• FAQ
• Migration
• SonarQube
• CNAB400 Bank Samples

Project

• Architecture
• Testing
• Contributing
• Roadmap

🛠️ Development

See CONTRIBUTING.md and TESTING.md for setup, workflows, and conventions.

📜 License

APACHE. See LICENSE.

🔗 Links

• NPM Package
• Report Issues