Ozon Support Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require baks-dev/ozon-support
   

2. Register the Ozon Support Profile Type Run the artisan command to add the Ozon-specific user profile type:

   php artisan baks:users-profile-type:ozon-support
   

   This creates the necessary database tables and migrations for Ozon-related user profiles.

3. Configure Ozon API Credentials Add the following to your .env file:

   OZON_API_KEY=your_ozon_api_key
   OZON_API_SECRET=your_ozon_api_secret
   OZON_API_SANDBOX=false  # Set to true for sandbox testing
   

4. Publish Configuration (if needed) If the package requires additional configuration, publish and edit the config file:

   php artisan vendor:publish --provider="BaksDev\OzonSupport\OzonSupportServiceProvider"
   

   Edit the published config file at config/ozon-support.php.

5. First Use Case: Fetch Ozon Orders Use the provided service to fetch orders from Ozon:

   use BaksDev\OzonSupport\Facades\Ozon;
   
   $orders = Ozon::orders()->fetch();
   

Implementation Patterns

Usage Patterns

1. Service Facade The package provides a facade (Ozon) for easy access to Ozon API services:

   // Fetch orders
   $orders = Ozon::orders()->fetch();
   
   // Create an order
   $order = Ozon::orders()->create([
       'external_id' => 'order_123',
       'items' => [...],
   ]);
   

2. Event Listeners The package includes webhook listeners for Ozon events (e.g., order status updates). Register them in EventServiceProvider:

   protected $listen = [
       'ozon.order.created' => [
           \App\Listeners\HandleOzonOrderCreated::class,
       ],
   ];
   

3. CLI Commands Use the provided artisan commands for common tasks:

   # Sync inventory with Ozon
   php artisan ozon:inventory:sync
   
   # Test Ozon API connection
   php artisan ozon:test-connection
   

4. User Profile Integration Attach Ozon profiles to users:

   $user->ozonProfile()->create([
       'api_key' => 'user_specific_key',
       'api_secret' => 'user_specific_secret',
   ]);
   

Workflows

1. Order Management

   • Fetch orders: Ozon::orders()->fetch()
   • Create orders: Ozon::orders()->create($data)
   • Update order status: Ozon::orders()->update($orderId, $status)

2. Inventory Sync

   • Sync inventory to Ozon: php artisan ozon:inventory:sync
   • Fetch inventory from Ozon: Ozon::inventory()->fetch()

3. Webhook Handling

   • Configure Ozon webhooks in your Ozon seller account to point to your Laravel endpoint (e.g., /ozon/webhook).
   • Handle incoming webhooks in a controller:

     public function handleWebhook(Request $request)
     {
         $payload = $request->json()->all();
         event(new OzonWebhookReceived($payload));
     }
     

4. Payment Processing

   • Fetch payments: Ozon::payments()->fetch()
   • Create refunds: Ozon::payments()->refund($paymentId, $amount)

Integration Tips

1. Queue Delayed Tasks Offload API calls to queues to avoid timeouts:

   Ozon::orders()->create($data)->onQueue('ozon');
   

2. Logging Enable logging for debugging:

   config(['ozon-support.log_enabled' => true]);
   

3. Testing Use the sandbox mode for testing:

   OZON_API_SANDBOX=true
   

4. Customizing Responses Extend the package’s models or services to add custom logic:

   namespace App\Services;
   
   use BaksDev\OzonSupport\Services\OzonOrderService;
   
   class CustomOzonOrderService extends OzonOrderService
   {
       public function create(array $data)
       {
           // Custom logic before/after parent call
           return parent::create($data);
       }
   }
   

   Bind your custom service in a service provider:

   $this->app->bind(
       \BaksDev\OzonSupport\Contracts\OzonOrderService::class,
       App\Services\CustomOzonOrderService::class
   );
   

Gotchas and Tips

Pitfalls

1. OAuth2 Token Management

   • Ensure your .env has the correct OAuth2 credentials and that tokens are refreshed automatically. Monitor token expiration errors in logs.

2. Webhook Signatures

   • Ozon sends webhook payloads with HMAC signatures. Verify these signatures in your webhook handler to prevent spoofing:

     use BaksDev\OzonSupport\Helpers\OzonWebhook;
     
     $isValid = OzonWebhook::validateSignature(
         $request->header('X-Ozon-Signature'),
         $request->getContent()
     );
     

3. Rate Limiting

   • Ozon’s API has rate limits. Implement retry logic for failed requests:

     use Illuminate\Support\Facades\Http;
     
     $response = Http::withOptions(['timeout' => 30])
         ->retry(3, 100)
         ->get('https://api.ozon.ru/v3/orders');
     

4. Time Zone Handling

   • Ozon APIs return timestamps in UTC. Convert them to your local time zone if needed:

     $order->created_at->setTimezone('Europe/Moscow');
     

5. Database Conflicts

   • If you’ve previously created Ozon-related tables manually, ensure they match the package’s migrations. Run:

     php artisan migrate:fresh --env=testing
     

     in a test environment to reset the database.

Debugging

1. Enable Debug Mode Set debug to true in config/ozon-support.php to get detailed API response logs.

2. Check Logs Look for errors in storage/logs/laravel.log or enable monolog for more granular logging.

3. Test in Sandbox Always test critical operations in Ozon’s sandbox environment before going live.

4. Validate API Responses Use tools like Postman to manually test API endpoints and compare responses with the package’s output.

Config Quirks

1. Sandbox vs. Production Ensure OZON_API_SANDBOX is set correctly. Mixing sandbox and production credentials can cause unexpected errors.

2. Custom Endpoints If you need to override Ozon’s API endpoints (e.g., for testing), configure them in config/ozon-support.php:

   'api' => [
       'base_uri' => env('OZON_API_BASE_URI', 'https://api.ozon.ru'),
   ],
   

3. User Profile Scoping The package uses user profiles to scope Ozon API calls. Ensure users have the correct profile attached:

   $user->ozonProfile()->firstOrFail();
   

Extension Points

1. Custom Services Override the package’s services by binding your custom implementations in a service provider:

   $this->app->bind(
       \BaksDev\OzonSupport\Contracts\OzonOrderService::class,
       App\Services\CustomOzonOrderService::class
   );
   

2. Event Extensions Listen to Ozon events and extend their behavior:

   Ozon::orders()->created(function ($order) {
       // Custom logic after order creation
   });
   

3. Webhook Extensions Add custom webhook handlers by extending the OzonWebhookHandler class:

   namespace App\Handlers;
   
   use BaksDev\OzonSupport\Handlers\OzonWebhookHandler;
   
   class CustomOzonWebhookHandler extends OzonWebhookHandler
   {
       public function handleOrderCreated(array $payload)
       {
           // Custom logic
       }
   }
   

   Bind your custom handler in a service provider.

4. API Response Transformers Modify how API responses are transformed into Laravel models by extending the OzonTransformer class:

   namespace App\Transformers;
   
   use BaksDev\OzonSupport\Transformers\OzonTransformer;
   
   class CustomOzonTransformer extends OzonTransformer
   {
       public function transformOrder(array $data)
       {
           // Custom transformation logic
           return parent::transformOrder($data);
       }
   }
   

   Bind your custom transformer in a service provider.

5. CLI Command Extensions Extend existing artisan commands or create new ones by publishing the package’s commands and customizing them: