Интеграция СДЭК на сайт: API v2, расчёт доставки, ПВЗ, отслеживание

Интеграция СДЭК на сайт: полный цикл от расчёта до отслеживания

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

На практике интеграция с API СДЭК часто вызывает проблемы: неверный расчёт из-за кодов городов (в базе >100 000 городов) или потерянные заказы при сбоях запросов. Мы решаем это кешированием справочников, автоматическими повторными попытками (retry с exponential backoff) и подробным логированием. В результате количество сбоев снижается до 0.1% — это подтверждают наши клиенты с 15+ проектами интеграции доставки.

Что даёт интеграция СДЭК

Как мы обеспечиваем надёжность синхронизации статусов?

Используем 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 рабочих дней. Добавление отслеживания через webhook, синхронизация статусов и печать накладных — ещё 3–4 дня. Тестирование в тестовой среде СДЭК обязательно. Стоимость рассчитывается индивидуально.