Підключення DPD до сайту: PHP-посібник з прикладами

При інтеграції DPD розробники часто спотикаються про SOAP-протокол: помилки в тілі відповіді, власна система кодування міст, неочевидні поля для замовлення. Наприклад, щоб створити замовлення, потрібно передавати коди міст із довідника DPD, а не КЛАДР — інакше API поверне помилку city not found. Для розрахунку вартості потрібен об'єм вантажу: довжина × ширина × висота / 1 000 000. Без готового SDK самостійна розробка займає до 10 днів і може призвести до помилок в обробці відповідей. Ми накопичили досвід на 15+ проектах і скоротили цей термін удвічі. Професійна інтеграція економить до 30% на доставці за рахунок вибору оптимального тарифу та кешування довідників. Вартість базової інтеграції — від 15 000 грн, розширеної — від 30 000 грн.

Як підключити DPD API?

Встановлення SDK через Composer:

composer require dpd-ru/dpd-php-api-client

Ініціалізація клієнта з тестовим оточенням:

use DPD\DPDClient;

$client = new DPDClient(
    username: config('services.dpd.username'),
    password: config('services.dpd.password'),
    clientNumber: config('services.dpd.client_number'),
    test: app()->environment('production') === false
);

Тестове середовище (test: true) працює на https://test.dpd.ru. Облікові дані для тесту запитуються у менеджера DPD окремо від бойових.

Основні методи інтеграції

Нижче наведено ключові функції: розрахунок вартості, пошук міста, отримання терміналів, створення замовлення, відстеження, друк накладної, виклик кур'єра.

// --- Розрахунок вартості ---
public function calculateDelivery(
    string $fromCityId,   // код міста DPD (не ISO)
    string $toCityId,
    float  $weightKg,
    array  $dimensions,
    float  $declaredValue = 0
): array {
    $response = $this->client->getDPDOrderCost2([...]);
    // ... обробка
}

// --- Пошук міста ---
public function findCity(string $cityName, string $countryCode = 'RU'): array {
    $response = $this->client->getCitiesCashPay([...]);
    // ...
}

// --- Пункти видачі ---
public function getTerminals(?string $cityId = null): array {
    $response = $this->client->getTerminalsSelfDelivery2([...]);
    // ...
}

// --- Створення замовлення ---
public function createOrder(Order $order): array {
    $response = $this->client->createOrder([...]);
    // ...
}

// --- Відстеження ---
public function trackParcel(string $dpdOrderNum): array {
    $response = $this->client->getStatesByClient([...]);
    // ...
}

// --- Друк накладної ---
public function printLabel(string $dpdOrderNum, string $format = 'PDF'): string {
    $response = $this->client->createLabelFile([...]);
    // ...
}

// --- Виклик кур'єра ---
public function createPickupRequest(...): string {
    // ...
}

Налаштування розрахунку вартості: 5 кроків

Розрахунок вартості вимагає передачі кодів міст відправника та отримувача, ваги та габаритів. DPD повертає вартість для кожної доступної послуги. SDK автоматично обробляє відповідь і формує масив з цінами. Порівняння вартості різних служб дозволяє автоматично вибрати найвигідніший варіант, що економить до 30% на доставці.

1. Отримайте тестові облікові дані у менеджера DPD.
2. Встановіть SDK через Composer.
3. Ініціалізуйте клієнта з test: true.
4. Викличте метод getDPDOrderCost2, передавши коди міст, вагу та габарити.
5. Обробте відповідь: перевірте статус, витягніть вартість для кожної послуги.

Кешування довідника міст скорочує кількість запитів на 80%. Середній час розрахунку — менше 0.5 секунди. Довідник містить понад 5000 міст.

Вибір сервісу доставки

DPD пропонує кілька сервісів:

Додатково підтримуються сервіси з особливими умовами, наприклад, "Parcel Return" для повернень.

Тестове vs бойове оточення

Чому професійна інтеграція надійніша?

SOAP-специфікація DPD містить багато нюансів: відповіді повертають помилки в тілі, а не HTTP-статуси; коди міст не збігаються з КЛАДР; потрібна власна система маппінгу. Наші сертифіковані інженери інтегрували DPD для 15+ проектів, тому гарантуємо:

• Коректну обробку всіх типів відповідей (включаючи помилки status !== 'OK')
• Оптимізацію запитів: кешування довідника міст, розпаралелювання розрахунків
• Підтримку всіх сервісів: від PCL до EXPRESS
• Скорочення термінів розробки до 5–7 днів для базової інтеграції

Професійна інтеграція в 2 рази швидша і на 40% дешевша за самостійну. Вона обходиться на 40% дешевше за рахунок відсутності помилок та втрат часу. 95% відповідей обробляються коректно з першого разу.

Що входить в роботу (deliverables)

• Підключення API DPD (отримання доступів, налаштування SDK)
• Реалізація розрахунку вартості з вибором сервісу та врахуванням габаритів
• Інтеграція карти ПВЗ з фільтрацією та відображенням режиму роботи
• Створення замовлень з автоматичною передачею даних в DPD
• Відстеження статусів та оновлення статусу замовлення у вашій системі
• Друк накладних у форматах PDF або ZPL для термопринтерів
• Виклик кур'єра для забору відправлень
• Документація з інтеграції (технічна інструкція, опис API-методів)
• Навчання ваших співробітників (до 2 годин)
• Тестування на тестовому та бойовому оточеннях
• Підтримка протягом місяця після запуску

Обсяг, терміни та вартість

Базова інтеграція (розрахунок, ПВЗ, створення замовлення, відстеження) — від 5 до 7 днів, вартість від 15 000 грн. Розширена інтеграція (включаючи виклик кур'єра, друк накладних, мультисклад) — від 10 днів, вартість від 30 000 грн. Кінцева вартість розраховується індивідуально після аналізу вашого проекту. Отримайте консультацію з інтеграції DPD — вона безкоштовна.

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

• Помилки у відповідях: DPD не використовує HTTP-статуси, кожна операція потребує перевірки status у тілі відповіді.
• Коди міст: потрібен окремий пошук через getCitiesCashPay, оскільки DPD використовує свою нумерацію.
• Об'єм вантажу: параметр volume обчислюється в кубічних метрах, помилка у формулі призводить до некоректної вартості.
• Тайм-аути: запити до тестового середовища можуть бути повільними, рекомендується кешування довідників.

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

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