Інтеграція логістичних сервісів СДЕК у мобільний додаток
СДЕК — один із найбільших логістичних провайдерів з розвиненою API-документацією. Інтеграція на перший погляд стандартна: запит тарифів, створення замовлення, відстеження. Але у СДЕК є особливості аутентифікації, застарілі та актуальні версії API одночасно, та кілька різних ендпоінтів для різних завдань.
API v2 vs v1: що використовувати
СДЕК підтримує дві версії API паралельно. api.cdek.ru/v2/ — актуальна, REST з OAuth2. api.cdek.ru/v1/ — legacy, XML/SOAP, ще працює, але нові функції туди не додають. Використовуємо тільки v2.
Аутентифікація в 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 секунд до істечення. Не запитуємо новий токен на кожен запит — це повільно та порушує rate limits.
Тестове середовище: api.edu.cdek.ru/v2/ з тестовими credentials EMscd6r9JnFiQ3bLoyjJY6eM78JV9wbo / PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kG з документації. Завжди розробляємо на тестовому середовищі.
Ключові ендпоінти
Розрахунок тарифу:
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=...
або по треку:
GET /v2/orders?cdek_number=...
Повертає statuses — масив событій з timestamp та описом.
Реалізація на iOS
URLSession або Alamofire. Створюємо CDEKApiClient з методами getToken(), calculateTariff(), getPickupPoints(), createOrder(), trackOrder(). Токен зберігаємо в Keychain через KeychainWrapper. Не в UserDefaults — то credentials.
Список ПВЗ — кешуємо на добу в Core Data: пункти видачи рідко змінюються, а запитувати при кожному відкритті екрана — непотрібне навантаження API.
Реалізація на 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()
}
}
Карта ПВЗ
Список пунктів видачи відображаємо на Google Maps з кластеризацією (ClusterManager). При натисканні на маркер — BottomSheetDialog з адресою, режимом роботи, фото. Пошук найближчого ПВЗ — через ST_DWithin якщо фільтруємо на сервері, або локально через сортування по Location.distanceTo().
Тривалість: три-п'ять днів — аутентифікація, розрахунок тарифів, створення замовлення, відстеження, карта ПВЗ.