Yandex Market Orders Laravel Package

Getting Started

Minimal Steps to First Order Sync

1. Install Dependencies:

   composer require baks-dev/yandex-market baks-dev/yandex-market-orders
   

2. Configure Yandex Market Profile: Choose your marketplace model (FBS/DBS) and run:

   # For FBS (Fulfillment by Seller)
   php bin/console baks:users-profile-type:yandex-market-fbs
   php bin/console baks:payment:yandex-market-fbs
   php bin/console baks:delivery:yandex-market-fbs
   
   # For DBS (Delivery by Seller)
   php bin/console baks:users-profile-type:yandex-market-dbs
   php bin/console baks:payment:yandex-market-dbs
   php bin/console baks:delivery:yandex-market-dbs
   

3. Set Up Database Schema:

   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. Configure API Credentials: Add Yandex Market API credentials to .env:

   YANDEX_MARKET_FBS_TOKEN=your_fbs_token_here
   YANDEX_MARKET_DBS_TOKEN=your_dbs_token_here
   YANDEX_KASSA_SECRET_KEY=your_kassa_secret_key
   

5. First Order Sync: Use the package's service to fetch and process orders:

   use BaksDev\YandexMarketOrders\Services\YandexMarketOrderService;
   
   $orderService = app(YandexMarketOrderService::class);
   $orders = $orderService->fetchOrders(); // Fetches pending orders from Yandex Market
   foreach ($orders as $order) {
       $orderService->processOrder($order); // Syncs order to your Laravel app
   }
   

6. Verify Webhooks (if applicable): Ensure your Laravel app is configured to handle Yandex Market webhooks for real-time updates.

Implementation Patterns

Core Workflow: Order Processing

1. Fetch Orders: Use YandexMarketOrderService to pull orders from Yandex Market:

   $service = app(YandexMarketOrderService::class);
   $orders = $service->fetchOrders(['status' => 'new']);
   

2. Process Orders: Map Yandex Market orders to your Laravel order model:

   foreach ($orders as $yandexOrder) {
       $laravelOrder = $service->createOrderFromYandex($yandexOrder);
       // Custom logic (e.g., inventory check, email notification)
       event(new OrderProcessed($laravelOrder));
   }
   

3. Update Order Status: Sync status back to Yandex Market:

   $service->updateOrderStatus($yandexOrderId, 'shipped');
   

Payment Integration

1. Configure Yandex.Kassa: Use the payment command to set up Yandex.Kassa integration:

   php bin/console baks:payment:yandex-market-fbs
   

2. Handle Webhooks: Create a Laravel route to handle Yandex.Kassa payment notifications:

   Route::post('/yandex-kassa/webhook', [YandexKassaWebhookController::class, 'handle']);
   

3. Process Payments:

   use BaksDev\YandexMarketOrders\Services\YandexMarketPaymentService;
   
   $paymentService = app(YandexMarketPaymentService::class);
   $payment = $paymentService->capturePayment($orderId, $amount);
   

Delivery Integration

1. Configure Delivery: Run the delivery command for your model:

   php bin/console baks:delivery:yandex-market-fbs
   

2. Update Delivery Status:

   use BaksDev\YandexMarketOrders\Services\YandexMarketDeliveryService;
   
   $deliveryService = app(YandexMarketDeliveryService::class);
   $deliveryService->updateDeliveryStatus($orderId, 'delivered');
   

Event-Driven Extensions

Leverage Laravel events to extend functionality:

// In EventServiceProvider
protected $listen = [
    \BaksDev\YandexMarketOrders\Events\OrderCreated::class => [
        \App\Listeners\SendOrderConfirmation::class,
        \App\Listeners\UpdateInventory::class,
    ],
];

CLI Automation

Automate order syncs with Laravel tasks:

# Sync orders every 5 minutes
* * * * * cd /path-to-project && php artisan yandex:market:orders:sync --env=production

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • The package includes its own migrations for orders, payments, and deliveries. If your app already has similar tables, conflicts may arise.
   • Fix: Review baks:assets:install output and manually merge schemas if needed.

2. Webhook Handling:

   • Yandex Market and Yandex.Kassa rely on webhooks for real-time updates. If not configured, order/payment statuses may desync.
   • Fix: Ensure your Laravel app has routes for:

     /yandex-market/webhook
     /yandex-kassa/webhook
     

3. API Rate Limits:

   • Yandex Market API has rate limits. Bulk operations may fail if not throttled.
   • Fix: Implement retries with exponential backoff in your YandexMarketOrderService:

     try {
         $orders = $client->fetchOrders();
     } catch (RateLimitExceededException $e) {
         sleep(2 ** $attempt);
         retry();
     }
     

4. Token Management:

   • API tokens (FBS/DBS/Yandex.Kassa) must be securely stored and rotated periodically.
   • Fix: Use Laravel's env or a secrets manager (e.g., AWS Secrets Manager).

5. Time Zone Mismatches:

   • Yandex Market uses UTC, but your app might use a different timezone. Order timestamps may appear off.
   • Fix: Normalize timestamps in your service layer:

     $order->created_at = $yandexOrder->created_at->setTimezone('UTC');
     

Debugging Tips

1. Enable Debug Logging: Add to config/logging.php:

   'channels' => [
       'yandex' => [
           'driver' => 'single',
           'path' => storage_path('logs/yandex-market.log'),
           'level' => 'debug',
       ],
   ],
   

   Then log API responses:

   \Log::channel('yandex')->debug('API Response', ['data' => $response]);
   

2. Test with Sandbox: Use Yandex Market's sandbox environment before going live:

   $client = new YandexMarketClient([
       'token' => 'sandbox_token',
       'endpoint' => 'https://sandbox.api.yandex.ru/...',
   ]);
   

3. Validate Webhooks Locally: Test webhook payloads with Laravel's artisan serve and tools like ngrok:

   ngrok http 8000
   

   Then configure Yandex Market to send webhooks to your ngrok.io URL.

Extension Points

1. Custom Order Processing: Override the default order service:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->bind(
           \BaksDev\YandexMarketOrders\Services\YandexMarketOrderService::class,
           \App\Services\CustomYandexMarketOrderService::class
       );
   }
   

2. Add Custom Fields: Extend the order model to include Yandex-specific fields:

   use BaksDev\YandexMarketOrders\Models\YandexMarketOrder;
   
   class CustomYandexMarketOrder extends YandexMarketOrder
   {
       protected $casts = [
           'yandex_tracking_number' => 'string',
           'yandex_delivery_cost' => 'float',
       ];
   }
   

3. Modify Payment Logic: Extend the payment service to add custom validation:

   use BaksDev\YandexMarketOrders\Services\YandexMarketPaymentService;
   
   class CustomYandexMarketPaymentService extends YandexMarketPaymentService
   {
       public function capturePayment($orderId, $amount)
       {
           // Custom logic (e.g., fraud check)
           if ($this->isFraudulent($orderId)) {
               throw new \RuntimeException('Fraud detected');
           }
           return parent::capturePayment($orderId, $amount);
       }
   }
   

4. Add New Delivery Methods: