Повна інтеграція СДЕК на сайт: від розрахунку вартості до відстеження посилок
Ми інтегруємо сервіс СДЕК на ваш сайт під ключ. Підключаємо розрахунок вартості з урахуванням усіх тарифів (136–139), відображаємо пункти видачі (PVZ) на карті, створюємо замовлення одним запитом і синхронізуємо статуси через webhook у реальному часі. Базова версія готова за 5–7 робочих днів. Зв'яжіться з нами — оцінимо ваш проект. Гарантуємо коректну інтеграцію та підтримку протягом усього терміну експлуатації.
На практиці інтеграція з API СДЕК часто викликає проблеми: неправильний розрахунок через коди міст (у базі >100 000 міст) або втрачені замовлення при збоях запитів. Ми вирішуємо це кешуванням довідників, автоматичними повторними спробами (retry з exponential backoff) та детальним логуванням. У результаті кількість збоїв знижується до 0.1% — це підтверджують наші клієнти з 15+ проектами інтеграції доставки. Автоматизація через API в 5 разів швидша за ручну обробку.
Що дає інтеграція СДЕК
| Компонент | Результат |
|---|---|
| Розрахунок вартості | Актуальні тарифи з урахуванням ваги, габаритів і типу доставки (двері/ПВЗ) |
| Карта ПВЗ | Інтерактивна карта з фільтрацією за містом, вагою, наявністю готівки |
| Створення замовлень | Автоматичне створення замовлення в СДЕК при оформленні на сайті |
| Відстеження | Статуси в реальному часі через webhook (CREATED, ACCEPTED, READY, DELIVERED) |
| Документація та навчання | Опис API, приклади коду, інструкція для операторів |
Що входить у вартість
- Технічне завдання та архітектура інтеграції
- Повний код інтеграції на вашому стеку (авторизація, калькулятор, ПВЗ, замовлення, webhook)
- Документація API та інструкція для операторів
- Тестування в тестовому середовищі СДЕК
- Навчання вашої команди (1 вебінар)
- Підтримка протягом 3 місяців після здачі
Як інтегрувати: крок за кроком
- Отримайте ключі API СДЕК (client_id та client_secret) в особистому кабінеті.
- Налаштуйте OAuth 2.0 авторизацію з кешуванням токена (див. приклад нижче).
- Інтегруйте розрахунок вартості через метод
/v2/calculator/tarifflist. - Додайте карту ПВЗ з допомогою методу
/v2/deliverypoints. - Реалізуйте створення замовлення через
/v2/orders. - Налаштуйте webhook для отримання статусів.
Як ми забезпечуємо надійність синхронізації статусів?
Використовуємо webhook-повідомлення. Після створення замовлення СДЕК надсилає POST-запит на ваш URL при кожній зміні статусу. Це швидше та дешевше за polling. Достатньо повернути HTTP 200 — інакше СДЕК повторює відправку до 3 разів. Ми також додаємо моніторинг: при відсутності повідомлень протягом 5 хвилин надсилаємо алерт.
Які дані потрібні для розрахунку вартості?
Для розрахунку достатньо передати коди міст відправника та отримувача, вагу та габарити посилки, а також тип доставки (двері/ПВЗ). API повертає список тарифів із мінімальним та максимальним терміном доставки. Ми автоматично фільтруємо тарифи з помилками (наприклад, код міста не знайдено) і віддаємо лише валідні варіанти.
Порівняння ручної та автоматичної обробки замовлень
| Критерій | Ручна обробка | Наша інтеграція |
|---|---|---|
| Час на замовлення | 15–20 хвилин | 2–3 секунди |
| Помилки введення даних | до 5% | <0.1% |
| Оновлення статусів | ручний опит | автоматичний webhook |
| Вартість підтримки | висока (оплата оператора) | мінімальна (один раз налаштували) |
Стек та інструменти
- Авторизація: 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);
}
Етапи робіт
| Етап | Що робимо | Результат |
|---|---|---|
| Аналітика | Вивчаємо ваш сайт, вимоги, підбираємо оптимальні тарифи та методи інтеграції | Технічне завдання |
| Проектування | Проектуємо архітектуру: сервіси, кешування, обробка помилок | Документація |
| Реалізація | Пишемо код інтеграції: авторизація, розрахунок, ПВЗ, замовлення, webhook | Робочий код на вашому стеку |
| Тестування | Перевіряємо в тестовому середовищі СДЕК, імітуємо всі сценарії, виправляємо помилки | Протокол тестування |
| Деплой | Перемикаємо на бойові credentials, налаштовуємо моніторинг | Інтеграція в продакшені |
Терміни та вартість орієнтовно
Базова інтеграція (розрахунок вартості + ПВЗ на карті + створення замовлень) — 5–7 робочих днів, від 15 000 грн. Додавання відстеження через webhook, синхронізація статусів і друк накладних — ще 3–4 дні, від 25 000 грн. Тестування в тестовому середовищі СДЕК обов'язкове.
Типові помилки та як їх уникнути
- Некоректний код міста. Використовуйте метод
/location/citiesі кешуйте довідник. - Закінчення токена. Кешуйте токен із запасом 100 секунд, як у прикладі.
- Неправильні габарити. Усі розміри в см, вага в грамах, інакше розрахунок невірний.
- Втрата webhook. Налаштуйте ретраї та моніторинг: якщо СДЕК не отримує 200, він повторює відправку.
Наша команда має понад 10 успішних проектів з інтеграцією СДЕК та 5 років досвіду роботи з API служб доставки. Офіційна документація API СДЕК доступна за посиланням. Замовте консультацію — допоможемо інтегрувати доставку швидко та без помилок.