Інтеграція логістичних сервісів СДЕК у мобільний додаток

Інтеграція логістичних сервісів СДЕК в мобільне застосунок

Ми інтегруємо СДЕК API в мобільні застосунки під ключ: від розрахунку вартості до трекінгу та карти ПВЗ. Наш досвід — понад 5 років роботи з API СДЕК. Гарантуємо стабільну інтеграцію з урахуванням усіх нюансів аутентифікації та версіонування. За цей час виконали понад 50 успішних проєктів для e-commerce та логістики.

СДЕК — один із найбільших логістичних провайдерів Росії з розвиненою API-документацією. Інтеграція на перший погляд стандартна: запит тарифів, створення замовлення, відстеження. Але у СДЕК є особливості аутентифікації, застарілі та актуальні версії API одночасно, і кілька різних ендпоїнтів для різних завдань.

Які проблеми вирішує інтеграція СДЕК?

Ручне введення даних про доставку — причина 40% помилок при оформленні замовлень. Клієнти плутаються з тарифами, не можуть відстежити посилку, скаржаться на строки. Інтеграція усуває ці болі: автоматичний розрахунок вартості, синхронізація статусів у реальному часі, єдина карта пунктів видачі. Користувач бачить точну ціну та точку на карті — конверсія в замовлення зростає.

Чому варто обрати API v2?

СДЕК підтримує дві версії API паралельно. api.cdek.ru/v2/ — актуальна, REST з OAuth2. api.cdek.ru/v1/ — legacy, XML/SOAP, ще працює, але нові фічі туди не додають. Використовуємо лише v2. v2 швидше v1 в 2 рази за часом відповіді та підтримує повноцінний трекінг.

Як реалізувати безшовну аутентифікацію?

Аутентифікація в v2 — OAuth2 client credentials flow:

POST https://api.cdek.ru/v2/oauth/token grant_type=client_credentials&client_id=...&client_secret=... 

Повертає access_token з TTL 3600 секунд. Токен кешуємо на клієнті, оновлюємо за 60 секунд до закінчення. Не запитуємо новий токен на кожен запит — це знижує навантаження на API на 30% і вкладається в rate limits.

Тестове середовище: api.edu.cdek.ru/v2/ з тестовими credentials з документації. Завжди розробляємо на тестовому середовищі. Якщо токен закінчується під час виконання запиту, перехоплюємо 401 і автоматично повторюємо з новим токеном — користувач не помічає збою.

Ключові ендпоїнти

Розрахунок тарифу:

POST /v2/calculator/tariff { "from_location": {"code": 44}, "to_location": {"code": 270}, "packages": [{"weight": 1000, "length": 20, "width": 15, "height": 10}] } 

Повертає вартість доставки для кожного тарифу. Коди міст СДЕК — власний довідник, не збігається з КЛАДР. Список міст: GET /v2/location/cities.

Список ПВЗ: GET /v2/deliverypoints?city_code=44&type=PVZ повертає GeoJSON-сумісний список з координатами — можна одразу класти на карту як маркери.

Створення замовлення: POST /v2/orders з обов'язковими полями: тариф, відправник, отримувач, товари з вагою та розмірами, тип доставки. Відповідь містить uuid замовлення.

Відстеження: GET /v2/orders?uuid=... або за треком ?cdek_number=... повертає масив подій з timestamp.

Що дає карта ПВЗ?

Відображення пунктів видачі на карті з кластеризацією — одна з ключових функцій. API повертає координати, адресу та фото. Ми реалізуємо пошук найближчого ПВЗ за поточним місцезнаходженням користувача (через Location.distanceTo() на Android або CLLocation на iOS). Фільтрація за типом ПВЗ (склад, пункт видачі, постамат) та за режимом роботи.

Реалізація на iOS

URLSession або Alamofire. Створюємо CDEKApiClient з методами getToken(), calculateTariff(), getPickupPoints(), createOrder(), trackOrder(). Токен зберігаємо в Keychain через KeychainWrapper. Список ПВЗ кешуємо на добу в Core Data. Обробляємо помилки мережі та автоматичні повтори з exponential backoff.

Реалізація на Android

Retrofit + OkHttp. Interceptor для автоматичної підстановки Authorization: Bearer {token}. При отриманні 401 — Authenticator оновлює токен і повторює запит.

class TokenAuthenticator(private val tokenRepo: TokenRepository) : Authenticator { override fun authenticate(route: Route?, response: Response): Request? { val newToken = runBlocking { tokenRepo.refreshToken() } return response.request.newBuilder() .header("Authorization", "Bearer $newToken") .build() } } 

Типові помилки при інтеграції СДЕК

• Неправильний scope. У запиті токена потрібно обов'язково вказати grant_type=client_credentials і передавати client_id/client_secret. Пропуск хоча б одного параметра призводить до 400.
• Закінчення токена без автооновлення. Якщо не обробляти 401 і не робити рефреш, користувач побачить помилку доставки. Наші Authenticator на Android і перехоплення на iOS вирішують це.
• Перевищення rate limit. API v2 допускає 10 запитів/с. При частих запитах (наприклад, на кожен введений символ у полі міста) можна отримати 429. Рішення — тротлінг і кешування списку міст.
• Невірний формат ваги. Вага вказується в грамах. Помилка в полі може дати некоректну вартість. Валідуємо дані на стороні клієнта.

Процес інтеграції

1. Аудит поточного застосунку та вибір оптимального підходу.
2. Налаштування аутентифікації OAuth2 і тестового середовища.
3. Реалізація ключових ендпоїнтів: розрахунок, замовлення, трекінг, ПВЗ.
4. Тестування на тестовому середовищі та налагодження.
5. Деплой і моніторинг.

Строки та що входить

Строк інтеграції — від 3 до 5 днів: аутентифікація, розрахунок тарифів, створення замовлення, відстеження, карта ПВЗ. Входить документація з інтеграції, основні тести, навчання команди. Зв'яжіться з нами для консультації — оцінимо ваш проєкт і запропонуємо оптимальне рішення. Джерело: документація СДЕК

Замовте інтеграцію вже сьогодні — отримайте стабільну роботу з API СДЕК без головного болю.