Colissimo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require ekyna/colissimo-bundle
   

   Register the bundle in config/app.php under providers:

   Ekyna\ColissimoBundle\ColissimoBundle::class,
   

2. Publish Configuration Publish the default config to config/colissimo.php:

   php artisan vendor:publish --provider="Ekyna\ColissimoBundle\ColissimoBundle" --tag="config"
   

3. Basic Usage Inject the ColissimoClient service into a controller or service:

   use Ekyna\ColissimoBundle\Client\ColissimoClient;
   
   public function __construct(private ColissimoClient $colissimo) {}
   

   Fetch a tracking label:

   $tracking = $this->colissimo->getTrackingLabel('12345678901234567890');
   

Implementation Patterns

Workflow: Shipping Label Generation

1. Fetch Rates Use the getShippingRates method to retrieve available Colissimo shipping options:

   $rates = $this->colissimo->getShippingRates(
       $senderAddress,
       $recipientAddress,
       $packageWeight,
       $packageDimensions
   );
   

   Tip: Cache rates for 15 minutes to avoid API rate limits.

2. Create Shipment Generate a shipment object with selected rate:

   $shipment = $this->colissimo->createShipment($rateId, $orderItems);
   

3. Print Label Download and print the label:

   $label = $this->colissimo->generateLabel($shipment);
   file_put_contents('label.pdf', $label);
   

Integration with EkynaCommerceBundle

• Order Events Listen to order.shipped events to auto-generate labels:

  event(new OrderShipped($order));
  

  Use the ColissimoService to handle label generation:

  $this->colissimo->processOrderShipment($order);
  

• Admin Panel Extend the EkynaCommerceBundle admin to display Colissimo tracking:

  $tracking = $this->colissimo->getTrackingInfo($order->trackingNumber);
  return view('admin.order.show', compact('tracking'));
  

API Rate Limiting

• Batch Processing For bulk orders, use the batchGenerateLabels method:

  $labels = $this->colissimo->batchGenerateLabels($orderIds);
  

Gotchas and Tips

Configuration Quirks

• API Credentials Ensure colissimo.php has valid client_id and client_secret:

  'api' => [
      'client_id' => env('COLISSIMO_CLIENT_ID'),
      'client_secret' => env('COLISSIMO_CLIENT_SECRET'),
  ],
  

  Tip: Use Laravel's .env for sensitive data.

• Endpoint Overrides Customize the API endpoint if using a sandbox:

  'api' => [
      'endpoint' => env('COLISSIMO_API_ENDPOINT', 'https://api.colissimo.fr'),
  ],
  

Debugging

• API Errors Enable debug mode in config:

  'debug' => env('APP_DEBUG', false),
  

  Check logs for ColissimoException details.

• Rate Limits Monitor HTTP 429 responses. Implement exponential backoff:

  try {
      $this->colissimo->getShippingRates(...);
  } catch (RateLimitExceededException $e) {
      sleep($e->getRetryAfter());
      retry();
  }
  

Extension Points

• Custom Shipping Methods Extend ColissimoShippingMethod to add logic:

  class CustomColissimoMethod extends ColissimoShippingMethod {
      public function isAvailable(Order $order) {
          return $order->isInternational();
      }
  }
  

• Webhook Handling Implement ColissimoWebhookListener to process Colissimo callbacks:

  public function handleShipmentStatusUpdate(Shipment $shipment) {
      $order = $shipment->getOrder();
      $order->updateTrackingStatus($shipment->getStatus());
  }
  

Performance Tips

• Caching Cache API responses for 15 minutes:

  Cache::remember("colissimo_rates_{$cacheKey}", 900, function() use ($params) {
      return $this->colissimo->getShippingRates(...$params);
  });
  

• Async Processing Use Laravel Queues for label generation:

  GenerateColissimoLabel::dispatch($order)->delay(now()->addMinute());