OpenSefaz

SDK Rust para integração com os sistemas da SEFAZ (NF-e, NFC-e, CT-e)

🚀 Visão Geral

OpenSefaz é um SDK completo escrito em Rust para facilitar a integração com os sistemas da SEFAZ, proporcionando:

• Segurança: Aproveita as garantias de segurança de memória do Rust
• Performance: Código otimizado e eficiente
• Confiabilidade: Sistema de tipos forte previne erros em tempo de compilação
• Facilidade de uso: API intuitiva e bem documentada

📦 Instalação

Adicione ao seu Cargo.toml:

[dependencies]
opensefaz-rs = "0.1"

Ou instale a CLI:

cargo install opensefaz-cli

🔧 Uso

Biblioteca

use opensefaz_rs::{Config, NfeClient, Certificado, Ambiente};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configurar cliente
    let config = Config::new(
        "99999999999999".to_string(), // CNPJ
        "SP".to_string(),              // UF
        Ambiente::Homologacao,
    );
    
    // Carregar certificado digital
    let certificado = Certificado::from_pem_file(
        "/caminho/certificado.pem",
        "senha"
    )?;
    
    // Criar cliente
    let client = NfeClient::new(config, certificado)?;
    
    // Consultar NF-e
    let resultado = client
        .consultar_por_chave("42150899999999999999550010000000011234567890")
        .await?;
    
    println!("Status: {:?}", resultado.status);
    println!("Protocolo: {:?}", resultado.protocolo);
    
    Ok(())
}

CLI

# Consultar NF-e
opensefaz --certificado ./cert.pem --senha 123456 --cnpj 99999999999999 consultar 42150899999999999999550010000000011234567890

# Verificar status do serviço
opensefaz --certificado ./cert.pem --senha 123456 --cnpj 99999999999999 status

# Validar XML
opensefaz validar nfe.xml

# Assinar XML
opensefaz --certificado ./cert.pem --senha 123456 --cnpj 99999999999999 assinar nfe.xml --saida nfe-assinada.xml

# Gerar chave de acesso
opensefaz gerar-chave --estado 42 --cnpj 99999999999999

# Formatar documentos
opensefaz formatar 12345678000199 --tipo cnpj

🏗️ Arquitetura do Projeto

opensefaz/
├── opensefaz-rs/      # SDK principal
│   ├── src/
│   │   ├── lib.rs         # Ponto de entrada
│   │   ├── error.rs       # Tipos de erro
│   │   ├── config.rs      # Configuração
│   │   ├── certificate.rs # Certificado digital
│   │   ├── nfe.rs         # Cliente NF-e
│   │   ├── types.rs       # Tipos de dados
│   │   └── utils.rs       # Utilitários
│   └── Cargo.toml
├── opensefaz-cli/     # Interface de linha de comando
│   ├── src/
│   │   └── main.rs
│   └── Cargo.toml
└── Cargo.toml         # Workspace

📚 Recursos Principais

Certificados Digitais

• Suporte a certificado A1 (PEM/PFX)
• Validação de validade
• Verificação de vencimento

NF-e (Nota Fiscal Eletrônica)

• Consulta por chave de acesso
• Consulta por protocolo
• Envio de lote
• Cancelamento
• Carta de correção

Validações

• Validação de CNPJ/CPF
• Validação de chave de acesso
• Validação de XML contra XSD

Utilitários

• Formatação de documentos
• Cálculo de dígito verificador
• Geração de números aleatórios

🔐 Segurança

• Assinatura digital com RSA
• Criptografia de dados sensíveis
• Comunicação HTTPS com TLS
• Validação de certificados

🧪 Testes

# Rodar todos os testes
cargo test

# Testes com output
cargo test -- --nocapture

# Testes de um módulo específico
cargo test nfe

# Gerar coverage (requer cargo-tarpaulin)
cargo tarpaulin --out Html

🛠️ Desenvolvimento

Pré-requisitos

• Rust 1.75+
• OpenSSL (para alguns recursos)

Build

# Build do workspace
cargo build

# Build em release
cargo build --release

# Build da CLI
cargo build -p opensefaz-cli

Features

• sync: Suporte a API síncrona (padrão)
• async: Suporte a API assíncrona
• openssl-vendored: Compila OpenSSL estaticamente

📖 Documentação

A documentação completa e interativa está disponível em:

• 📚 Documentação Completa - Guia completo com todos os detalhes
• 🌐 Site de Documentação - Para gerar com mdBook
• 📄 API Reference - Documentação gerada no docs.rs
• 💻 Exemplos - Código de exemplo

Tópicos da Documentação

1. Introdução - Visão geral do projeto
2. Instalação - Como instalar e configurar
3. Guia de Uso - Tutoriais e exemplos práticos
4. API Reference - Documentação completa da API
5. CLI - Uso da interface de linha de comando
6. Exemplos - Casos de uso reais
7. FAQ - Perguntas frequentes

Gerar Site de Documentação

Para gerar um site de documentação interativo:

# Instalar mdBook
cargo install mdbook

# Navegar para docs
cd docs

# Gerar e visualizar
mdbook serve --open

O site estará disponível em http://localhost:3000

🤝 Contribuindo

Contribuições são bem-vindas! Veja nosso Guia de Contribuição.

Como contribuir:

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'Adiciona nova feature')
4. Push (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

Dual-licensed under:

• MIT License (LICENSE-MIT)

🔗 Links Úteis

• Portal da NF-e
• Documentação Técnica NF-e
• Layout da NF-e

⚠️ Aviso Importante

Este projeto está em desenvolvimento ativo. Use em produção com cautela e sempre valide os resultados. A SEFAZ pode alterar especificações sem aviso prévio.

📞 Suporte

• Issues: https://github.com/opensefaz/opensefaz/issues
• Discussões: https://github.com/opensefaz/opensefaz/discussions

OpenSefaz - Criando sistemas fiscais robustos com Rust 🦀