Overenozakazniky Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require heureka/overeno-zakazniky
   

2. Initialize the client with your API key (from Heureka's service admin):

   $certification = new \Heureka\ShopCertification('your_api_key_here');
   

   For SK shops, specify the service:

   $certification = new \Heureka\ShopCertification('your_api_key_here', [
       'service' => \Heureka\ShopCertification::HEUREKA_SK
   ]);
   

First Use Case: Logging an Order

// Set customer email (required)
$certification->setEmail('customer@example.com');

// Set order ID (optional but recommended)
$certification->setOrderId(12345);

// Add product ITEM_IDs (optional but recommended for tracking)
$certification->addProductItemId('PROD123');
$certification->addProductItemId('PROD456');

// Execute the request
$response = $certification->logOrder();

Key files to reference:

• examples/ folder for ready-to-use examples.
• src/Heureka/ShopCertification.php for core logic.
• src/Heureka/Exceptions/ for error handling.

Implementation Patterns

1. Order Logging Workflow

Typical Laravel integration (e.g., in an OrderService or OrderObserver):

use Heureka\ShopCertification;
use Illuminate\Support\Facades\Log;

class OrderService {
    protected $certification;

    public function __construct() {
        $this->certification = new ShopCertification(config('heureka.api_key'), [
            'service' => config('heureka.service', ShopCertification::HEUREKA_CZ)
        ]);
    }

    public function logOrderToHeureka($order) {
        $this->certification->setEmail($order->email);
        $this->certification->setOrderId($order->id);

        foreach ($order->products as $product) {
            $this->certification->addProductItemId($product->heureka_item_id);
        }

        try {
            $response = $this->certification->logOrder();
            Log::info('Heureka certification logged', ['response' => $response]);
        } catch (\Heureka\Exceptions\RequesterException $e) {
            Log::error('Heureka certification failed', ['error' => $e->getMessage()]);
            // Optionally: Retry or notify admin
        }
    }
}

2. Event-Driven Integration

Trigger logging after an order.placed event:

// In EventServiceProvider
protected $listen = [
    'order.placed' => [
        'App\Listeners\LogOrderToHeureka',
    ],
];

3. Batch Processing

For bulk orders (e.g., via queue jobs):

class HeurekaBatchLogger {
    public function logBatch($orderIds) {
        $certification = new ShopCertification(config('heureka.api_key'));

        foreach ($orderIds as $orderId) {
            $order = Order::find($orderId);
            $certification->setEmail($order->email);
            $certification->setOrderId($orderId);

            // Reset product IDs for each order
            $certification->resetProductItemIds();
            foreach ($order->products as $product) {
                $certification->addProductItemId($product->heureka_item_id);
            }

            $certification->logOrder();
        }
    }
}

4. Configuration Management

Store API keys and settings in .env:

HEUREKA_API_KEY=your_api_key_here
HEUREKA_SERVICE=cz  # or 'sk'

Load via Laravel config:

// config/heureka.php
return [
    'api_key' => env('HEUREKA_API_KEY'),
    'service' => env('HEUREKA_SERVICE', \Heureka\ShopCertification::HEUREKA_CZ),
];

5. Testing

Mock the client in unit tests:

$mock = Mockery::mock('\Heureka\ShopCertification[logOrder]');
$mock->shouldReceive('logOrder')->once()->andReturn(['code' => 200]);

Gotchas and Tips

Common Pitfalls

1. Wrong API Key for Region

   • Error: 401 Unauthorized with "Unknown API key".
   • Fix: Ensure you use the CZ or SK key matching your service parameter.

     $certification = new ShopCertification('cz_key', ['service' => ShopCertification::HEUREKA_CZ]);
     

2. Invalid JSON Payload

   • Error: 400 Bad Request.
   • Fix: Validate your data before sending:

     $data = [
         'apiKey' => $certification->getApiKey(),
         'email' => $certification->getEmail(),
         'orderId' => $certification->getOrderId(),
         'productItemIds' => $certification->getProductItemIds(),
     ];
     json_encode($data); // Test if valid
     

3. Missing Content-Type Header

   • Error: 415 Unsupported Media Type.
   • Fix: The package handles this automatically, but ensure no middleware (e.g., Laravel's VerifyCsrfToken) interferes.

4. Duplicate Product IDs

   • Error: DuplicateProductItemIdException.
   • Fix: Use addProductItemId() only once per product or reset IDs between orders:

     $certification->resetProductItemIds();
     

5. Order ID as String vs. Integer

   • Gotcha: The API accepts both, but older versions may fail with integers.
   • Fix: Cast to string if unsure:

     $certification->setOrderId((string) $order->id);
     

6. Timeouts

   • Issue: Slow responses may time out.
   • Fix: Adjust the timeout in the constructor (since v4.0.1):

     $certification = new ShopCertification('key', [
         'service' => ShopCertification::HEUREKA_CZ,
         'timeout' => 10, // seconds
     ]);
     

Debugging Tips

1. Enable Guzzle Debugging Add this to your ShopCertification constructor to log requests:

   $client = new \GuzzleHttp\Client([
       'debug' => fopen('heureka_debug.log', 'w'),
   ]);
   

2. Validate Heureka Item IDs Ensure ITEM_ID matches your Heureka XML feed (case-sensitive, no spaces).

3. Check Email Format Invalid emails (e.g., missing @) may cause silent failures. Validate with:

   if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
       throw new \InvalidArgumentException("Invalid email: $email");
   }
   

4. Handle Exceptions Gracefully Catch specific exceptions:

   try {
       $certification->logOrder();
   } catch (\Heureka\Exceptions\RequesterException $e) {
       // Log or retry
   } catch (\Heureka\Exceptions\DuplicateProductItemIdException $e) {
       // Handle duplicates
   }
   

Extension Points

1. Custom Request Handler Override the HTTP client for logging/retries:

   $certification = new ShopCertification('key', [
       'handler' => \GuzzleHttp\HandlerStack::create(),
   ]);
   

2. Add Metadata Extend the payload with custom fields (if Heureka supports them):

   $certification->setAdditionalData(['custom_field' => 'value']);
   

3. Queue Failed Orders Use Laravel Queues to retry failed requests:

   try {
       $certification->logOrder();
   } catch (\Exception $e) {
       LogOrderToHeurekaJob::dispatch($order)->delay(now()->addMinute());
   }
   

4. Local Testing Mock the API endpoint for development:

   // In phpunit.xml
   <env name="HEUREKA_API_URL" value="http://localhost:8000/mock-heureka"/>
   

Configuration Quirks

• PHP Version: Requires PHP ≥7.3 (since v4.0.0). Use composer require php:^7.3 if needed.
• Service Parameter: Must be one of:

  \Heureka\ShopCertification::HEUREKA_CZ // Default
  \Heureka\ShopCertification::HEUREKA_SK
  

• Product IDs: Optional but highly recommended for accurate tracking. Omitting them logs the order without product context.