Epic: complete and harden the National NFS-e protocol client

[vitormattos]

Outcome

Make nfse-php a robust, reusable protocol layer for the National NFS-e ecosystem, with versioned official contracts, complete contributor operations, strict validation and testable transport/security boundaries.

Why

The library already covers emission, DPS recovery, query, cancellation, selected event lookup, ADN distribution, municipal parameters, DANFSe v2, IBS/CBS, foreign takers and XML signature integrity. The remaining gaps are protocol completeness and preservation of testable architecture while the protocol surface grows.

A comparison with other National NFS-e SDKs found a recurring failure mode: clients/services gradually accumulate XML construction, certificate handling, signing, HTTP, retry and parsing responsibilities. #60 therefore requires a characterization-first architecture audit before major new protocol features are allowed to increase that coupling.

Other open implementations demonstrate useful patterns: versioned official XSD fixtures, domain-table snapshots, integration fixtures, explicit transport abstractions and substitution/event coverage. The official National NFS-e API also supports substitution semantics and generic event operations beyond the current convenience methods.

Scope

• official schema/version lifecycle and XSD validation
• NFS-e substitution support
• complete generic SEFIN event operations
• versioned official domain/correlation tables
• received-signature trust verification separated from integrity verification
• injectable/testable HTTP transport and safe retry policy
• sanitized official response fixtures/contract tests
• remaining production fiscal groups such as deductions/reductions/benefits and administrative/judicial decision emission

Out of scope

• Akaunting UI/persistence
• municipality-specific legacy SOAP providers
• NFS-e Via/concessionaire features unless they become applicable to the normal contributor API
• silently inferring tax treatment
• unsafe retries of mutating fiscal operations

Success criteria

• generated DPS/event XML is validated against the exact supported official XSD release
• protocol versions and official tables are explicit and auditable
• substitution and event lifecycle are represented without Akaunting-specific assumptions
• transport behavior is injectable and deterministic in tests
• XML signature integrity and certificate trust are distinct concepts in the API
• fixture tests cover success, rejection, timeout and malformed upstream payloads

Definition of done

• all child issues complete
• public API changes documented with migration notes
• compatibility tests pass on supported PHP versions and minimum dependency set
• no cross-layer Akaunting dependency introduced

Intended GitHub issue type: Epic.

Child issues

• Validate generated fiscal XML against versioned official XSD bundles #48 — Official XSD validation and schema lifecycle
• Add first-class NFS-e substitution support #49 — First-class NFS-e substitution
• Complete the generic SEFIN event query and registration API #50 — Complete generic SEFIN event API
• Version official NFS-e domain and correlation tables #51 — Versioned official domain/correlation tables
• Separate XML signature integrity from ICP-Brasil certificate trust validation #52 — ICP-Brasil trust validation separate from XMLDSig integrity
• Introduce an injectable HTTP transport and safe retry policy #53 — Injectable HTTP transport and safe retry policy
• Add sanitized SEFIN and ADN contract fixture suites #54 — Sanitized SEFIN/ADN contract fixtures
• Complete municipal deductions, reductions and benefit fields in DPS #55 — Municipal deductions/reductions/benefits
• Support emission under administrative or judicial decision rules #56 — Administrative/judicial decision emission
• Validate DANFSe v2 rendering against official NT 008 reference cases #57 — DANFSe v2 reference/golden regression tests
• Establish tagged releases and a documented compatibility policy #59 — Establish tagged releases and a documented compatibility policy
• Audit nfse-php architecture for testability and protocol-boundary separation #60 — Architecture/testability audit and protocol-boundary separation

[vitormattos]

Protocol-hardening status after the current implementation batch:

• Validate generated fiscal XML against versioned official XSD bundles #48 complete: versioned official XSD validation for DPS/events/complete NFS-e
• Add first-class NFS-e substitution support #49 complete: first-class substitution
• Complete the generic SEFIN event query and registration API #50 complete: generic SEFIN event API
• Version official NFS-e domain and correlation tables #51 complete: reproducible official domain/correlation tables
• Separate XML signature integrity from ICP-Brasil certificate trust validation #52 complete: ICP-Brasil trust separated from XMLDSig integrity
• Introduce an injectable HTTP transport and safe retry policy #53 complete: injectable transport and safe retry policy
• Add sanitized SEFIN and ADN contract fixture suites #54 complete: protocol contract fixtures
• Complete municipal deductions, reductions and benefit fields in DPS #55 complete: deductions/reductions/benefits
• Support emission under administrative or judicial decision rules #56 complete: administrative/judicial decision flow
• Validate DANFSe v2 rendering against official NT 008 reference cases #57 complete: DANFSe v2 regression coverage
• Audit nfse-php architecture for testability and protocol-boundary separation #60 complete: architecture/testability audit

Only #59 remains intentionally deferred until pre-release/stabilization. #85 aligns Release Drafter with that decision by making it manual rather than failing on every main push.

Keep this epic open while #59 is intentionally deferred; the functional protocol scope is otherwise complete.

[vitormattos]

Closing this epic: all child issues are now closed.

The protocol-hardening scope is complete on main: official schemas/tables, substitution/events, trust separation, injectable transport, fixtures, fiscal groups, decision-flow emission, DANFSe regression coverage and architecture/testability work are all integrated.

Release policy work (#59) is no longer an active blocker and was closed separately. Future protocol changes should be tracked as new focused issues rather than keeping this completed epic open.