Getting Started

Minimal Steps to First Use

Install the Package

composer require baks-dev/wildberries-orders

Run Setup Commands Choose either FBS (Fulfillment by Seller) or DBS (Delivery by Seller):

# For FBS
php bin/console baks:users-profile-type:wildberries-fbs
php bin/console baks:payment:wildberries-fbs
php bin/console baks:delivery:wildberries-fbs

# For DBS
php bin/console baks:users-profile-type:wildberries-dbs
php bin/console baks:payment:wildberries-dbs
php bin/console baks:delivery:wildberries-dbs

Install Assets and Migrate

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

Configure API Credentials Add Wildberries API keys to your .env file:

WILDBERRIES_API_KEY=your_api_key_here
WILDBERRIES_API_SECRET=your_api_secret_here

First Order Test Use the package’s service to create a test order:

use BaksDev\WildberriesOrders\Facades\WildberriesOrder;

$order = WildberriesOrder::create([
    'profile_type' => 'wildberries-fbs', // or 'wildberries-dbs'
    'items' => [
        ['sku' => '12345', 'quantity' => 2],
    ],
    'customer' => ['email' => '[email protected]', 'phone' => '+79991234567'],
]);

Implementation Patterns

Core Workflows

1. Order Management

Create Orders Use the facade or service container to generate orders for Wildberries:

$order = WildberriesOrder::create([
    'profile_type' => 'wildberries-fbs',
    'items' => [...],
    'customer' => [...],
    'shipping' => [...],
]);

Fetch Orders Retrieve orders from Wildberries:

$orders = WildberriesOrder::fetchOrders(['status' => 'new']);

Update Order Status Sync status changes back to Wildberries:
```
WildberriesOrder::updateStatus($orderId, 'shipped');
```

2. Payment Processing

Initialize Payment Bind payments to Wildberries profiles:

$payment = WildberriesPayment::create([
    'order_id' => $orderId,
    'amount' => 1000.00,
    'currency' => 'RUB',
]);

Capture Payment Process payments via Wildberries:
```
$payment->capture();
```

3. Delivery Integration

Assign Delivery Method Configure delivery profiles for FBS/DBS:

$delivery = WildberriesDelivery::assign($orderId, 'wildberries-fbs');

Track Shipments Sync shipment updates:

$tracking = WildberriesDelivery::track($orderId);

4. Console-Driven Setup

Profile Types Register Wildberries-specific user profiles:

php bin/console baks:users-profile-type:wildberries-fbs

Payment/Delivery Profiles Bind payment and delivery methods:

php bin/console baks:payment:wildberries-fbs
php bin/console baks:delivery:wildberries-fbs

Integration Tips

Laravel Service Binding

Bind the package’s services in config/app.php or a service provider:

$app->bind('wildberries.order', function ($app) {
    return new \BaksDev\WildberriesOrders\Services\WildberriesOrderService(
        $app['wildberries.api.client']
    );
});

Event Listeners

Extend order lifecycle events (e.g., OrderCreated, PaymentProcessed) to trigger custom logic:

// app/Listeners/WildberriesOrderListener.php
public function handle(OrderCreated $event) {
    if ($event->order->profile_type === 'wildberries-fbs') {
        WildberriesOrder::createFromLaravel($event->order);
    }
}

API Client Customization

Override the default API client (e.g., for logging or retry logic):

$app->bind('wildberries.api.client', function ($app) {
    return new \BaksDev\WildberriesOrders\Clients\WildberriesApiClient(
        $app['http.client'],
        config('wildberries.api.timeout')
    );
});

Queue-Based Processing

Offload API calls to queues for scalability:

// Dispatch an order creation job
CreateWildberriesOrder::dispatch($orderData)->onQueue('wildberries');

Gotchas and Tips

Pitfalls

Schema Conflicts
- The package introduces tables like wildberries_orders, wildberries_payments, and wildberries_deliveries. Avoid naming conflicts by:
  - Using a database prefix (e.g., wb_).
  - Running doctrine:migrations:diff before applying to check for overlaps.
Console Command Collisions
- Commands like baks:delivery:wildberries-fbs may conflict with existing commands. Rename or alias them in app/Console/Kernel.php:
```
protected $commands = [
    \BaksDev\WildberriesOrders\Console\DeliveryCommand::class => 'wb:delivery:fbs',
];
```
PHP 8.4+ Dependency
- The package requires PHP 8.4+ (e.g., named arguments, attributes). Upgrade your Laravel app or use a Docker container with PHP 8.4+.
Wildberries API Rate Limits
- Wildberries enforces rate limits. Implement exponential backoff in your API client:
```
$client->withOptions(['timeout' => 30, 'connect_timeout' => 10]);
```
Missing Inventory Sync
- This package does not handle inventory. Plan for custom inventory sync or integrate with a third-party solution (e.g., Laravel Inventory).

Localization Gaps

Wildberries-specific tax rules (NDS/VAT) and address formats may not align with your system. Extend the package’s models to handle localizations:

// app/Models/WildberriesOrder.php
protected static function boot() {
    parent::boot();
    static::saving(function ($order) {
        $order->setTaxRulesForRussia();
    });
}

Debugging Tips

Enable Debug Logging Add to config/logging.php:

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

Then log API responses:

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

Test API Responses Use Wildberries’ sandbox API to validate responses:

$sandboxResponse = WildberriesOrder::create([...], true); // Enable sandbox mode

Validate Migrations Before running migrate, inspect the diff:
```
php bin/console doctrine:migrations:diff --dry-run
```

Handle API Errors Catch Wildberries-specific exceptions:

try {
    $order = WildberriesOrder::create([...]);
} catch (\BaksDev\WildberriesOrders\Exceptions\ApiValidationException $e) {
    \Log::error('Wildberries API Validation Error', ['errors' => $e->errors]);
    abort(422, 'Invalid order data for Wildberries');
}

Extension Points

Custom Order Validation Extend the WildberriesOrderValidator to add business rules:

// app/Providers/WildberriesServiceProvider.php
public function register() {
    $this->app->bind('wildberries.order.validator', function () {
        return new class extends \BaksDev\WildberriesOrders\Validators\WildberriesOrderValidator {
            public function rules() {
                return array_merge(parent::rules(), [
                    'items.*.sku' => 'required|exists:products,sku',
                ]);
            }
        };
    });
}

Webhook Integration Add webhook listeners for real-time updates:

Wildberries Orders Laravel Package