PIX BR Code Parser

Uma biblioteca Rust para análise e validação de códigos QR PIX (BR Code) brasileiros seguindo o padrão EMV QRCPS.

Características

• ✅ Análise de códigos QR PIX estáticos e dinâmicos
• ✅ Validação de conformidade com EMV QRCPS
• ✅ Validação de checksum CRC16
• ✅ API ergonômica com structs tipadas
• ✅ Suporte opcional ao serde para serialização
• ✅ Análise zero-allocation para aplicações críticas de performance
• ✅ Geração de códigos QR PIX
• ✅ Classificação automática de tipos de chave PIX

Instalação

Adicione ao seu Cargo.toml:

[dependencies]
pix-brcode-parser = "0.1.0"

# Para suporte a serialização
pix-brcode-parser = { version = "0.1.0", features = ["serde"] }

Uso Rápido

Analisando um Código QR PIX

use pix_brcode_parser::{parse_brcode, BRCodeError};

fn main() {
    let qr_string = "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***630436D9";
    
    match parse_brcode(qr_string) {
        Ok(brcode) => {
            println!("✅ Código PIX válido!");
            println!("Chave PIX: {}", brcode.merchant_account_info.pix_key);
            println!("Tipo da Chave: {:?}", brcode.pix_key_type());
            println!("Comerciante: {}", brcode.merchant_name);
            println!("Cidade: {}", brcode.merchant_city);
            
            if let Some(amount) = &brcode.transaction_amount {
                println!("Valor: R$ {}", amount);
            } else {
                println!("Valor: A ser definido pelo usuário");
            }
            
            println!("Tipo: {}", if brcode.is_static() { "Estático" } else { "Dinâmico" });
        }
        Err(e) => {
            eprintln!("❌ Erro ao analisar código PIX: {}", e);
        }
    }
}

Gerando um Código QR PIX

use pix_brcode_parser::{BRCode, MerchantAccountInfo, generate_brcode};

fn main() {
    let brcode = BRCode {
        payload_format_indicator: "01".to_string(),
        point_of_initiation_method: Some("11".to_string()), // Estático
        merchant_account_info: MerchantAccountInfo {
            gui: "br.gov.bcb.pix".to_string(),
            pix_key: "user@example.com".to_string(),
            description: Some("Pagamento por serviços".to_string()),
            url: None,
        },
        merchant_category_code: "0000".to_string(),
        transaction_currency: "986".to_string(), // BRL
        transaction_amount: Some("25.50".to_string()),
        country_code: "BR".to_string(),
        merchant_name: "ACME CORP".to_string(),
        merchant_city: "SAO PAULO".to_string(),
        additional_data: None,
        crc16: String::new(), // Será calculado automaticamente
    };
    
    match generate_brcode(&brcode) {
        Ok(qr_string) => {
            println!("Código QR gerado: {}", qr_string);
        }
        Err(e) => {
            eprintln!("Erro ao gerar código: {}", e);
        }
    }
}

Exemplos de Códigos PIX

Código PIX Estático com Valor Fixo

// QR Code com valor predefinido de R$ 10,00
let static_qr = "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***630436D9";

let brcode = parse_brcode(static_qr).unwrap();
assert_eq!(brcode.transaction_amount, Some("10.00".to_string()));
assert_eq!(brcode.merchant_name, "FULANO DE TAL");
assert_eq!(brcode.merchant_city, "BRASILIA");

Diferentes Tipos de Chave PIX

use pix_brcode_parser::{parse_brcode, PixKeyType, classify_pix_key};

// Chave UUID
let uuid_key = "123e4567-e89b-12d3-a456-426614174000";
assert_eq!(classify_pix_key(uuid_key), PixKeyType::Uuid);

// Chave Email
let email_key = "usuario@exemplo.com";
assert_eq!(classify_pix_key(email_key), PixKeyType::Email);

// Chave Telefone
let phone_key = "+5511999999999";
assert_eq!(classify_pix_key(phone_key), PixKeyType::Phone);

// Chave CPF
let cpf_key = "12345678901";
assert_eq!(classify_pix_key(cpf_key), PixKeyType::Cpf);

// Chave CNPJ
let cnpj_key = "12345678000195";
assert_eq!(classify_pix_key(cnpj_key), PixKeyType::Cnpj);

Tratamento de Erros

use pix_brcode_parser::{parse_brcode, BRCodeError};

let invalid_qr = "codigo_invalido";

match parse_brcode(invalid_qr) {
    Ok(brcode) => println!("Código válido: {:?}", brcode),
    Err(e) => match e {
        BRCodeError::InvalidChecksum => {
            println!("Checksum inválido - código pode estar corrompido");
        }
        BRCodeError::InvalidGui(gui) => {
            println!("GUI inválido: esperado 'br.gov.bcb.pix', encontrado: {}", gui);
        }
        BRCodeError::MissingField(field) => {
            println!("Campo obrigatório ausente: {}", field);
        }
        BRCodeError::InvalidFormat(msg) => {
            println!("Formato inválido: {}", msg);
        }
        _ => {
            println!("Erro: {}", e);
        }
    }
}

Validação de Campos

use pix_brcode_parser::parse_brcode;

// Exemplo com nome do comerciante muito longo (máximo 25 caracteres)
let long_name_qr = "..."; // QR code com nome > 25 chars

match parse_brcode(long_name_qr) {
    Err(BRCodeError::FieldTooLong { tag, max_length, actual_length }) => {
        println!("Campo {} muito longo: máximo {}, atual {}", tag, max_length, actual_length);
    }
    _ => {}
}

Serialização com Serde (Feature Opcional)

#[cfg(feature = "serde")]
{
    use serde_json;
    
    let qr_string = "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***630436D9";
    let brcode = parse_brcode(qr_string).unwrap();
    
    // Serializar para JSON
    let json = serde_json::to_string(&brcode).unwrap();
    println!("JSON: {}", json);
    
    // Deserializar de JSON
    let brcode_from_json: BRCode = serde_json::from_str(&json).unwrap();
    assert_eq!(brcode, brcode_from_json);
}

Estrutura dos Dados

BRCode Principal

pub struct BRCode {
    pub payload_format_indicator: String,      // Sempre "01"
    pub point_of_initiation_method: Option<String>, // "11" = estático, "12" = dinâmico
    pub merchant_account_info: MerchantAccountInfo,
    pub merchant_category_code: String,        // Código da categoria do comerciante
    pub transaction_currency: String,          // "986" para BRL
    pub transaction_amount: Option<String>,    // Valor da transação
    pub country_code: String,                  // "BR"
    pub merchant_name: String,                 // Nome do comerciante (máx 25 chars)
    pub merchant_city: String,                 // Cidade (máx 15 chars)
    pub additional_data: Option<AdditionalData>,
    pub crc16: String,                        // Checksum CRC16
}

Informações da Conta PIX

pub struct MerchantAccountInfo {
    pub gui: String,                          // "br.gov.bcb.pix"
    pub pix_key: String,                      // Chave PIX
    pub description: Option<String>,          // Descrição opcional
    pub url: Option<String>,                  // URL para QR dinâmicos
}

Dados Adicionais

pub struct AdditionalData {
    pub bill_number: Option<String>,
    pub mobile_number: Option<String>,
    pub store_label: Option<String>,
    pub loyalty_number: Option<String>,
    pub reference_label: Option<String>,      // Etiqueta de referência
    pub customer_label: Option<String>,
    pub terminal_label: Option<String>,
    pub purpose_of_transaction: Option<String>,
    pub additional_consumer_data_request: Option<String>,
}

Validações Implementadas

• ✅ Checksum CRC16: Validação completa usando CRC-16/CCITT-FALSE
• ✅ GUI PIX: Deve ser "br.gov.bcb.pix"
• ✅ Código da Moeda: Deve ser "986" (Real Brasileiro)
• ✅ Código do País: Deve ser "BR"
• ✅ Indicador de Formato: Deve ser "01"
• ✅ Limites de Campo:
  • Nome do comerciante: máximo 25 caracteres
  • Cidade: máximo 15 caracteres
  • Etiqueta de referência: máximo 25 caracteres
• ✅ Formato da Chave PIX: Validação básica de caracteres

Executando os Exemplos

# Exemplo de análise
cargo run --example parse_pix_qr

# Exemplo de geração
cargo run --example generate_pix_qr

Executando os Testes

# Testes unitários
cargo test --lib

# Todos os testes
cargo test

# Com saída detalhada
cargo test -- --nocapture

Compatibilidade

• Rust: 1.70+
• Plataformas: Windows, Linux, macOS
• Arquiteturas: x86_64, ARM64

Licença

Dual licensed under MIT OR Apache-2.0.

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch para sua feature
3. Adicione testes para novas funcionalidades
4. Execute cargo test para garantir que tudo funciona
5. Envie um Pull Request

Recursos Úteis

• Manual BR Code - Banco Central
• EMV QR Code Specification
• PIX - Banco Central do Brasil

Esta biblioteca foi desenvolvida para facilitar a integração com o sistema PIX brasileiro, seguindo rigorosamente os padrões EMV QRCPS e as especificações do Banco Central do Brasil.