Интеграция логистических сервисов СДЭК в мобильное приложение
СДЭК — один из крупнейших логистических провайдеров России с развитой 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().
Срок: три-пять дней — аутентификация, расчёт тарифов, создание заказа, отслеживание, карта ПВЗ.