fiscal 0.5.0 - Docs.rs

Port completo do sped-nfe (PHP) — a biblioteca fiscal brasileira mais usada (2.400+ stars) — reescrito em Rust com tipos algébricos, typestate pattern e 1000+ testes (94% de cobertura).

Durante o desenvolvimento, contribuímos 370 testes de volta ao sped-nfe (PR #1313, mergeado), elevando a cobertura de 40% para 86,5%.

Quick Start

[dependencies]
fiscal = "0.1"

use fiscal::types::*;
use fiscal::xml_builder::InvoiceBuilder;

let issuer = IssuerData::new(
    "25028332000105", "140950881119", "Minha Empresa",
    TaxRegime::Normal, "35", "3550308",
    "Rua Principal", "100", "Centro", "SAO PAULO", "01000000",
);

let item = InvoiceItemData::new(
    "001", "Produto Teste", "18069000", "5102", "UN",
    1000, 10000, 10000, "00", 1800, 10000, "01", "01",
);

let invoice = InvoiceBuilder::new(issuer, SefazEnvironment::Homologation, InvoiceModel::NFe)
    .series(1)
    .invoice_number(1)
    .operation_nature("VENDA")
    .add_item(item)
    .payments(vec![PaymentData::new("01", 10000)])
    .build()?;

println!("Chave: {}", invoice.access_key());
println!("XML: {}", invoice.xml());

Por que fiscal-rs?

O ecossistema Rust para documentos fiscais brasileiros é fragmentado e incompleto:

Feature	nfe	Rust-Nfe-API	Fiscalidade	fiscal-rs
NF-e (modelo 55)	Structs	Parse/Serialize	Transmit	Full
NFC-e (modelo 65)	-	Yes	?	Yes
Geração XML 4.00	-	Yes	-	Yes
SEFAZ mTLS	-	-	Yes	Yes
Certificado PFX/X.509	-	-	Yes	Yes
XMLDSig C14N	-	-	Yes	Yes
Todos os impostos (ICMS/PIS/COFINS/IPI/II/ISSQN)	-	-	-	Yes
Contingência (SVCAN/SVCRS/EPEC)	-	-	-	Yes
QR Code NFC-e (v2 + v3)	-	-	-	Yes
Protocolo (nfeProc)	-	-	-	Yes
Eventos (cancel/CCe/manifest)	-	-	-	Yes
TXT → XML (SPED)	-	-	-	Yes
Testes	Few	Some	Some	739+
crates.io	Yes	No	Yes	Yes

Benchmarks

Containers Docker idênticos: 1 CPU, 512 MB RAM. Metodologia completa →

Operação	Rust	Bun/TS	PHP	Rust vs Bun	Rust vs PHP
invoice_builder	27 µs	49 µs	427 µs	1.8x	16x
sign_xml	996 µs	1.9 ms	3.4 ms	1.9x	3.4x
tag_nested_item	3.0 µs	7.0 µs	9.7 µs	2.3x	3.2x
serialize_icms00	829 ns	1.0 µs	3.3 µs	1.2x	4.0x
tag_simple_text	122 ns	224 ns	1.0 µs	1.8x	8.5x
escape_xml_clean	40 ns	111 ns	124 ns	2.8x	3.1x

Reproduza você mesmo:

./benchmarks/run_all.sh   # requer Docker

Features

Ciclo completo NF-e/NFC-e: geração, assinatura, autorização, eventos, cancelamento, inutilização
Typestate pattern: InvoiceBuilder<Draft> → <Built> → <Signed> — erros impossíveis em compilação
Todos os ICMS: 15 CST (00-90) + 10 CSOSN (101-900), ICMSPart, ICMSST, ICMSUFDest
Todos os tributos: PIS, COFINS (Aliq/Qtde/NT/Outr/ST), IPI, II, ISSQN
Crypto nativo: carregamento PFX, assinatura XML-DSig RSA-SHA1 C14N, mTLS — sem child_process
Zero float drift: valores monetários em centavos i64 (10000 = R$ 100,00)
Newtypes validados: TaxId, Gtin, Ncm, Cfop — parse, don't validate
Layout 4.00: schema SEFAZ atual
FFI-ready: uma base Rust → PyO3, napi-rs, wasm-bindgen, UniFFI

Workspace

Crate	Descrição	crates.io
`fiscal-core`	Tipos, cálculos, builder XML
`fiscal-crypto`	Certificados e assinatura XML
`fiscal-sefaz`	URLs SEFAZ, SOAP, client HTTP
`fiscal`	Facade que re-exporta tudo

Convenções de valores

Tipo	Armazenamento	Exemplo	Significado
Dinheiro (vProd, vNF)	`Cents(i64)`	`Cents(1050)`	R$ 10,50
Alíquota ICMS (pICMS)	`Rate(i64)` centésimos	`Rate(1800)`	18,0000%
Alíquota PIS/COFINS	`Rate4(i64)` décimos de milésimo	`Rate4(16500)`	1,6500%

Metodologia de porting

Portar todos os testes 1:1 do PHP/TypeScript (739+ testes)
Implementar código Rust até todos passarem
Validar contra ambiente de homologação SEFAZ real
Contribuir de volta: 370 testes enviados ao sped-nfe original (cobertura 40% → 86,5%)

Contribuindo

git clone --recurse-submodules https://github.com/JoaoHenriqueBarbosa/fiscal-rs
./scripts/install-hooks.sh   # instala pre-push hook
cargo test                   # 739+ testes

Usamos conventional commits e release-plz para releases automáticos. Veja o guia completo de contribuição.

Agradecimentos

Um agradecimento enorme a @robmachado — criador e mantenedor do sped-nfe — e @gersonfs, contribuidor ativo do projeto. Ambos me receberam de braços abertos nos PRs, consideraram minhas contribuições com seriedade e geraram discussões que melhoraram tanto o sped-nfe quanto o fiscal-rs. O fiscal-rs só existe porque o sped-nfe pavimentou o caminho por mais de uma década. Obrigado por manter o ecossistema fiscal brasileiro vivo e aberto.

Projetos relacionados

sped-nfe — Implementação PHP de referência (2.400+ stars)
FinOpenPOS — Port TypeScript (ancestral direto desta lib)
nfe — Structs NF-e em Rust por Fernando Batels
Rust-Nfe-API — Parser/serializer NF-e em Rust
Fiscalidade — Transmissão SEFAZ em Rust

Licença

MIT