README

SDK для интеграции с API доставки DPD.

Требования

PHP 8.5 или выше
расширения: soap, pdo, pdo_sqlite (или другой драйвер PDO), mbstring, iconv, ftp
Composer
зависимость symfony/cache ^8.0.12 (устанавливается через Composer)

Установка

Через Composer

composer require kskby/dpd

Из исходников

Клонируйте репозиторий и подключите автозагрузку:

require_once 'path/to/dpd/src/autoload.php';

Затем установите зависимости:

composer install

После установки

Для расчёта стоимости нужен импорт городов и терминалов во внутреннюю БД. Примеры загрузчиков: examples/load_locations.php, examples/load_terminals.php.

Настройки

Параметры передаются в \Ipol\DPD\Config\Config (или в класс, реализующий \Ipol\DPD\Config\ConfigInterface):

UPLOAD_DIR — каталог для сохранённых файлов (наклейки, накладные)
DATA_DIR — каталог с данными и SQL-схемами
DB — подключение к БД (по умолчанию SQLite)
DB.DSN — DSN строка
DB.USERNAME / DB.PASSWORD — учётные данные
DB.DRIVER — драйвер (обычно определяется из DSN)
DB.PDO — готовый объект \PDO вместо остальных параметров БД
KLIENT_NUMBER / KLIENT_KEY / KLIENT_CURRENCY — аккаунт RU
KLIENT_NUMBER_KZ / KLIENT_KEY_KZ / KLIENT_CURRENCY_KZ — аккаунт KZ
KLIENT_NUMBER_BY / KLIENT_KEY_BY / KLIENT_CURRENCY_BY — аккаунт BY
API_DEF_COUNTRY — аккаунт по умолчанию: RU, KZ, BY
IS_TEST — тестовый режим API
WEIGHT / LENGTH / WIDTH / HEIGHT — габариты по умолчанию (граммы и миллиметры)
TARIFF_OFF — исключённые тарифы (PCL, CSM, ECN, …)
DEFAULT_TARIFF_CODE / DEFAULT_TARIFF_THRESHOLD — тариф по умолчанию при низкой стоимости
DECLARED_VALUE — включать объявленную ценность в расчёт
COMMISSION_NPP_CHECK / COMMISSION_NPP_PERCENT / COMMISSION_NPP_MINSUM / COMMISSION_NPP_PAYMENT / COMMISSION_NPP_DEFAULT — комиссия за НПП

Пример для Беларуси:

$config = new \Ipol\DPD\Config\Config([
    'KLIENT_NUMBER_BY'   => '...',
    'KLIENT_KEY_BY'      => '...',
    'KLIENT_CURRENCY'    => 'BYN',
    'KLIENT_CURRENCY_BY' => 'BYN',
    'API_DEF_COUNTRY'    => 'BY',
    'IS_TEST'            => true,
]);

Расчёт стоимости доставки

Сначала создаётся отправка \Ipol\DPD\Shipment:

$config = new \Ipol\DPD\Config\Config([
    // параметры авторизации
]);

$shipment = new \Ipol\DPD\Shipment($config);

// города отправления и назначения (должны быть в БД)
$shipment->setSender('Беларусь', 'Гомельская', 'г. Гомель');
$shipment->setReceiver('Беларусь', 'Минская', 'г. Минск');

// от терминала / до двери
$shipment->setSelfPickup(true);
$shipment->setSelfDelivery(false);

$goods = [
    [
        'NAME'       => 'Название товара',
        'QUANTITY'   => 1,
        'PRICE'      => 1000,
        'VAT_RATE'   => 'Без НДС',
        'WEIGHT'     => 1000, // граммы
        'DIMENSIONS' => [
            'LENGTH' => 100, // мм
            'WIDTH'  => 200,
            'HEIGHT' => 200,
        ],
    ],
];

$shipment->setItems($goods, 1000);

// опционально: тип плательщика и платёжная система (для НПП / комиссий)
$shipment->setPaymentMethod(1, 1);

Расчёт выполняет \Ipol\DPD\Calculator:

$calc = $shipment->calculator();

// оптимальный тариф
$tariff = $calc->calculate();

// конкретный тариф
$tariff = $calc->calculateWithTariff('PCL');

В calculate и calculateWithTariff можно передать код валюты. Для конвертации нужен класс с интерфейсом \Ipol\DPD\Currency\ConverterInterface:

class Converter implements \Ipol\DPD\Currency\ConverterInterface
{
    // реализация
}

$tariff = $calc
    ->setCurrencyConverter(new Converter())
    ->calculate('USD');

Отправка заказа

Заказ хранится в модели \Ipol\DPD\DB\Order\Model и во внутренней БД:

$config = new \Ipol\DPD\Config\Config([
    // ...
]);

$shipment = new \Ipol\DPD\Shipment($config);
// параметры отправления...

$order = \Ipol\DPD\DB\Connection::getInstance($config)->getTable('order')->makeModel();
$order->orderId = 'Внешний код заказа';
$order->setShipment($shipment);

$order->serviceCode = 'PCL';
// или вручную: $order->serviceVariant = ['SELF_PICKUP' => true, 'SELF_DELIVERY' => false];

$order->pickupDate = '2026-08-06';
$order->pickupTimePeriod = '9-18';

$order->senderName = 'Наименование отправителя';
$order->senderFio = 'ФИО отправителя';
$order->senderPhone = 'Телефон отправителя';
$order->senderTerminalCode = 'Код терминала отправления';

$order->receiverName = 'Наименование получателя';
$order->receiverFio = 'ФИО получателя';
$order->receiverPhone = 'Телефон получателя';
$order->receiverStreet = 'Улица';
$order->receiverStreetabbr = 'ул.';
$order->receiverHouse = 'дом';
$order->receiverComment = 'инструкция для курьера';

Операции с API DPD — через $order->dpd() (\Ipol\DPD\Order):

$result = $order->dpd()->create();

// $order->dpd()->cancel();
// $order->dpd()->checkStatus();
// $order->dpd()->getLabelFile();
// $order->dpd()->getInvoiceFile();

$orderId = 1;
$order = \Ipol\DPD\DB\Connection::getInstance($config)->getTable('order')->getByOrderId($orderId);
$order->dpd()->cancel();

Работа с местоположениями и терминалами

После загрузки данных города и ПВЗ доступны через DataMapper:

$orderTable    = \Ipol\DPD\DB\Connection::getInstance($config)->getTable('order');
$locationTable = \Ipol\DPD\DB\Connection::getInstance($config)->getTable('location');
$terminalTable = \Ipol\DPD\DB\Connection::getInstance($config)->getTable('terminal');

Возвращается объект с интерфейсом \Ipol\DPD\DB\TableInterface. У локаций есть getByAddress($country, $region, $city, $select = '*').

$items = $terminalTable->find([
    'where' => 'NPP_AVAILABLE = "Y"',
])->fetchAll();

Cron

Класс \Ipol\DPD\Agents содержит методы для периодических заданий, в том числе обновление статусов заказов:

// dpd-check-status.php
$config = new \Ipol\DPD\Config\Config([
    // параметры
]);

\Ipol\DPD\Agents::checkOrderStatus($config);

*/10 * * * * /path/to/php /path/to/dpd-check-status.php

Тесты

Автотесты на PHPUnit 11 покрывают основные сценарии (маршрут Гомель → Минск, БД SQLite in-memory, моки API).

Установка dev-зависимостей и запуск:

composer install
composer test

Эквивалентно:

vendor/bin/phpunit

Конфигурация: phpunit.xml.dist, тесты в каталоге tests/.

Кодировка

Модуль работает в UTF-8. Для другой кодировки проекта конвертируйте данные самостоятельно. Вспомогательный метод:

$data = [
    'PARAM1' => 'Параметр 1',
    'PARAM2' => [
        'SUB1' => 'п 2.1',
        'SUB2' => 'п 2.2',
    ],
];

$convertData = \Ipol\DPD\Utils::convertEncoding($data, 'windows-1251', 'UTF-8');

Примеры

В каталоге examples/ — примеры использования SDK.

Документация

Описание классов и методов: документация.

kskby / dpd

Package info

Security

Statistics