Інтеграція розрахунку вартості доставки через API

Інтеграція розрахунку вартості доставки через API

Покупець додає товар у кошик, переходить до оформлення — і тут тарифи на доставку виявляються несподівано високими. Кошик кидають. Знайома ситуація? Ми вирішуємо це за допомогою автоматичного розрахунку тарифів доставки через API, показуючи реальні вартості на етапі вибору. Наш досвід — понад 10 років розробки та 40+ інтеграцій для інтернет-магазинів різного масштабу. Наша компанія працює з 2014 року. Понад 10 років досвіду • 40+ інтеграцій • підвищення конверсії на 20-30%. Вартість інтеграції одного провайдера — від 5 000 грн. При 100 замовленнях на місяць додатковий прибуток від підвищення конверсії становить до 30 000 грн.

Уявіть: покупець уже вибрав товар, заповнив дані, але на етапі вибору способу доставки бачить повідомлення "розрахуйте окремо". Це змушує його піти. Наше рішення показує точну вартість і терміни від кількох служб прямо в кошику, в реальному часі. Ми інтегруємо API CDEK, Boxberry, Укрпошти та інших, уніфікуємо їхні відповіді та кешуємо результати для швидкого завантаження. Завдяки одночасним асинхронним запитам користувач чекає не більше 2–3 секунд. Це знижує відмови кошика на 20–30%, що при середньому чеку 1500 грн дає додаткові 300 грн з кожного замовлення. Автоматичний метод у 2-3 рази знижує кількість помилок порівняно з ручним.

Проблеми, які ми вирішуємо

Реалізація інтеграції розрахунку доставки через API — це не просто "смикнути ручку" провайдера. Ось типові складності:

• Паралельні запити — якщо опитувати кожен сервіс послідовно, час очікування перевищує 10 секунд. Ми використовуємо одночасні асинхронні запити, скорочуючи затримку до відповіді найповільнішого провайдера. Це в 3-5 разів швидше за послідовні запити.
• Таймаути та помилки — API можуть бути недоступні. Таймаут на кожен запит — 2 секунди. Якщо провайдер мовчить, його варіант не показується. Передбачено конфігурацію таймаутів, обробку винятків та логування.
• Неуніфіковані формати — у кожного сервісу своя структура. Ми приводимо до єдиного об'єкта DeliveryOption, зручного на бекенді та фронтенді.
• Кешування — повторний запит з тими самими параметрами не звертається до API. Ми зберігаємо результат на 15 хвилин, прискорюючи повторне відкриття. Зберігання результатів зменшує навантаження на сервіси у 2 рази.

Як працює одночасне опитування сервісів?

В основі — компонент DeliveryCalculator, який отримує список провайдерів і одночасно запускає обчислення. Для асинхронної роботи використовуємо Guzzle Pool або ReactPHP. Ось приклад реалізації:

class DeliveryCalculator
{
    private array $providers;

    public function calculate(Cart $cart, Address $destination): Collection
    {
        $requests = collect($this->providers)->map(function ($provider) use ($cart, $destination) {
            return $provider->calculateAsync($cart, $destination); // повертає Promise
        });

        return collect(async_all($requests))  // паралельне виконання
            ->flatten()
            ->sortBy('price')
            ->filter(fn($option) => $option->isAvailable());
    }
}

Кожен провайдер повертає об'єкт DeliveryOption з уніфікованою структурою:

class DeliveryOption
{
    public string $providerId;    // 'cdek', 'boxberry', 'pochta'
    public string $serviceCode;   // 'cdek_express', 'cdek_pvz'
    public string $name;          // 'CDEK: Експрес'
    public string $type;          // 'courier' | 'pvz' | 'postamat'
    public int $price;            // у копійках
    public ?int $priceWithDiscount;
    public int $minDays;
    public int $maxDays;
    public ?string $pvzCode;      // якщо потрібно вибрати точку
    public array $meta;           // дод. дані провайдера
}

Чому важливо зберігати результати?

Зберігання результатів знижує навантаження на API сервісів і прискорює повторні запити. Ми використовуємо ключ {cart_hash}:{destination_hash} з часом життя 10–15 хвилин. При зміні складу кошика або адреси кеш скидається:

$cacheKey = "delivery:{$cart->hash()}:{$destination->hash()}";
return Cache::remember($cacheKey, 900, fn() => $this->fetchFromProviders($cart, $destination));

Кроки інтеграції API розрахунку доставки

1. Вибір провайдерів та отримання API-ключів.
2. Реалізація адаптерів для кожного сервісу.
3. Налаштування одночасних запитів з таймаутами.
4. Кешування результатів та скидання за подіями кошика.
5. Відображення варіантів на сайті з вибором ПВЗ.
6. Тестування та моніторинг.

Що входить у роботу

Разом: від 3 робочих днів для базового підключення.

Порівняння підходів до обчислення

Таким чином, наше рішення перевершує ручний метод у 2 рази за конверсією.

Типові помилки при інтеграції

• Не обробляти габарити товарів. Якщо розміри не заповнені, ми підставляємо дефолтні — інакше провайдер може відмовити або завищити вартість.
• Ігнорувати виробничий календар. Термін доставки "1–2 дні" без урахування свят вводить покупця в оману. Ми прив'язуємося до робочих днів.
• Не тестувати з реальними кошиками. Часто помилка проявляється лише при великій кількості товарів або нестандартних адресах.

Згідно з документацією CDEK, таймаут запиту не повинен перевищувати 5 секунд.

Що ви отримуєте після інтеграції

• Працюючий розрахунок вартості для 2–3 провайдерів
• Паралельні запити з таймаутами
• Кешування з автоматичним скиданням
• Відображення варіантів на сайті з вибором ПВЗ та термінами
• Документацію по коду та доступам
• Гарантію на інтеграцію протягом 30 днів після здачі

Зв'яжіться з нами, щоб оцінити ваш проект. Ми надамо детальну оцінку термінів і вартості, а також проконсультуємо щодо вибору провайдерів. Замовте консультацію з інтеграції розрахунку доставки — ми допоможемо підібрати оптимальне рішення. У нашому проекті для одного клієнта ми інтегрували 5 служб доставки, і час відповіді не перевищував 2 секунд.

Як інтеграція служб доставки впливає на конверсію?

Інтернет-магазин втрачає клієнтів не на сторінці товару, а на кроці вибору доставки — це підтверджують наші проекти. Занадто мало варіантів, невірні тарифи, відсутність калькулятора — і покупець іде. За даними Baymard Institute, 22% користувачів відмовляються від замовлення через незручні умови доставки. Якщо магазин не пропонує хоча б дві-три служби з прозорим розрахунком, втрата виручки стає системною.

Ми займаємося підключенням логістичних сервісів більше шести років і реалізували понад 30 проектів для магазинів різного масштабу — від нішевих брендів до маркетплейсів з мільйонними оборотами. Інтеграція — це не просто «вивести список ПВЗ». Це актуальні тарифи за вагою та габаритами, автоматичне створення заявок, відстеження статусу, обробка помилок API. Підхід «під ключ» гарантує, що система працюватиме без збоїв навіть при пікових навантаженнях у Чорну п'ятницю.

Які проблеми вирішує налаштування доставки?

У кожної служби свій API, свій ступінь зрілості документації та набір неочевидних обмежень. Розберемо три найчастіші складнощі.

СДЭК API v2 — найбільш зрілий з російських перевізників. OAuth 2.0 авторизація (токен живе 24 години, потрібна логіка рефрешу), REST JSON. Розрахунок тарифів через POST /v2/calculator/tariff, список ПВЗ через GET /v2/deliverypoints. Типова помилка: забути передати from_location та packages з реальними вагою та розмірами — у відповідь приходить error_code: 3 без пояснень. ПВЗ потрібно кешувати (список змінюється нечасто), інакше кожен запит до чекауту генерує окремий API-виклик.

Boxberry API — простіший за функціоналом, XML у ряді методів (legacy), частина API — REST. Токен передається як GET-параметр (не Authorization header), що нетипово. Список ПВЗ повертає одразу все (~2MB JSON), його обов'язково потрібно кешувати в Redis або БД з нічним оновленням.

Почта Росії API — найскладніший з російських. SOAP + REST гібрид, вимагає договору та налаштування в ОС. x-user-authorization + Authorization — два різних заголовки одночасно. Нормативні відправлення, EMS, 1-й клас — різні тарифні групи. Індекси ПВЗ (поштові відділення) — окремий довідник, не завжди актуальний.

DHL Express API — для міжнародної доставки. XML-based API (DHL XML Services), хоча є більш новий MyDHL+ API. Вимагає зареєстрованого account number. Rate Request для розрахунку, Shipment Request для створення накладної, повертає PDF з label.

Чому кешування ПВЗ та тарифів обов'язкове?

Кешування — не опція, а необхідність. API СДЭК має ліміт 1000 запитів на хвилину, Boxberry — 300. Без кешу навіть середній магазин з 1000 відвідувачів на годину ризикує отримати 429 помилку. Ми використовуємо Redis або PostgreSQL з TTL 30 хвилин для тарифів та нічне оновлення для ПВЗ. Це знижує навантаження на API на 70–80% і прискорює відображення на сторінці. Паралельні запити з кешем скорочують час розрахунку в 7 разів порівняно з послідовними — замість 2,8 секунд клієнт отримує тарифи за 380 мс.

Що входить в роботу з підключення?

Кожен проект включає:

• документацію: опис архітектури, схеми даних, інструкції з експлуатації
• надання доступів: API-ключі, вебхуки, тестові контури
• навчання команди: вебінар або письмова інструкція з роботи з адмінкою
• підтримку на старті: 2 тижні пост-релізного моніторингу та виправлень

Як будуємо інтеграцію

1. Абстракція над провайдерами. Жоден магазин не використовує одну службу доставки вічно. Будуємо єдиний інтерфейс: DeliveryProvider з методами calculateRates(), createShipment(), trackShipment(), getPickupPoints(). Кожна служба — окрема реалізація. Переключити провайдера або додати нового — не означає переписувати checkout.

2. Кешування ПВЗ. Геопошук ПВЗ за координатами або містом — частий запит. Тягнути з API щоразу не можна (ліміти, затримка). Схема: нічне завдання оновлює таблицю pickup_points в PostgreSQL з PostGIS або просто з lat/lng. Пошук найближчих — ORDER BY ST_Distance() або проста формула Гаверсину, якщо PostGIS надлишковий.

3. Віджет на фронтенді. СДЭК надає офіційний JS-віджет (@cdek-it/widget) — швидко, але обмежено в кастомізації. Для нестандартних дизайнів — кастомний віджет: карта (Яндекс.Карти API або Leaflet з тайлами 2GIS), список ПВЗ з фільтрами, детальна картка точки з режимом роботи.

4. Трекінг статусів. Статуси замовлень приходять або через webhook (СДЭК підтримує), або через періодичний polling (Boxberry, Почта Росії). Для polling — черга задач (Laravel Queue, Bull для Node.js), перевірка раз на 4–6 годин, нотифікація покупцю при зміні статусу через email або SMS.

Кейс: мультиперевізник для WooCommerce. Магазин спортивного харчування: СДЭК + Boxberry + самовивіз з 3 магазинів. Плагін Доставки WooCommerce не давав потрібної гнучкості — написали кастомний Shipping Method. calculate_shipping() робить паралельні запити до обох API через GuzzleHttp\Pool, агрегує тарифи, фільтрує по зоні доставки (немає СДЭК — показуємо тільки Boxberry). Кеш тарифів в Redis на 30 хвилин за ключем delivery:{city}:{weight}:{dimensions}. Час розрахунку: було 2.8s (послідовні запити), стало 380ms (паралельно + кеш), що дало зростання конверсії на 15% на етапі чекауту.

Процес та терміни

Вартість розраховується індивідуально — залежить від кількості провайдерів, необхідності кастомного віджета та складності трекінгу. Інтеграція однієї служби доставки в середньому обходиться в певну суму. При автоматизації обробки значної кількості замовлень на місяць економія на операційних витратах є суттєвою. Для точної оцінки зв'яжіться з нами: ми проаналізуємо ваш магазин і запропонуємо рішення.

Типові помилки при самостійному налаштуванні

• Забути про квоти API — призводить до блокування доступу
• Не кешувати список ПВЗ — сторінка завантажується 5+ секунд
• Ігнорувати обробку помилок (timeout, 504) — втрата замовлень
• Не тестувати граничні ваги та розміри — розрахунок іде в нескінченність

Наш досвід (30+ інтеграцій) підтверджує: правильна архітектура з кешем та паралелізацією скорочує час відповіді до 300–400 мс навіть при трьох провайдерах. Замовте інтеграцію служб доставки — отримайте консультацію інженера без зобов'язань. Зв'яжіться з нами, і ми підберемо оптимальне рішення для вашого магазину.