Symfony Ticketbai Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require apabolleta/symfony-ticketbai
   

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Apabolleta\TicketBAIBundle\APMTicketBAIBundle::class => ['all' => true],
   ];
   

3. Configure the Bundle Publish the default config:

   php bin/console config:dump-reference APMTicketBAIBundle
   

   Update config/packages/apm_ticketbai.yaml with your TicketBAI credentials (e.g., client_id, client_secret, sandbox_mode).

4. First Use Case: Generate a Ticket Inject the TicketBAIClient service and call:

   use Apabolleta\TicketBAIBundle\Client\TicketBAIClient;
   
   public function __construct(private TicketBAIClient $ticketBAIClient) {}
   
   public function generateTicket(float $amount, string $concept): string
   {
       $ticket = $this->ticketBAIClient->createTicket($amount, $concept);
       return $ticket->getTicketId();
   }
   

Implementation Patterns

Core Workflows

1. Ticket Creation Use TicketBAIClient to generate tickets with metadata:

   $ticket = $this->ticketBAIClient->createTicket(
       100.50, // Amount
       "Venta de servicios", // Concept
       [
           'customer' => ['name' => 'John Doe', 'vat' => 'ES12345678A'],
           'invoice' => ['series' => 'A', 'number' => '123'],
       ]
   );
   

2. Validation & Submission Validate tickets before submission:

   $validator = $this->ticketBAIClient->getValidator();
   $errors = $validator->validate($ticket);
   if ($errors->count() === 0) {
       $this->ticketBAIClient->submitTicket($ticket);
   }
   

3. Sandbox Mode Enable in config for testing:

   apm_ticketbai:
       sandbox_mode: true
   

Integration Tips

• Event Listeners Hook into ticketbai.ticket.created or ticketbai.ticket.submitted events:

  // src/EventListener/TicketBAIListener.php
  public function onTicketCreated(TicketCreatedEvent $event)
  {
      // Log or process the ticket
  }
  

• Doctrine Entities Map tickets to entities for persistence:

  use Apabolleta\TicketBAIBundle\Entity\Ticket;
  
  #[ORM\Entity]
  class Invoice {
      #[ORM\OneToOne(targetEntity: Ticket::class, cascade: ['persist'])]
      private ?Ticket $ticket = null;
  }
  

• API Responses Handle responses with DTOs:

  use Apabolleta\TicketBAIBundle\DTO\TicketResponse;
  
  public function handleResponse(TicketResponse $response): void
  {
      if ($response->isSuccess()) {
          // Process success
      }
  }
  

Gotchas and Tips

Pitfalls

1. Sandbox vs. Production

   • Forgetting to disable sandbox_mode in production causes failed submissions.
   • Fix: Use environment variables or separate configs:

     # config/packages/apm_ticketbai_%env(default::prod).yaml
     apm_ticketbai:
         sandbox_mode: "%env(bool:TICKETBAI_SANDBOX)%"
     

2. Validation Errors

   • TicketBAI returns cryptic validation errors. Use the Validator service to decode them:

     $errors = $validator->validate($ticket);
     foreach ($errors as $error) {
         // Log or display: $error->getMessage()
     }
     

3. Rate Limits

   • TicketBAI enforces request limits. Cache responses or implement retries:

     use Symfony\Contracts\HttpClient\Exception\RateLimited;
     use Symfony\Contracts\HttpClient\HttpClientInterface;
     
     try {
         $response = $httpClient->request('POST', $url);
     } catch (RateLimited $e) {
         sleep(10); // Retry after delay
         retry();
     }
     

Debugging

• Enable Debug Mode Set debug: true in config to log raw API responses:

  apm_ticketbai:
      debug: true
  

• HTTP Client Logging Configure Symfony’s HTTP client to log requests:

  // config/packages/http_client.yaml
  framework:
      http_client:
          default_options:
              headers:
                  'X-DEBUG-TOKEN': 'your_token' # For Symfony Profiler
  

Extension Points

1. Custom Fields Extend the Ticket entity to add custom metadata:

   use Apabolleta\TicketBAIBundle\Entity\Ticket;
   
   class CustomTicket extends Ticket {
       private ?string $customField = null;
   
       public function getCustomField(): ?string { return $this->customField; }
   }
   

2. Webhook Handling Implement a controller to receive TicketBAI webhooks:

   #[Route('/ticketbai/webhook', name: 'ticketbai_webhook', methods: ['POST'])]
   public function handleWebhook(Request $request, TicketBAIClient $client): Response
   {
       $client->processWebhook($request->getContent());
       return new Response('OK');
   }
   

3. Batch Processing Use the BatchProcessor service for bulk operations:

   $processor = $this->ticketBAIClient->getBatchProcessor();
   $results = $processor->process([$ticket1, $ticket2]);