Wildberries Support Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/wildberries-support
   

2. Basic Usage:

   use BaksDev\Wildberries\Support\Facades\WildberriesSupport;
   
   // Initialize with credentials (check if .env support is added in v7.4.19)
   WildberriesSupport::setCredentials(
       env('WILDBERRIES_API_KEY'),
       env('WILDBERRIES_SECRET_KEY')
   );
   
   // Example: Fetch orders (verify method exists in v7.4.19)
   $orders = WildberriesSupport::getOrders(['limit' => 10]);
   

3. First Use Case:

   • Sync a single order status to your database:

     $order = WildberriesSupport::getOrderById(12345);
     Order::updateOrCreate(
         ['external_id' => $order['id']],
         ['status' => $order['status'], 'updated_at' => now()]
     );
     

Where to Look First

• Source Code: vendor/baks-dev/wildberries-support/src/ for method signatures and undocumented features.
• Tests: Run php bin/phpunit --group=wildberries-support to see real-world usage patterns.
• GitHub Issues: Check for open bugs or feature requests (e.g., webhook support).

Implementation Patterns

Core Workflows

1. Order Management:

   // Fetch orders with pagination
   $orders = WildberriesSupport::getOrders(['page' => 1, 'per_page' => 50]);
   
   // Update order status (verify method in v7.4.19)
   WildberriesSupport::updateOrderStatus(12345, 'shipped');
   

2. Catalog Integration:

   // Add/Update products
   WildberriesSupport::addProduct([
       'name' => 'Test Product',
       'price' => 999,
       'stock' => 100,
   ]);
   
   // Fetch product by ID
   $product = WildberriesSupport::getProduct(67890);
   

3. Support Tickets:

   // Create a support ticket
   $ticket = WildberriesSupport::createTicket([
       'subject' => 'Order Issue',
       'message' => 'Delivery delayed',
       'order_id' => 12345,
   ]);
   
   // Fetch ticket updates
   $updates = WildberriesSupport::getTicketUpdates($ticket['id']);
   

Laravel Integration Tips

1. Service Provider Wrapper:

   // Register in AppServiceProvider
   $this->app->singleton('wildberries', function () {
       return new \BaksDev\Wildberries\Support\Client(
           env('WILDBERRIES_API_KEY'),
           env('WILDBERRIES_SECRET_KEY')
       );
   });
   

2. Queue Jobs for Async Operations:

   // Sync orders job
   class SyncWildberriesOrders implements ShouldQueue
   {
       public function handle()
       {
           $orders = WildberriesSupport::getOrders();
           foreach ($orders as $order) {
               Order::updateOrCreate(
                   ['external_id' => $order['id']],
                   ['status' => $order['status']]
               );
           }
       }
   }
   

3. Event Listeners for Webhooks (if supported in v7.4.19):

   // Example: Handle order status updates
   public function handle(OrderStatusUpdated $event)
   {
       WildberriesSupport::updateOrderStatus(
           $event->order->external_id,
           $event->newStatus
       );
   }
   

4. API Rate Limit Handling:

   // Retry logic for rate-limited endpoints
   try {
       $response = WildberriesSupport::getOrders();
   } catch (\BaksDev\Wildberries\Support\Exceptions\RateLimitExceeded $e) {
       sleep($e->retryAfter);
       retry();
   }
   

Data Mapping Patterns

1. Normalize Wildberries Responses:

   $order = WildberriesSupport::getOrder(12345);
   $normalized = [
       'id' => $order['id'],
       'status' => $order['status'],
       'created_at' => Carbon::parse($order['created_at']),
       'items' => collect($order['items'])->map(function ($item) {
           return [
               'product_id' => $item['product_id'],
               'quantity' => $item['quantity'],
           ];
       }),
   ];
   

2. Bulk Operations with Chunking:

   WildberriesSupport::getOrders(['limit' => 1000])->chunk(100, function ($chunk) {
       foreach ($chunk as $order) {
           // Process each order
       }
   });
   

Gotchas and Tips

Pitfalls

1. Authentication Quirks:

   • Issue: Credentials may not persist between requests in v7.4.19.
   • Fix: Manually set credentials before each operation or create a wrapper:

     class WildberriesWrapper {
         public function __call($method, $args) {
             WildberriesSupport::setCredentials(
                 env('WILDBERRIES_API_KEY'),
                 env('WILDBERRIES_SECRET_KEY')
             );
             return WildberriesSupport::$method(...$args);
         }
     }
     

2. Response Format Changes:

   • Issue: v7.4.19 may alter response structures (e.g., nested arrays flattened).
   • Fix: Compare responses with Wildberries’ official API docs and update your mapping logic.

3. Undocumented Methods:

   • Issue: Some methods may exist but lack documentation.
   • Fix: Use php artisan tinker to explore:

     \BaksDev\Wildberries\Support\Facades\WildberriesSupport::getAvailableMethods();
     

4. Rate Limits:

   • Issue: Wildberries enforces strict rate limits (e.g., 100 requests/minute).
   • Fix: Implement exponential backoff:

     use Symfony\Component\Routing\Exception\ResourceNotFoundException;
     
     try {
         $response = WildberriesSupport::getOrders();
     } catch (ResourceNotFoundException $e) {
         if ($e->getCode() === 429) {
             sleep(60); // Wait 1 minute
             retry();
         }
     }
     

5. Webhook Delays:

   • Issue: If v7.4.19 introduces webhooks, Wildberries may delay delivery.
   • Fix: Implement a retry queue job for unprocessed webhooks.

Debugging Tips

1. Enable Verbose Logging:

   WildberriesSupport::setLogLevel(\Monolog\Logger::DEBUG);
   

2. Mock HTTP Calls in Tests:

   use Illuminate\Support\Facades\Http;
   
   Http::fake([
       'api.wildberries.ru/orders' => Http::response(['data' => []], 200),
   ]);
   
   $orders = WildberriesSupport::getOrders();
   

3. Inspect Raw Responses:

   $response = WildberriesSupport::getOrders(['debug' => true]);
   // $response now includes raw HTTP data
   

Extension Points

1. Custom Response Transformers:

   WildberriesSupport::setTransformer('orders', function ($data) {
       return collect($data)->map(function ($order) {
           return [
               'id' => $order['id'],
               'formatted_date' => Carbon::parse($order['created_at'])->format('Y-m-d H:i:s'),
           ];
       });
   });
   

2. Add New Endpoints:

   // Extend the client class
   namespace App\Services;
   
   use BaksDev\Wildberries\Support\Client;
   
   class ExtendedWildberriesClient extends Client
   {
       public function getCustomerReviews($orderId)
       {
           return $this->request('GET', "/orders/{$orderId}/reviews");
       }
   }
   

3. Override Default Config:

   // In config/wildberries.php
   'defaults' => [
       'timeout' => 30, // Override default timeout
       'retry_attempts' => 3,
   ],
   

Configuration Quirks

1. Environment Variables:

   • Issue: v7.4.19 may not fully support .env variables.
   • Fix: Hardcode credentials in a config file or use a wrapper:

     config(['wildberries.credentials' => [
         'key' => env('WILDBERRIES_API_KEY'),
         'secret' => env('WILDBERRIES_SECRET_KEY'),
     ]]);
     

2. Default Headers:

   • Issue: Missing Accept-Language or User-Agent headers may cause issues.
   • Fix: Add them globally:

     WildberriesSupport::setDefaultHeaders([
         'Accept-Language' => 'ru-RU',
         '