brcobranca Ruby Gem

The Brcobranca gem is organized into several functional modules:

• Brcobranca::Boleto: Contains classes for different Brazilian banks (e.g., BancoBrasil, Itau, Bradesco, Santander, Caixa, etc.) and templates (e.g., Rghost, RghostCarne, RghostBolepix).
• Brcobranca::Retorno: Handles bank return files (e.g., RetornoCbr643, RetornoCnab240, RetornoCnab400).
• Brcobranca::Remessa: Generates remittance files for payments and Pix, supporting various formats like Cnab400, Cnab240, and Cnab444.
• Brcobranca::Util: Provides utility classes like Empresa and Errors.

The Rghost2 module implements method_missing to allow calling dynamic methods for any valid format supported by rghost. Any method starting with to_ will be interpreted as a request to generate the boleto in that specific format.

Example:

• boleto.to_pdf is equivalent to boleto.to(:pdf)
• boleto.to_png is equivalent to boleto.to(:png)

# Example of dynamic method usage
@boleto.to_pdf #=> boleto generated in pdf format
@boleto.to_gif #=> boleto generated in gif format

When generating boletos or remessa files, the gem may raise specific exceptions if the provided data is invalid. You can rescue these exceptions to access the validation errors.

• Brcobranca::BoletoInvalido: Raised when data provided for a boleto is invalid. The exception message contains the joined error messages.
• Brcobranca::RemessaInvalida: Raised when data provided for a remessa file is invalid.

To access the specific error messages, you can rescue the exception and call .errors on the exception object (which internally uses the object's validation messages).

# For Boletos
begin
  # code to generate boleto
rescue Brcobranca::BoletoInvalido => invalido
  puts invalido.errors
end

# For Remessa
begin
  # code to generate remessa
rescue Brcobranca::RemessaInvalida => invalido
  puts invalido.errors
end

You can customize the global configuration of the Brcobranca gem using the setup block. This is typically done in a Rails initializer or a configuration file.

Available configuration options in Brcobranca::Configuration:

• gerador: The generator used (Default: :rghost).
• formato: The file format for the generated boleto (Default: :pdf). Supported formats depend on the generator (e.g., :gif).
• resolucao: The pixel resolution of the generated file (Default: 150).
• external_encoding: The encoding for text sent to GhostScript (Default: 'ascii-8bit'). Using 'ascii-8bit' helps avoid issues with accents and special characters.

Brcobranca.setup do |config|
  config.formato = :gif
  config.resolucao = 300
end

When integrating with banks, you need to know which CNAB formats (e.g., 400, 240, 444) are supported for sending files (Remessa) and receiving files (Retorno).

| Bank | Retorno | Remessa |
| ----------------- | ------------------- | --------------------- |
| Banco do Brasil | 400 (ou CBR643) | 400 (ou CBR641) e 240 |
| Banco do Nordeste | 400 | 400 |
| Banco de Brasília | 400 | 400 |
| Banestes | Não | Não |
| Banrisul | 400 | 400 |
| Bradesco | 400 | 400 |
| Caixa | 240 | 240 |
| Citibank | Não | 400 |
| HSBC | Não | Não |
| Itaú | 400 | 400 e 444 |
| Santander | 400 e 240 | 400 e 240 |
| Sicoob | 240 | 400 e 240 |
| Sicredi | 240 | 240 |
| UNICRED | 400 | 400 e 240 |
| AILOS | 240 | 240 |
| CREDISIS | 400 | 400 |

The Rghost template module implements method_missing to provide convenient dynamic methods for every supported format. Instead of calling .to(:format), you can call .to_format directly on a boleto instance.

Example:

• boleto.to_pdf generates a PDF.
• boleto.to_jpg generates a JPG.
• boleto.to_png generates a PNG.

# Using dynamic methods for convenience
pdf_stream = boleto.to_pdf
jpg_stream = boleto.to_jpg

The codigo_barras_segunda_parte method returns the 25-character numeric string required for the second part of the Ailos barcode. It is composed of the convenio, the nosso_numero_boleto, and the carteira.

# Returns a 25-character numeric string
boleto.codigo_barras_segunda_parte