Інтеграція СДЕК: як підключити розрахунок, ПВЗ та відстеження на сайті

Повна інтеграція СДЕК на сайт: від розрахунку вартості до відстеження посилок

Ми інтегруємо сервіс СДЕК на ваш сайт під ключ. Підключаємо розрахунок вартості з урахуванням усіх тарифів (136–139), відображаємо пункти видачі (PVZ) на карті, створюємо замовлення одним запитом і синхронізуємо статуси через webhook у реальному часі. Базова версія готова за 5–7 робочих днів. Зв'яжіться з нами — оцінимо ваш проект. Гарантуємо коректну інтеграцію та підтримку протягом усього терміну експлуатації.

На практиці інтеграція з API СДЕК часто викликає проблеми: неправильний розрахунок через коди міст (у базі >100 000 міст) або втрачені замовлення при збоях запитів. Ми вирішуємо це кешуванням довідників, автоматичними повторними спробами (retry з exponential backoff) та детальним логуванням. У результаті кількість збоїв знижується до 0.1% — це підтверджують наші клієнти з 15+ проектами інтеграції доставки. Автоматизація через API в 5 разів швидша за ручну обробку.

Що дає інтеграція СДЕК

Що входить у вартість

• Технічне завдання та архітектура інтеграції
• Повний код інтеграції на вашому стеку (авторизація, калькулятор, ПВЗ, замовлення, webhook)
• Документація API та інструкція для операторів
• Тестування в тестовому середовищі СДЕК
• Навчання вашої команди (1 вебінар)
• Підтримка протягом 3 місяців після здачі

Як інтегрувати: крок за кроком

1. Отримайте ключі API СДЕК (client_id та client_secret) в особистому кабінеті.
2. Налаштуйте OAuth 2.0 авторизацію з кешуванням токена (див. приклад нижче).
3. Інтегруйте розрахунок вартості через метод /v2/calculator/tarifflist.
4. Додайте карту ПВЗ з допомогою методу /v2/deliverypoints.
5. Реалізуйте створення замовлення через /v2/orders.
6. Налаштуйте webhook для отримання статусів.

Як ми забезпечуємо надійність синхронізації статусів?

Використовуємо webhook-повідомлення. Після створення замовлення СДЕК надсилає POST-запит на ваш URL при кожній зміні статусу. Це швидше та дешевше за polling. Достатньо повернути HTTP 200 — інакше СДЕК повторює відправку до 3 разів. Ми також додаємо моніторинг: при відсутності повідомлень протягом 5 хвилин надсилаємо алерт.

Які дані потрібні для розрахунку вартості?

Для розрахунку достатньо передати коди міст відправника та отримувача, вагу та габарити посилки, а також тип доставки (двері/ПВЗ). API повертає список тарифів із мінімальним та максимальним терміном доставки. Ми автоматично фільтруємо тарифи з помилками (наприклад, код міста не знайдено) і віддаємо лише валідні варіанти.

Порівняння ручної та автоматичної обробки замовлень

Стек та інструменти

• Авторизація: OAuth 2.0 client credentials, токен живе 3600 секунд, кешуємо в Redis.
• Розрахунок вартості: метод /v2/calculator/tarifflist.
• ПВЗ: метод /v2/deliverypoints з фільтрацією за містом, вагою та типом.
• Замовлення: метод /v2/orders з повним набором полів.
• Webhook: реєструємо один раз, обробляємо ключові статуси.

Приклад авторизації та кешування токена:

class CdekAuthService {
    private const TOKEN_URL = 'https://api.cdek.ru/v2/oauth/token';
    private const CACHE_KEY = 'cdek_access_token';

    public function getToken(): string {
        return Cache::remember(self::CACHE_KEY, 3500, function () {
            $response = Http::asForm()->post(self::TOKEN_URL, [
                'grant_type' => 'client_credentials',
                'client_id' => config('services.cdek.client_id'),
                'client_secret' => config('services.cdek.client_secret'),
            ]);

            if ($response->failed()) {
                throw new CdekAuthException('Failed to obtain CDEK token: ' . $response->body());
            }

            return $response->json('access_token');
        });
    }
}

Приклад розрахунку вартості:

class CdekCalculatorService {
    public function calculateTariffList(
        string $fromCityCode,
        string $toCityCode,
        array $packages,
        int $deliveryType = 1
    ): array {
        $response = Http::withToken($this->auth->getToken())
            ->post('https://api.cdek.ru/v2/calculator/tarifflist', [
                'type' => $deliveryType,
                'from_location' => ['code' => (int)$fromCityCode],
                'to_location' => ['code' => (int)$toCityCode],
                'packages' => $packages,
            ]);

        if ($response->failed()) {
            throw new CdekApiException($response->body());
        }

        return collect($response->json('tariff_codes'))
            ->filter(fn($t) => empty($t['errors']))
            ->map(fn($t) => [
                'code' => $t['tariff_code'],
                'name' => $t['tariff_name'],
                'cost' => $t['delivery_sum'],
                'min_days' => $t['period_min'],
                'max_days' => $t['period_max'],
            ])
            ->values()
            ->toArray();
    }
}

Приклад отримання пунктів видачі:

public function getPickupPoints( string $cityCode, float $weightKg, bool $cashAllowed = false ): array {
    $response = Http::withToken($this->auth->getToken())
        ->get('https://api.cdek.ru/v2/deliverypoints', [
            'city_code' => $cityCode,
            'weight_max' => (int)($weightKg),
            'have_cash' => $cashAllowed ? 'true' : null,
            'type' => 'PVZ',
            'is_handout' => 'true',
        ]);

    return collect($response->json())
        ->map(fn($p) => [
            'code' => $p['code'],
            'name' => $p['name'],
            'address' => $p['location']['address'],
            'lat' => $p['location']['latitude'],
            'lng' => $p['location']['longitude'],
            'work_time' => $p['work_time'],
            'cash_allowed'=> $p['have_cash'],
        ])
        ->toArray();
}

Приклад створення замовлення:

public function createOrder(Order $order): string {
    $payload = [
        'tariff_code' => $order->cdek_tariff_code,
        'from_location' => [
            'code' => config('services.cdek.warehouse_city_code'),
            'address' => config('services.cdek.warehouse_address'),
        ],
        'to_location' => [
            'code' => $order->cdek_city_code,
            'address' => $order->delivery_address,
        ],
        'recipient' => [
            'name' => $order->recipient_name,
            'phones' => [['number' => $order->recipient_phone]],
            'email' => $order->recipient_email,
        ],
        'packages' => [[
            'number' => 'p' . $order->id,
            'weight' => (int)($order->total_weight_kg * 1000),
            'length' => $order->package_length,
            'width' => $order->package_width,
            'height' => $order->package_height,
            'comment' => 'Замовлення #' . $order->id,
            'items' => $order->items->map(fn($item) => [
                'name' => $item->product->name,
                'ware_key'=> (string)$item->product_id,
                'payment' => ['value' => 0],
                'cost' => $item->price,
                'amount' => $item->quantity,
                'weight' => (int)($item->product->weight_g),
            ])->toArray(),
        ]],
    ];

    if ($order->pickup_point_code) {
        $payload['delivery_point'] = $order->pickup_point_code;
    }

    $response = Http::withToken($this->auth->getToken())
        ->post('https://api.cdek.ru/v2/orders', $payload);

    $orderId = $response->json('entity.uuid');

    if (!$orderId) {
        throw new CdekOrderException(
            'Failed to create CDEK order: ' . json_encode($response->json('requests.0.errors'))
        );
    }

    return $orderId;
}

Приклад обробки webhook:

public function handleWebhook(Request $request): Response
{
    $data = $request->json()->all();
    if ($data['type'] !== 'ORDER_STATUS') {
        return response('ok', 200);
    }
    $cdekOrderUuid = $data['attributes']['uuid'];
    $statusCode = $data['attributes']['status']['code'];
    $order = Order::where('cdek_uuid', $cdekOrderUuid)->first();
    if ($order) {
        $order->update([
            'cdek_status' => $statusCode,
            'cdek_status_at' => now(),
        ]);
        if (in_array($statusCode, ['READY_FOR_PICKUP', 'DELIVERED'])) {
            dispatch(new NotifyCustomerDeliveryStatus($order, $statusCode));
        }
    }
    return response('ok', 200);
}

Етапи робіт

Терміни та вартість орієнтовно

Базова інтеграція (розрахунок вартості + ПВЗ на карті + створення замовлень) — 5–7 робочих днів, від 15 000 грн. Додавання відстеження через webhook, синхронізація статусів і друк накладних — ще 3–4 дні, від 25 000 грн. Тестування в тестовому середовищі СДЕК обов'язкове.