# 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)
[](https://crates.io/crates/nfe-core)
[](https://docs.rs/nfe-core)
[](https://github.com/opensefaz/opensefaz#license)
[](https://github.com/opensefaz/opensefaz/actions)
## 🚀 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:
| `nfe-core` | Tipos core, erros, configurações, validações |
| `nfe-xml` | Parse, validação e assinatura de XML |
| `nfe-transport` | Camada de transporte, cliente HTTP, SOAP |
| `nfe-cli` | Interface de linha de comando |
## 🚀 Quick Start
```rust
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
```toml
[dependencies]
nfe-core = "0.1"
nfe-transport = "0.1"
tokio = { version = "1.0", features = ["full"] }
```
### Usando todos os crates
```toml
[dependencies]
nfe-core = "0.1"
nfe-xml = "0.1"
nfe-transport = "0.1"
```
### CLI
```bash
cargo build -p nfe-cli
./target/debug/nfe --help
```
## 🔧 Uso
### Biblioteca - nfe-core (validações)
```rust
use nfe_core::utils::{validar_cnpj, formatar_cnpj};
// Validar e formatar CNPJ
if validar_cnpj("12345678000195") {
println!("{}", formatar_cnpj("12345678000195"));
}
```
### Biblioteca - nfe-xml (XML)
```rust
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)
```rust
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
```bash
# 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
```bash
# 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
```bash
# 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
| `sync` | nfe-transport | API síncrona (padrão) |
| `async` | nfe-transport | API assíncrona |
| `openssl-vendored` | nfe-transport | OpenSSL estático |
## 📖 Documentação
- **[📚 Documentação Completa](docs/DOCUMENTACAO.md)** - Guia completo
- **[🌐 Site de Documentação](docs/src/SUMMARY.md)** - mdBook
- **[📄 API Reference](https://docs.rs/nfe-core)** - docs.rs
### Gerar Site de Documentação
```bash
cd docs
mdbook serve --open
```
## 🤝 Contribuindo
Veja [CONTRIBUTING.md](./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](LICENSE-MIT))
## 🔗 Links Úteis
- [Portal da NF-e](http://www.nfe.fazenda.gov.br/)
- [Documentação Técnica NF-e](http://www.nfe.fazenda.gov.br/portal/documentacaoAcesso.asp?tipo=2)
## 📞 Suporte
- Issues: https://github.com/opensefaz/opensefaz/issues
- Discussions: https://github.com/opensefaz/opensefaz/discussions
---
**OpenSefaz** - Criando sistemas fiscais robustos com Rust 🦀