Ozon Promotion Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/ozon-promotion
   

   Ensure your php version is 8.4+ (check via php -v).

2. Publish Config Publish the default configuration to config/ozon-promotion.php:

   php artisan vendor:publish --provider="BaksDev\OzonPromotion\OzonPromotionServiceProvider" --tag="config"
   

   Key config fields to verify:

   • api_key (Ozon API credentials)
   • default_campaign_id (fallback campaign ID)
   • debug (enable for API debugging)

3. First Use Case: Fetching Promotions Inject the OzonPromotion facade into a controller/service:

   use BaksDev\OzonPromotion\Facades\OzonPromotion;
   
   public function getPromotions() {
       $promotions = OzonPromotion::getPromotions(['campaign_id' => 123]);
       return response()->json($promotions);
   }
   

   • Default endpoint: GET /api/promotions
   • Required params: campaign_id (or use default_campaign_id from config).

Implementation Patterns

Core Workflows

1. Campaign Management

   • Create/Update Campaigns:

     OzonPromotion::createCampaign([
         'name' => 'Summer Sale',
         'budget' => 1000,
         'start_date' => now()->addDays(3),
         'end_date' => now()->addDays(10),
     ]);
     

   • Fetch Campaigns:

     $campaigns = OzonPromotion::getCampaigns(['status' => 'active']);
     

2. Product Promotion

   • Add Products to Campaign:

     OzonPromotion::addProductsToCampaign(123, [1001, 1002, 1003]);
     

   • Bulk Operations:

     OzonPromotion::bulkUpdatePromotions([
         ['product_id' => 1001, 'discount' => 15],
         ['product_id' => 1002, 'discount' => 20],
     ]);
     

3. Reporting

   • Generate Reports:

     $report = OzonPromotion::getReport('daily', '2024-01-01', '2024-01-31');
     

   • Export to CSV:

     $csv = OzonPromotion::exportReportToCsv($report);
     

Integration Tips

• Queue Delayed Tasks: Use Laravel’s queue system for bulk operations (e.g., OzonPromotion::bulkUpdatePromotions()):

  OzonPromotion::dispatchBulkUpdate([...], now()->addMinutes(5));
  

• Event Listeners: Hook into Ozon’s webhooks (e.g., promotion.approved) via Laravel’s HandleOzonWebhook event listener. Example listener:

  public function handle(OzonPromotionApproved $event) {
      // Update local DB or trigger notifications
  }
  

• Caching: Cache frequent API calls (e.g., promotions list) with tags:

  Cache::tags(['ozon_promotions'])->remember('promotions_123', now()->addHours(1), fn() =>
      OzonPromotion::getPromotions(['campaign_id' => 123])
  );
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Ozon’s API enforces 60 requests/minute. Use OzonPromotion::throttle() to manage bursts:

     OzonPromotion::throttle(10, function() {
         // Rate-limited batch processing
     });
     

   • Debugging: Enable debug: true in config to log API responses/errors.

2. Timezone Mismatches

   • Ozon expects dates in UTC. Convert Laravel’s Carbon instances:

     $ozonDate = $carbonInstance->setTimezone('UTC')->toIso8601String();
     

3. Product ID Formats

   • Ozon uses string IDs (e.g., "1001"), not integers. Validate inputs:

     $productIds = array_map('strval', $request->input('product_ids'));
     

4. Webhook Verification

   • Ozon sends webhooks with a signature header. Validate using:

     if (!OzonPromotion::verifyWebhookSignature($request->getContent(), $request->header('signature'))) {
         abort(403);
     }
     

Debugging

• Enable API Logging: Set debug: true in config to log raw API requests/responses to storage/logs/ozon-promotion.log.
• Mock API Calls: Use the OzonPromotion::fake() method for testing:

  OzonPromotion::fake([
      'getPromotions' => ['promotions' => []],
  ]);
  

Extension Points

1. Custom API Clients Extend BaksDev\OzonPromotion\Clients\OzonClient to add endpoints:

   class CustomOzonClient extends OzonClient {
       public function getCustomData($param) {
           return $this->get("custom-endpoint", $param);
       }
   }
   

   Register in config/ozon-promotion.php:

   'client' => \App\Services\CustomOzonClient::class,
   

2. Local Overrides Override default responses in app/Providers/OzonPromotionServiceProvider.php:

   public function boot() {
       OzonPromotion::macro('customMethod', function() {
           return "Overridden!";
       });
   }
   

3. Database Sync Use Laravel’s OzonPromotionSyncer to sync local DB with Ozon’s API:

   OzonPromotion::syncCampaignsToLocal();