Інтеграція служби доставки DPD на сайт

Інтеграція служби доставки DPD на сайт

DPD — міжнародний логістичний оператор з мережею по Росії та країнах СНГ. API надається через SOAP-сервіси, дещо архаїчно за сучасними стандартами REST, але функціональне. Офіційний SDK для PHP приховує складність SOAP.

Підключення та ініціалізація

use DPD\DPDClient;

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

Тестова середовище на https://test.dpd.ru. Credentials для тестування запитуються окремо від промислових.

Розрахунок вартості

public function calculateDelivery(
    string $fromCityId,
    string $toCityId,
    float  $weightKg
): array {
    $response = $this->client->getDPDOrderCost2([
        'pickup'  => ['CityID' => $fromCityId],
        'delivery' => ['CityID' => $toCityId],
        'weight'  => $weightKg,
        'serviceCode'  => 'ALL',
    ]);

    return collect($response->return ?? [])
        ->filter(fn($r) => $r->result === 'OK')
        ->map(fn($r) => [
            'service_code' => $r->serviceCode,
            'cost'         => (float)$r->cost,
            'days'         => (int)$r->days,
        ])
        ->toArray();
}

Коди сервісів: BZP (дверь-дверь), PCL (до терміналу), EXPRESS.

Пошук міст

public function findCity(string $cityName): array
{
    $response = $this->client->getCitiesCashPay([
        'cityName' => $cityName,
    ]);

    return collect($response->return ?? [])
        ->map(fn($c) => [
            'id'   => $c->cityId,
            'name' => $c->cityName,
        ])->toArray();
}

Кешувати міста локально — запити повільні.

Терміналипункти видачі

public function getTerminals(?string $cityId = null): array
{
    $response = $this->client->getTerminalsSelfDelivery2(
        $cityId ? ['cityId' => $cityId] : []
    );

    return collect($response->return ?? [])
        ->map(fn($t) => [
            'id'   => $t->terminalCode,
            'name' => $t->terminalName,
        ])->toArray();
}

Створення замовлення

public function createOrder(Order $order): array
{
    $response = $this->client->createOrder([
        'header' => [
            'datePickup'    => now()->addDay()->format('Y-m-d') . 'T10:00:00',
            'senderAddress' => [
                'name' => config('services.dpd.sender_name'),
                'city' => config('services.dpd.sender_city'),
            ],
        ],
        'order' => [[
            'orderNum'        => (string)$order->id,
            'serviceCode'     => $order->dpd_service_code,
            'cargoWeight'     => $order->total_weight_kg,
            'receiverAddress' => [
                'name' => $order->recipient_name,
                'city' => $order->shipping_city,
            ],
        ]],
    ]);

    if (!$response->return[0] || $response->return[0]->status !== 'OK') {
        throw new DpdOrderException('Помилка створення замовлення DPD');
    }

    return [
        'dpd_order_num' => $response->return[0]->orderNumberInternal,
    ];
}

Відстеження

public function trackParcel(string $dpdOrderNum): array
{
    $response = $this->client->getStatesByClient(['clientOrderNr' => $dpdOrderNum]);

    return collect($response->return ?? [])
        ->map(fn($s) => [
            'date'   => $s->transitionTime,
            'status' => $s->newState,
        ])->toArray();
}

Друк етикеток

public function printLabel(string $dpdOrderNum): string
{
    $response = $this->client->createLabelFile([
        'OrderRanges' => ['clientOrderNr' => $dpdOrderNum],
        'fileFormat'  => 'PDF',
    ]);

    return base64_decode($response->return->fileContent);
}

Проблеми

SOAP-відповіді іноді повертають помилки в тілі з status !== 'OK'. Коди міст — не ФИАС, потрібен маппінг.

Терміни

Базова інтеграція — 5–7 днів. SOAP складність додає 1–2 дні порівняно з REST.