API-інтеграція Dostavista: розрахунок, замовлення, відстеження кур'єрів

Втрата замовлень через відсутність розрахунку доставки — реальність для 30% інтернет-магазинів. Клієнт іде, якщо не бачить точної вартості. Інтеграція Dostavista вирішує цю проблему: API дозволяє розраховувати вартість, створювати замовлення та відстежувати кур'єрів у реальному часі. Ми маємо понад 10 років досвіду в веб-розробці та 15+ успішних інтеграцій кур'єрських служб, що гарантує стабільну роботу без сюрпризів. Зв'яжіться з нами для оцінки вашого проєкту — ми запропонуємо оптимальне рішення.

Чому варто інтегрувати Dostavista?

Dostavista — краудсорсингова платформа, що забезпечує доставку вдвічі швидше за традиційні кур'єрські служби, а вартість на 20-30% нижча. Гнучка система типів транспорту дозволяє перевозити що завгодно: від документів до великогабаритних меблів. API надає всі необхідні методи: розрахунок вартості, створення замовлення, відстеження статусів. Ми використовуємо накопичений досвід (10+ років у веб-розробці) для надійної інтеграції. Згідно з нашими даними, після інтеграції конверсія в кошику збільшується в середньому на 15%.

Які методи API надає Dostavista?

Dostavista надає REST API з авторизацією через X-User-Email і X-User-Token. Sandbox-оточення доступне на robotapitest.dostavista.ru. Перед використанням потрібно створити обліковий запис і отримати API-токен в особистому кабінеті. API має ліміт 10 запитів на секунду на обліковий запис. При перевищенні повертається 429 Too Many Requests, тому для розрахунків використовуйте кешування. Детальніше про методи — у Dostavista API Documentation (https://dostavista.docs.apiary.io/).

Як розраховується вартість доставки?

POST /api/business/v1/calculate-order

{
    "matter": "Документи",
    "insurance_amount": "0",
    "vehicle_type_id": 1, // 1=пішохід, 2=велосипед, 3=мотоцикл, 8=авто
    "points": [
        {
            "address": "Київ, Хрещатик, 1",
            "client_order_id": "pickup"
        },
        {
            "address": "Київ, Арбат, 10",
            "client_order_id": "delivery"
        }
    ]
}

Відповідь містить delivery_fee_amount у копійках — вартість доставки. Рекомендується додати невеликий буфер (+5–10%) до вартості, що відображається, оскільки кінцева ціна може незначно відрізнятися через динамічне ціноутворення. Для зменшення кількості запитів кешуйте результати на 1 хвилину.

Як створити замовлення?

POST /api/business/v1/create-order

{
    "matter": "Одяг",
    "vehicle_type_id": 3,
    "backpay_amount": "0", // накладений платіж
    "points": [
        {
            "address": "Київ, Складський провулок, 5",
            "contact_person": {"phone": "+380901234567", "name": "Склад"},
            "taking_amount": "0",
            "note": "Зателефонувати за 15 хвилин"
        },
        {
            "address": "Київ, Леніна, 20, кв 5",
            "contact_person": {"phone": "+380907654321", "name": "Покупець"},
            "is_door_to_door": true,
            "note": "Код домофону: 456"
        }
    ]
}

При невірному vehicle_type_id API повертає помилку 400. Використовуйте унікальний client_order_id для ідемпотентності — це запобігає дублюванню замовлень при повторних відправках.

Як налаштувати webhook для отримання повідомлень?

1. В особистому кабінеті Dostavista вкажіть URL вашої кінцевої точки для прийому POST-запитів.
2. Реалізуйте обробку подій: order.created, order.status_changed, order.finished.
3. Webhook надсилає JSON з полями: order_id, status, courier_latitude, courier_longitude.
4. Переконайтеся, що сервер відповідає 200 OK протягом 5 секунд — при таймауті контекст надсилається повторно до 3 разів.
5. Протестуйте в sandbox-оточенні, імітуючи різні статуси. Для локальної налагодження використовуйте сервіси типу webhook.site або ngrok.

Як відстежувати кур'єра в реальному часі?

Статуси замовлення можна відстежувати через polling (GET /api/business/v1/orders/{id}) або webhook. Актуальні статуси:

У відповіді є поля courier_latitude і courier_longitude — координати кур'єра. Використовуйте JavaScript-бібліотеки (наприклад, Leaflet) для відображення на карті.

Як вибрати тип транспорту?

Dostavista дозволяє вибирати транспорт під вантаж:

На фронті це реалізується як додатковий крок при виборі доставки або автоматично на основі габаритів товару.

Як обробляти помилки API?

API може повертати помилки: 400 INVALID_PARAMETER (невірний тип транспорту або порожня адреса), 401 UNAUTHORIZED (невірний токен), 409 ORDER_EXISTS (замовлення з таким client_order_id вже існує), 429 TOO_MANY_REQUESTS (перевищено ліміт запитів, впровадьте кешування), 500 INTERNAL_ERROR (тимчасова помилка сервера, повторіть запит через 3 секунди).

Що входить в інтеграцію під ключ?

• Аналіз вимог і налаштування API-ключів
• Реалізація розрахунку вартості доставки на сайті
• Створення форми замовлення з вибором типу транспорту
• Інтеграція трекінгу кур'єра на карті
• Налаштування webhook-повідомлень про зміну статусу
• Тестування та налагодження в sandbox-оточенні
• Документація та передача доступів

Етапи роботи

1. Аналіз і проєктування — 1 день. Збираємо вимоги, підключаємо sandbox.
2. Розробка інтеграції — 2–3 дні. Реалізуємо розрахунок, створення замовлень, трекінг.
3. Тестування та деплой — 1 день. Перевіряємо всі сценарії, включаючи помилки API.

Скільки часу займає інтеграція?

Базова інтеграція з розрахунком і створенням замовлень — від 2 до 3 робочих днів. З трекінгом на карті та webhook-обробкою — від 4 до 5 днів. Точні терміни залежать від складності вашого проєкту. Наприклад, для мережі кав'ярень ми реалізували інтеграцію за 3 дні, що дозволило скоротити час доставки на 30%.

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

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

Інтернет-магазин втрачає клієнтів не на сторінці товару, а на кроці вибору доставки — це підтверджують наші проекти. Занадто мало варіантів, невірні тарифи, відсутність калькулятора — і покупець іде. За даними 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 мс навіть при трьох провайдерах. Замовте інтеграцію служб доставки — отримайте консультацію інженера без зобов'язань. Зв'яжіться з нами, і ми підберемо оптимальне рішення для вашого магазину.