Автоматичне оновлення залишків товарів від постачальників на Laravel

Покупець додав товар у кошик, оформив замовлення, а через годину менеджер повідомляє: «Цього товару немає на складі». Або навпаки: товар є, але прихований через нульовий залишок у застарілому фіді. За статистикою, до 30% замовлень скасовуються саме через невірні залишки, а менеджери витрачають до 2 годин на день на ручне звірення CSV-файлів — при середній зарплаті $20/год це коштує до $1200 на місяць. Це типова ситуація при ручній синхронізації залишків.

Ми вирішуємо її автоматичною синхронізацією stock-даних від постачальників. Наші інженери мають 6+ років досвіду в інтеграціях з постачальниками — від інтеграції з постачальником 1С до маркетплейсів. Після впровадження ви забудете про ручну синхронізацію. Бюджет на інтеграцію багаторазово перекривається скороченням часу менеджерів (до 90%) та зниженням кількості скасованих замовлень у 2–3 рази. Синхронізація з постачальниками — це вкладення, яке окупається за рахунок підвищення точності залишків та зростання конверсії.

Які дані потрібно синхронізувати?

Повна картина залишку включає:

• qty — кількість одиниць на складі постачальника
• warehouse — на якому складі (особливо важливо при регіональних складах)
• available_date — дата очікуваного надходження, якщо зараз 0
• reserved — зарезервовано під чужі замовлення
• status — знято з продажу, під замовлення, тільки опт

Мінімальний набір для більшості магазинів: sku, qty, warehouse_id.

Способи отримання даних від постачальників

CSV/Excel за розкладом

Найпоширеніший варіант — постачальник кладе оновлений файл на FTP раз на годину. Це типовий PHP імпорт CSV з використанням PhpSpreadsheet. Реалізуємо інтерфейс StockSourceInterface та парсер під конкретний формат:

class FtpStockSource implements StockSourceInterface {
    public function fetch(): array {
        $ftp = ftp_connect($this->host);
        ftp_login($ftp, $this->user, $this->pass);
        $tmpFile = tempnam(sys_get_temp_dir(), 'stock_');
        ftp_get($ftp, $tmpFile, $this->remotePath, FTP_BINARY);
        ftp_close($ftp);
        $reader = \PhpOffice\PhpSpreadsheet\IOFactory::load($tmpFile);
        $rows = $reader->getActiveSheet()->toArray();
        unlink($tmpFile);
        $stocks = [];
        foreach (array_slice($rows, 1) as $row) { // пропустити заголовок
            $stocks[] = [
                'sku' => (string) $row[0],
                'qty' => (int) $row[2],
            ];
        }
        return $stocks;
    }
}

REST API з delta-оновленнями

Сучасні постачальники надають endpoint для інкрементальних змін. Запитуємо тільки ті SKU, залишки яких змінилися з останнього опитування. Це економить трафік та час обробки.

Webhook від постачальника

Якщо постачальник вміє пушити зміни, приймаємо POST-запит і ставимо задачу в чергу. Ендпоінт відповідає за <200 мс. Webhook — найбільш оперативний метод. Він оновлює залишки в десять разів швидше, ніж CSV-опитування, але вимагає більш складної інфраструктури.

class StockWebhookController
{
    public function __invoke(Request $request, string $source): JsonResponse
    {
        $payload = $request->validated();
        ProcessStockWebhookJob::dispatch($source, $payload);
        return response()->json(['status' => 'queued']);
    }
}

Порівняння методів

Як агрегувати залишки з декількох складів?

Підсумковий залишок на сайті — сума по всіх активних складах або з урахуванням пріоритету. Наприклад, склад «Київ» вважається основним: якщо на ньому qty > 0, показуємо його; інакше — інші. Ми реалізуємо це через view або computed-поле. Приклад SQL-представлення:

CREATE VIEW product_available_stock AS
SELECT product_id, SUM(qty) AS total_qty, MAX(updated_at) AS last_synced_at
FROM product_stocks
WHERE source_active = true
GROUP BY product_id;

Обробка та застосування даних

Bulk upsert

Використовуємо upsert для масового оновлення — один запит на 500 рядків замість N окремих UPDATE. Laravel upsert працює через INSERT ... ON CONFLICT DO UPDATE в PostgreSQL. Bulk upsert зменшує час оновлення в 50 разів порівняно з окремими запитами.

class StockUpdater {
    public function apply(array $stocks, int $sourceId): StockUpdateResult {
        $updated = $skipped = 0;
        $chunks = array_chunk($stocks, 500);
        foreach ($chunks as $chunk) {
            $rows = [];
            foreach ($chunk as $item) {
                $productId = $this->skuMap[$item['sku']] ?? null;
                if (!$productId) {
                    $skipped++;
                    continue;
                }
                $rows[] = [
                    'product_id' => $productId,
                    'source_id' => $sourceId,
                    'qty' => max(0, $item['qty']),
                    'updated_at' => now(),
                ];
                $updated++;
            }
            if ($rows) {
                DB::table('product_stocks')->upsert(
                    $rows,
                    ['product_id', 'source_id'],
                    ['qty', 'updated_at']
                );
            }
        }
        return new StockUpdateResult($updated, $skipped);
    }
}

Автоматичне управління видимістю

Після оновлення залишків перераховуємо, чи доступний товар для замовлення. Використовуємо Observer або database trigger:

class StockVisibilityObserver {
    public function updated(ProductStock $stock): void
    {
        $totalQty = ProductStock::where('product_id', $stock->product_id)->sum('qty');
        Product::where('id', $stock->product_id)->update([
            'in_stock' => $totalQty > 0,
            'stock_count' => $totalQty,
        ]);
    }
}

Як вибрати частоту оновлення?

При частому оновленні важливо не перевантажити БД. Bulk upsert по 500 рядків за один запит оптимальний. Webhook обробляє зміни в десять разів швидше, ніж CSV-опитування, але вимагає більш складної інфраструктури.

Обробка помилок та TTL

Типова проблема: постачальник не відповів. Не обнуляємо залишки. Використовуємо TTL: якщо дані від джерела старші за max_age (наприклад, 4 годин), помічаємо товари як «застарілі» та показуємо попередження в адмінці, але не чіпаємо qty на вітрині.

Що входить у реалізацію

1. Визначення списку постачальників та форматів даних.
2. Розробка парсерів для кожного джерела з реалізацією StockSourceInterface.
3. Налаштування scheduler для періодичного опитування CSV/API або webhook-ендпоінту.
4. Реалізація StockUpdater з bulk upsert та маппінгом SKU → product_id.
5. Додавання StockVisibilityObserver для автоматичного управління видимістю.
6. Налаштування TTL та моніторингу помилок.
7. Тестування на копії бази з реальними даними.

Терміни реалізації

• Одне джерело (CSV/FTP), scheduler, bulk upsert, перерахунок видимості — від 2 днів.
• Декілька джерел + агрегація по складах — від 3 до 4 днів.
• Webhook-прийом + дашборд моніторингу синхронізації — від 5 днів.

Точні терміни називаємо після аудиту вашого проєкту.

Документація та підтримка

• Документація: опис архітектури, схема даних, інструкція для адміністратора.
• Доступи: налаштування FTP, API-ключів, webhook-ендпоінту.
• Навчання: показуємо, як додавати нового постачальника та моніторити синхронізацію.
• Підтримка: виправляємо помилки протягом гарантійного терміну.

Пишіть нам для оцінки проекту – реалізуємо інтеграцію під ключ за 2-5 днів. Замовте впровадження — і ваші залишки завжди будуть актуальними.