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

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

Ми інтегруємо сервіс СДЕК на ваш сайт під ключ. Підключаємо розрахунок вартості з урахуванням усіх тарифів (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 грн. Тестування в тестовому середовищі СДЕК обов'язкове.