Nota Fiscal Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require brazilianfriends/symfony-nota-fiscal-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       BrazilianFriendsOfSymfony\NotaFiscalBundle\BFOSNotaFiscalBundle::class => ['all' => true],
   ];
   

2. First Use Case: Generate a NF-e (Nota Fiscal Eletrônica) Configure the bundle in config/packages/bfos_nota_fiscal.yaml:

   bfos_nota_fiscal:
       environment: 'homologacao' # or 'producao'
       cnpj: '12345678901234'
       certificate_path: '%kernel.project_dir%/path/to/certificate.pfx'
       certificate_password: 'your_password'
   

   Use in a controller:

   use BrazilianFriendsOfSymfony\NotaFiscalBundle\Service\NotaFiscalService;
   
   public function generateNFe(NotaFiscalService $notaFiscalService)
   {
       $nfe = $notaFiscalService->createNFe([
           'cnpj' => '98765432109876',
           'serie' => '1',
           'numero' => '123',
           'valor' => 100.00,
           'destinatario' => [
               'cnpj' => '11122233344455',
               'nome' => 'Destinatário Teste',
           ],
       ]);
       return $nfe->getXml();
   }
   

3. Key Files to Review

   • config/packages/bfos_nota_fiscal.yaml (Configuration)
   • src/Service/NotaFiscalService.php (Core service)
   • src/Entity/NotaFiscal.php (Data structure)

Implementation Patterns

Common Workflows

1. Generating NF-e

   $notaFiscalService->createNFe([
       'cnpj' => '98765432109876',
       'serie' => '1',
       'numero' => '123',
       'valor' => 100.00,
       'destinatario' => [...],
       'produtos' => [ // Optional
           ['descricao' => 'Produto 1', 'quantidade' => 2, 'valor' => 50.00],
       ],
   ]);
   

2. Consulting NF-e Status

   $status = $notaFiscalService->consultarNFeStatus($nfe->getProtocolo());
   

3. Canceling NF-e

   $notaFiscalService->cancelarNFe($nfe->getProtocolo(), 'Motivo de cancelamento');
   

4. Event Listeners Subscribe to events like nfe.created or nfe.cancelled:

   # config/services.yaml
   services:
       App\EventListener\NotaFiscalListener:
           tags:
               - { name: 'kernel.event_listener', event: 'nfe.created', method: 'onNFeCreated' }
   

Integration Tips

• Laravel-Specific: Use Symfony’s HttpClient via GuzzleHttp for API calls if needed.
• Database Storage: Store generated NF-e data in Laravel’s Eloquent models:

  class NotaFiscal extends Model
  {
      protected $casts = [
          'protocolo' => 'string',
          'xml' => 'text',
      ];
  }
  

• Queue Jobs: Offload NF-e generation to queues for async processing:

  dispatch(new GenerateNFeJob($data));
  

Gotchas and Tips

Pitfalls

1. Certificate Handling

   • Ensure the .pfx certificate is in the correct path and has the right permissions.
   • Test locally with the homologacao environment before switching to producao.

2. Timeouts

   • The SEFAZ (Brazilian tax authority) API may time out. Implement retry logic:

     try {
         $response = $notaFiscalService->createNFe($data);
     } catch (TimeoutException $e) {
         retry()->times(3)->try(fn() => $notaFiscalService->createNFe($data));
     }
     

3. Validation Errors

   • SEFAZ returns XML errors. Parse them with:

     $errors = $notaFiscalService->parseSefasError($response);
     

4. Environment Switching

   • Always test in homologacao first. The producao environment has real financial implications.

Debugging

• Enable debug mode in bfos_nota_fiscal.yaml:

  debug: true
  

• Log raw SEFAZ responses for troubleshooting:

  Monolog\Logger::addDebugChannel('sefas');
  

Extension Points

1. Custom Services Extend NotaFiscalService to add business logic:

   class CustomNotaFiscalService extends NotaFiscalService
   {
       public function createNFeWithCustomRules(array $data)
       {
           // Add validation or transformations
           return parent::createNFe($data);
       }
   }
   

2. Event Customization Override default events in config/packages/bfos_nota_fiscal.yaml:

   events:
       nfe.created: ['App\EventListener\CustomNFeListener::onNFeCreated']
   

3. SEFAZ Endpoint Overrides For testing, override the SEFAZ URL:

   endpoints:
       nfe: 'https://homologacao.sefas.test/nfe'