Nfse Ssa Laravel Package

Technical Evaluation

Architecture fit

• Single-municipality fiscal adapter: the package targets the Salvador (BA) municipal NFS-e webservice, wrapping SOAP calls, RPS (Recibo Provisório de Serviços) XML construction, XMLDSig signing with an ICP-Brasil A1 certificate, lot submission, and query/cancellation. It is a boundary integration, not a domain layer — correct placement is behind an application-level port (e.g. InvoiceGateway), never called directly from controllers or models.
• Fit is narrow by design: Brazilian NFS-e is municipal, so this package solves exactly one jurisdiction. It is appropriate only if Salvador is a current or near-term billing jurisdiction; it is not a general Brazil NFS-e solution.
• Strategic timing risk: the national NFS-e standard (Sistema Nacional NFS-e) is consolidating municipal obligations. A Salvador-specific adapter has a finite useful life and should be treated as replaceable from day one.
• Expect the package's value to be the wire format and signing logic, which is the genuinely expensive part to reimplement — not the orchestration, persistence, or retry semantics, which we must own.

Integration feasibility

• Low-to-moderate effort for a Laravel app: typical shape is a service provider, publishable config (environment, CNPJ/inscrição municipal, certificate path and passphrase, RPS series/numbering), and a facade or injectable client. Verify whether it is Laravel-version-constrained (service provider auto-discovery, illuminate/support version bounds) and whether it is genuinely framework-coupled or a plain PHP library with a Laravel wrapper.
• Hard platform prerequisites: ext-soap, ext-openssl, a valid A1 PKCS#12 certificate, municipal credentials, and access to both homologation and production endpoints. These are procurement and ops tasks, not composer tasks — budget calendar time, not just engineering time.
• Certificate handling is the main security surface: passphrase in secrets manager, certificate mounted as a file or read from a vault, never committed, never logged. Confirm whether the package accepts a certificate path/passphrase or expects ambient filesystem state and global openssl config.
• Verify sandbox quality early. Municipal homologation environments are frequently stale, intermittently available, or behaviorally divergent from production. Treat "can we get a clean homologation round-trip" as a go/no-go spike with a time box.

Technical risk

• Stewardship risk (high): 25 stars and 0 dependents means effectively no external validation, no downstream bug surface, and likely a single maintainer. Assume we may become the maintainer. The release date is dated in the future relative to typical evaluation windows — verify tag hygiene, changelog, and whether releases track real commits.
• Protocol drift (high): municipal WSDLs and XSDs change with little notice; the city can alter required fields, rejection codes, or endpoints. No amount of package quality protects against this — only fast detection and a fork path do.
• Correctness risk (high, business-critical): a malformed or rejected NFS-e is a tax compliance event, not a 500. Duplicate RPS numbers, wrong service code, wrong ISS retention, or wrong taxation regime produce rejected lots and downstream reconciliation work with accounting.
• Maintenance risk (medium): PHP/SOAP dependencies are stable, but XML signing and namespace handling can break across libxml/openssl upgrades. Pin versions and cover the signature path with a golden-file test.
• License risk (low): MIT is permissive; forking and internalizing is unencumbered.

Key questions

• Does the package cover the full lifecycle we need — issue, query by RPS, cancel, substitute, and retrieve the authorized XML — or only issuance?
• How does it handle the "sent but response lost" case: does it expose a query-by-RPS for reconciliation, or does it just throw on timeout?
• Is RPS numbering managed by the package, by us, or not at all? This determines whether we need a transactional sequence store.
• Laravel and PHP version support matrix, and whether tests exist at all (unit-only vs. recorded-response integration tests).
• Does it enforce/marshal the municipal service code, ISS withholding, and taxation regime fields, or pass them through raw?
• Who signs the XML, and does the package validate the certificate before the round-trip (expiry, chain) so we fail fast rather than at the city?
• Is multi-tenant issuance on behalf of multiple CNPJs supported, or is it one-prestador-per-configuration?

Integration Approach

Stack fit

• Laravel-native install, but the honest integration unit is an anti-corruption layer: define our own MunicipalInvoiceGateway interface with issue, query, cancel, substitute, returning our own DTOs. Implement it with this package, and keep a NullGateway/manual-fallback implementation for outages and a future national-NFS-e or second-municipality implementation.
• Persist everything we need to be independent of the package's return types: RPS series/number, our internal invoice id, request XML, response XML, authorization number, verification code, status, and rejection codes.
• Signing and certificate loading stay in infrastructure; fiscal rules (which service code, ISS treatment, taxation regime) stay in our domain, driven by configuration per service offering — not hardcoded in the adapter.

Migration path

• If Salvador invoicing already exists (portal-based manual issuance, spreadsheet-driven, or a legacy script), run the package in shadow mode against homologation first: generate RPS/XML, compare field-by-field with what accounting files today, and only then enable production issuance.
• Plan the exit before entry: the adapter interface plus stored XML means switching to a national-standard provider or a fork is a class swap, not a rewrite.
• If we are greenfield with no Salvador obligations, defer — the package's value is unproven and the national standard is converging.

Compatibility

• Confirm PHP and Laravel support bounds against our current runtime; SOAP and signing behavior can shift on PHP minor upgrades. Pin the package and libxml/openssl behavior via a signature golden test in CI.
• Certificate compatibility (A1 PKCS#12, ICP-Brasil chain) and any requirement for the municipal cadastro to be active and in good standing in both homologation and production.
• Check whether the package assumes a specific php.ini (openssl config path, soap.wsdl_cache) that differs between our containers and the maintainer's environment.

Sequencing

1. Time-boxed homologation spike: certificate + credentials + one successful issue/query/cancel round-trip. Kill or proceed on evidence.
2. Adapter interface, DTOs, and persistence schema (RPS sequence, XML archive, status machine).
3. Queue-backed issuance with idempotency keys and a reconciliation job that queries unresolved submissions.
4. Cancellation/substitution flows plus accounting-facing export.
5. Observability, alerting, and a documented manual fallback runbook.
6. Reassess against national NFS-e obligations at each fiscal-year planning cycle.

Operational Impact

Maintenance

• Assume fork-and-own. Vendor a copy into our monorepo or a private registry mirror, tag it, and track upstream manually. Upstream responsiveness should not be on our critical path.
• Maintain our own contract tests: recorded request/response fixtures replayed against the signing and parsing layer so PHP/libxml upgrades surface immediately.
• Fiscal maintenance is recurring, not one-off — annual service-code and tax-regime reviews with accounting.

Support

• Internal ownership is required; no meaningful community support channel exists at 25 stars. Budget for one engineer with fiscal-domain familiarity as the named owner.
• Establish a relationship with the municipality's NFS-e support for credential and cadastro issues, and with accounting for rejection-code interpretation.
• Document a manual issuance runbook via the city portal; this is the real fallback when the webservice is down near a filing deadline.

Scaling

• Throughput is bounded by the municipal webservice, not by us. SOAP endpoints are typically rate-limited and slow; issue asynchronously via queues with concurrency caps and backoff.
• RPS numbering is a serialization point — a database sequence with row-level locking per prestador/series, never an in-memory counter, or concurrent workers will collide and produce rejected lots.
• XML archive grows monotonically (retention typically five years, per fiscal rules); plan object storage with lifecycle policy, not a database blob column.

Failure modes

• Accepted-but-timeout: the city processed the RPS but the response never arrived. Blind retry creates duplicates. Mitigation: idempotency by RPS number plus an out-of-band query before any retry.
• Rejection with business cause (invalid service code, expired cadastro, wrong taxation regime): must route to a human queue with the municipal message preserved verbatim, not retry forever.
• Certificate expiry or chain break: fails at signing or at the city with an opaque fault. Mitigation: scheduled expiry checks with lead-time alerting.
• Municipal outage / WSDL change: issuance stalls. Mitigation: circuit breaker, dead-letter queue, stalled-invoice dashboard, and the manual fallback.
• Silent field drift after an XSD update: requests start being accepted but with wrong tax treatment. Mitigation: periodic reconciliation of authorized invoices against expected fiscal values.

Ramp-up

• Moderate for a PHP developer, high for the fiscal semantics. The package removes the SOAP/signing toil but not the domain burden: service codes, ISS retention, taxation regime, RPS numbering, cancellation windows, and retention rules all require accounting partnership.
• Realistic onboarding: one engineer-week to a working homologation issue, plus two to four weeks to a production-grade, queued, reconciled, observable flow — with certificate and cadastro provisioning on the critical path and outside engineering's control.
• Given zero dependents and a low aggregate score, treat adoption as an evaluated bet with a defined exit, not a settled dependency choice.