Sped Common Laravel Package

Product Decisions This Supports

• Regulatory Compliance as a Core Feature:

  • Enables mandatory Brazilian tax compliance (NFe, CTe, MDFe, eSocial) for Laravel-based products targeting the Brazilian market, reducing legal exposure and operational risk.
  • Differentiator: For SaaS/ERP platforms competing in Brazil, this package provides a turnkey solution for SPED integration, accelerating time-to-market for tax-compliant features.

• Build vs. Buy Decision:

  • Buy: Ideal for teams without in-house expertise in Brazilian fiscal standards (SPED, NF-e, etc.). Avoids reinventing the wheel for XML validation, key generation, and cryptographic operations.
  • Build Only If:
    • Requiring custom fiscal logic beyond SPED (e.g., industry-specific tax rules).
    • Targeting multi-country SPED variants (e.g., Mexico’s CFDI) with minimal overlap.
    • Needing real-time SEFAZ API optimizations (e.g., connection pooling, retry logic).

• Roadmap Priorities:

  • Phase 1 (MVP): Integrate into invoice generation/validation workflows (e.g., Laravel-based e-commerce or ERP systems).
  • Phase 2 (Scalability): Abstract SPED logic into a service layer to support future multi-country tax compliance (e.g., via adapter pattern).
  • Phase 3 (Developer Experience): Build a fluent wrapper (e.g., SpedBuilder::nfe()->withItems([...])->validate()) to simplify usage for non-technical stakeholders.

• Use Cases:

  • E-Commerce Platforms: Automate NFe/CTe generation for B2B transactions in Brazil, with pre-submission validation to avoid SEFAZ rejections.
  • Accounting/ERP Systems: Replace custom XML validation logic with this package’s standardized methods, ensuring compliance across all fiscal documents.
  • Government/Gateways: Validate tax documents received via webhooks (e.g., from SEFAZ or third-party providers) before processing.
  • Audit/Forensics Tools: Verify the integrity of tax documents using cryptographic validation (e.g., Validator::isValid() + PrivateKey::verify()).

• Cost Reduction:

  • Eliminates need for third-party SPED consultants or custom development for XML validation/key generation.
  • Reduces SEFAZ rejection rates via built-in schema validation (e.g., Validator::isValid()).

When to Consider This Package

Adopt If:

• Your product must handle Brazilian fiscal electronic documents (NFe, CTe, MDFe, eSocial) and lacks in-house SPED expertise.
• You need reliable XML validation against SPED schemas (e.g., for pre-submission checks or audit trails).
• Your Laravel application requires:
  • Key generation/validation for NFe/CTe/MDFe (e.g., 44-digit keys per NT 2018.001).
  • Digital signature handling (e.g., PrivateKey::sign(), PublicKey::verify()).
  • Certificate management (e.g., expiry checks, storage).
• You’re building a tax-compliant system where:
  • Regulatory risk is high (e.g., fines for non-compliant invoices).
  • Integration with SEFAZ is required (e.g., web services, webhooks).
• Your team prioritizes maintainability over custom XML/XSD logic.

Avoid If:

• Your product does not operate in Brazil or target Brazilian tax compliance.
• You need multi-country SPED support (e.g., Mexico’s CFDI) with minimal customization (consider forking or alternatives like cfdi-php).
• Your use case involves non-standard fiscal documents (e.g., custom XML schemas unrelated to SPED).
• Your team has deep expertise in Brazilian tax laws and prefers building custom solutions for full control.
• You require real-time SEFAZ API optimizations (e.g., connection pooling, custom retry logic) beyond XML validation.

Alternatives to Evaluate:

How to Pitch It (Stakeholders)

For Executives:

"This package solves a critical regulatory and operational bottleneck for our Brazilian market expansion. By integrating nfephp-org/sped-common into our Laravel stack, we can:

• Automate NFe/CTe validation and key generation, reducing SEFAZ rejection rates by X% (estimate based on current manual process).
• Cut development time for tax-compliant features by Y weeks, avoiding costly third-party consultants.
• Future-proof our product for Brazilian fiscal requirements (e.g., eSocial, e-Financeira) with a single dependency.
• Lower compliance risk by leveraging a production-tested, community-maintained library used by [Z major Brazilian enterprises].

Investment: Minimal (Composer install + 2–4 weeks of integration). ROI: Faster time-to-market for Brazilian customers, reduced audit risk, and scalability for multi-country tax compliance."

For Engineering Teams:

"This package provides a batteries-included solution for Brazilian SPED compliance in Laravel, covering:

1. XML Validation: Pre-submission checks against SEFAZ schemas (NFe, CTe, MDFe).
2. Key Generation: 44-digit keys for fiscal documents (per NT 2018.001).
3. Cryptography: Digital signing/verification with PrivateKey/PublicKey.
4. Certificate Management: Expiry checks and secure storage.

Why Use It?

• No reinventing the wheel: Handles edge cases (e.g., XML sanitization, schema updates) that would take months to build.
• Laravel-friendly: Integrates via service providers, facades, or Artisan commands.
• Low maintenance: Active community (106 stars, 4.8 avg rating) with clear upgrade paths.

Trade-offs:

• Tight coupling to Brazilian standards (not ideal for multi-country SPED).
• Requires PHP OpenSSL and basic XML extensions.

Next Steps:

1. Spike: Validate XML with Validator::isValid() in a sandbox.
2. Prototype: Generate a key for a test NFe using Keys::build().
3. Architect: Design a service layer to abstract SPED logic for future extensibility."

For Legal/Compliance Teams:

"This package ensures our product adheres to Brazilian fiscal laws (SPED, NF-e, CTe) by:

• Validating XML against SEFAZ schemas before submission, reducing rejection risks.
• Generating compliant keys (e.g., 44-digit NFe keys) per regulatory standards (NT 2018.001).
• Supporting digital signatures for non-repudiation of fiscal documents.

Key Benefits:

• Audit-ready: Logs validation failures and cryptographic proofs.
• Future-proof: Aligns with upcoming SPED requirements (e.g., eSocial, e-Financeira).
• Reduced liability: Uses a community-vetted library with active maintenance.

Recommendation: Approve integration as a core dependency for Brazilian market compliance."