Підключення 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 обчислюється в кубічних метрах, помилка у формулі призводить до некоректної вартості.
• Тайм-аути: запити до тестового середовища можуть бути повільними, рекомендується кешування довідників.