OpenSefaz

⚠️ 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.

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

📦 Crates

O projeto é organizado em crates modulares:

🚀 Quick Start

use nfe_core::{Config, Ambiente};
use nfe_transport::{NfeClient, TransportCertificate};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::new(
        "99999999999999".to_string(),
        "SP".to_string(),
        Ambiente::Homologacao,
    );

    let cert = TransportCertificate::from_pem_file("cert.pem", "senha")?;
    let client = NfeClient::new(config, cert)?;

    let result = client.consultar_por_chave("42150899999999999550010000000011234567890").await?;
    println!("Status: {:?}", result.status);

    Ok(())
}

📦 Instalação

Usando crates individuais

[dependencies]
nfe-core = "0.1"
nfe-transport = "0.1"
tokio = { version = "1.0", features = ["full"] }

Usando todos os crates

[dependencies]
nfe-core = "0.1"
nfe-xml = "0.1"
nfe-transport = "0.1"

CLI

cargo build -p nfe-cli
./target/debug/nfe --help

🔧 Uso

Biblioteca - nfe-core (validações)

use nfe_core::utils::{validar_cnpj, formatar_cnpj};

// Validar e formatar CNPJ
if validar_cnpj("12345678000195") {
    println!("{}", formatar_cnpj("12345678000195"));
}

Biblioteca - nfe-xml (XML)

use nfe_xml::{XmlValidator, XmlSigner};

let validator = XmlValidator::new();
validator.validate_nfe(xml)?;

let signer = XmlSigner::new(cert_pem, key_pem);
let signed = signer.sign_xml(xml, None)?;

Biblioteca - nfe-transport (SEFAZ)

use nfe_transport::{NfeClient, TransportCertificate};

let cert = TransportCertificate::from_pem_file("cert.pem", "senha")?;
let client = NfeClient::new(config, cert)?;

let resultado = client.consultar_por_chave("42150899999999999550010000000011234567890").await?;

CLI

# Consultar NF-e
nfe --certificado ./cert.pem --senha 123456 --cnpj 99999999999999 consultar 42150899999999999550010000000011234567890

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

# Validar XML
nfe validar nfe.xml

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

# Formatar documentos
nfe formatar 12345678000195 --tipo cnpj

🏗️ Arquitetura do Projeto

opensefaz/
├── nfe-core/           # Core types, error handling, config, validations
│   ├── src/
│   │   ├── lib.rs       # Ponto de entrada
│   │   ├── error.rs     # Error types
│   │   ├── config.rs    # Config, Ambiente
│   │   ├── types.rs     # Status, ConsultaResultado, ChaveAcesso
│   │   └── utils.rs     # Validação CNPJ/CPF, formatação
│   └── Cargo.toml
├── nfe-xml/             # XML handling, signing, validation
│   ├── src/
│   │   ├── lib.rs
│   │   ├── parse.rs     # XML parsing (NFe, InfNFe, etc)
│   │   ├── sign.rs      # XML signing
│   │   └── validate.rs  # XML validation
│   └── Cargo.toml
├── nfe-transport/       # Transport layer, HTTP, SOAP
│   ├── src/
│   │   ├── lib.rs
│   │   ├── client.rs    # NfeClient
│   │   ├── soap.rs      # SOAP envelope
│   │   └── certificate.rs
│   └── Cargo.toml
├── nfe-cli/             # CLI binary
│   ├── src/
│   │   └── main.rs
│   └── Cargo.toml
└── Cargo.toml           # Workspace

📚 Recursos Principais

nfe-core - Core

• Validação de CNPJ/CPF (módulo 11)
• Validação de chave de acesso (44 dígitos)
• Cálculo de dígito verificador
• Formatação de documentos (CNPJ, CPF, CEP)
• Sistema de erros tipado

nfe-xml - XML

• Parse de NF-e (NFe, InfNFe, Ide, Emit, Dest, etc)
• Validação de estrutura XML
• Extração de chave de acesso
• Detecção de cancelamento/denegação

nfe-transport - Transport

• Cliente HTTP para SEFAZ
• Construção de envelopes SOAP
• Gerenciamento de certificados
• Consulta por chave/protocolo
• Cancelamento de eventos

nfe-cli - CLI

• consultar - Consulta NF-e por chave
• status - Status do serviço
• validar - Valida XML
• assinar - Assina XML
• gerar-chave - Gera chave de acesso
• certificado - Verifica certificado
• formatar - Formata documentos

🔐 Segurança

• Assinatura digital com RSA-SHA256
• Comunicação HTTPS com TLS
• Validação de certificados digitais
• Validação de todas as entradas

🧪 Testes

# Rodar todos os testes
cargo test

# Testes com output
cargo test -- --nocapture

# Testar crate específico
cargo test -p nfe-core
cargo test -p nfe-xml
cargo test -p nfe-transport

# Coverage
cargo tarpaulin --out Html

🛠️ Desenvolvimento

Pré-requisitos

• Rust 1.75+
• OpenSSL (para recursos de criptografia)

Build

# Build completo do workspace
cargo build

# Build específico
cargo build -p nfe-core
cargo build -p nfe-xml
cargo build -p nfe-transport
cargo build -p nfe-cli

# Release
cargo build --release

Features

📖 Documentação

• 📚 Documentação Completa - Guia completo
• 🌐 Site de Documentação - mdBook
• 📄 API Reference - docs.rs

Gerar Site de Documentação

cd docs
mdbook serve --open

🤝 Contribuindo

Veja CONTRIBUTING.md.

Regra importante: Ao adicionar novas funcionalidades, atualize também a documentação em docs/.

Como contribuir:

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'feat(nfe-core): adiciona nova função')
4. Push (git push origin feature/nova-feature)
5. Abra um Pull Request
6. Atualize a documentação em docs/ se necessário

📄 Licença

• MIT License (LICENSE-MIT)

🔗 Links Úteis

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

📞 Suporte

• Issues: https://github.com/opensefaz/opensefaz/issues
• Discussions: https://github.com/opensefaz/opensefaz/discussions

OpenSefaz - Criando sistemas fiscais robustos com Rust 🦀