Ws Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package is a niche, country-specific solution for Peru’s SUNAT electronic invoicing (facturación electrónica) requirements. It fits well in architectures where:
  • The product must comply with Peruvian tax regulations (e.g., e-invoicing, e-tickets, or e-documentation).
  • The system requires integration with SUNAT’s Web Services API (e.g., sunat.pe for validation, emission, or consultation of electronic documents).
  • The backend is Laravel/PHP-based, eliminating cross-language integration overhead.
• Monolithic vs. Microservices:
  • Monolithic: Easy to embed as a service layer (e.g., SUNATService facade).
  • Microservices: Could be exposed as a dedicated microservice (e.g., sunat-api) if the team prefers decoupling.
• Event-Driven Fit: If the system uses queues/jobs (e.g., Laravel Queues), the package’s synchronous nature may require wrappers for async processing (e.g., retries, dead-letter queues).

Integration Feasibility

• API Contract: The package abstracts SUNAT’s SOAP/WSDL endpoints (e.g., https://e-factura.sunat.gob.pe). Feasibility is high if:
  • The team can mock SUNAT responses for testing (e.g., using Laravel’s Mockery or Vcr).
  • The project does not require real-time validation (SUNAT has rate limits and may throttle requests).
• Dependencies:
  • Primary: guzzlehttp/guzzle (for HTTP requests), phpseclib/phpseclib (for digital signatures).
  • Secondary: Laravel’s config, log, and cache systems (if configured).
  • Risk: phpseclib may need updates for TLS 1.3 compliance (SUNAT may enforce this).
• Data Flow:
  • Input: XML payloads (e.g., ComprobanteElectronico).
  • Output: SUNAT responses (e.g., CDR, receipts, or errors like 1001 for invalid signatures).
  • Challenge: Validating XML schemas against SUNAT’s XSD schemas (e.g., UBL-2.1 for invoices) may require additional libraries (e.g., ext-simplexml, xmlschema).

Technical Risk

Key Questions

1. Compliance Requirements:
   • Does the product need real-time SUNAT validation, or is batch processing sufficient?
   • Are there additional SUNAT integrations (e.g., CDR for credit notes, PDA for authorizations)?
2. Security:
   • How will digital certificates (.p12/.pfx) be managed? (e.g., AWS Secrets Manager, Laravel Vault).
   • Is TLS 1.3 required for SUNAT endpoints? If so, does phpseclib support it?
3. Testing:
   • Can the team mock SUNAT responses for CI/CD? (e.g., using Vcr or Pest).
   • Are there edge cases (e.g., SUNAT downtime, malformed XML) to handle?
4. Maintenance:
   • Who will update the package if SUNAT changes its API (e.g., new WSDL)?
   • Should the team fork and maintain a private version?
5. Performance:
   • What is the expected volume of SUNAT requests? (e.g., 100/day vs. 10,000/day).
   • Will caching (e.g., Laravel Cache) be needed for repeated requests?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • High: The package is PHP-based and can be integrated via Composer.
  • Recommended Setup:

    composer require greenter/ws
    

  • Laravel Services:
    • Register as a service provider (AppServiceProvider):

      $this->app->singleton(SUNATService::class, function ($app) {
          return new SUNATService(config('sunat.credentials'));
      });
      

    • Use facades for cleaner code:

      use Greenter\Ws\Facades\SUNAT;
      
      SUNAT::sendInvoice($xmlPayload);
      

• Alternative Stacks:
  • Symfony: Works with minor adjustments (e.g., DI container).
  • Non-Laravel PHP: Requires manual setup (e.g., Guzzle client, XML handling).

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Goal: Validate basic functionality (e.g., sending a test invoice).
   • Steps:
     • Set up a local SUNAT sandbox (if available) or mock responses.
     • Test with pre-generated XML (e.g., from SUNAT’s developer portal).
     • Verify digital signing works with a test certificate.
   • Tools: Laravel Tinker, Postman (for raw API testing).

2. Phase 2: Core Integration

   • Goal: Integrate with the product’s invoice generation flow.
   • Steps:
     • Extend the package to wrap SUNAT calls in Laravel Jobs (for async processing).
     • Add retry logic for failed requests (e.g., using spatie/laravel-queueable-middleware).
     • Implement logging for SUNAT responses (e.g., Laravel’s Log channel).
   • Example Flow:

     User creates invoice → System generates XML → SUNATService sends to SUNAT → Store CDR → Return receipt to user.
     

3. Phase 3: Production Readiness

   • Goal: Ensure compliance, security, and scalability.
   • Steps:
     • Certificate Management: Automate renewal/rotation (e.g., cron job to check expiry).
     • Monitoring: Track SUNAT response times and errors (e.g., Laravel Horizon for queues).
     • Backup Plan: Implement a fallback mechanism (e.g., email alerts for SUNAT failures).
     • Audit Logs: Store SUNAT interactions in a database (e.g., sunat_audit_logs table).

Compatibility

• Laravel Versions:
  • Tested: PHP 7.2–7.4 (package’s composer.json).
  • Recommendation: Use Laravel 8+ with PHP 8.0+ (minor tweaks may be needed for type hints).
• SUNAT API Changes:
  • Risk: SUNAT may update WSDL/XSD schemas. Mitigation:
    • Subscribe to SUNAT’s developer alerts.
    • Maintain a changelog for API updates.
• Third-Party Dependencies:
  • Guzzle: Ensure version ^6.5 or ^7.0 is used (avoid breaking changes).
  • phpseclib: May need patching for TLS 1.3 (check SUNAT’s TLS requirements).

Sequencing

Operational Impact

Maintenance

• Package Updates:
  • Risk: Abandoned since 2019. Strategy:
    • Short-term: Use as-is with local patches.
    • Long-term: Fork the repo and **maintain a