SDEK Logistics Services Integration into Mobile Apps
SDEK is one of Russia's largest logistics providers with well-documented APIs. Integration at first glance is standard: request rates, create order, track shipment. But SDEK has authentication quirks, legacy and current API versions simultaneously, and multiple endpoints for different tasks.
API v2 vs v1: What to Use
SDEK supports two API versions in parallel. api.cdek.ru/v2/—current, REST with OAuth2. api.cdek.ru/v1/—legacy, XML/SOAP, still works, but new features not added. Use only v2.
Authentication in v2—OAuth2 client credentials flow:
POST https://api.cdek.ru/v2/oauth/token
grant_type=client_credentials&client_id=...&client_secret=...
Returns access_token with TTL 3600 seconds. Cache token on client, refresh 60 seconds before expiry. Don't request new token per request—slow and violates rate limits.
Test environment: api.edu.cdek.ru/v2/ with test credentials EMscd6r9JnFiQ3bLoyjJY6eM78JV9wbo / PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kG from docs. Always develop in test environment.
Key Endpoints
Calculate tariff:
POST /v2/calculator/tariff
{
"from_location": {"code": 44}, // SDEK city code, not FIAS
"to_location": {"code": 270},
"packages": [{"weight": 1000, "length": 20, "width": 15, "height": 10}]
}
Returns delivery cost per tariff. SDEK city codes—proprietary reference, not matching KLADR. City list: GET /v2/location/cities.
List pickup points:
GET /v2/deliverypoints?city_code=44&type=PVZ
Returns GeoJSON-compatible list with coordinates—directly put markers on map.
Create order:
POST /v2/orders
Minimum required fields: tariff, sender, recipient, items with weight/dimensions, delivery type (door or pickup point). Response contains uuid of order—save for tracking.
Track:
GET /v2/orders?uuid=...
or by track:
GET /v2/orders?cdek_number=...
Returns statuses—event array with timestamp and Russian description.
iOS Implementation
URLSession or Alamofire. Create CDEKApiClient with methods getToken(), calculateTariff(), getPickupPoints(), createOrder(), trackOrder(). Store token in Keychain via KeychainWrapper. Not in UserDefaults—those are credentials.
Pickup point list—cache for a day in Core Data: points change rarely, but requesting on every screen open—unnecessary API load.
Android Implementation
Retrofit + OkHttp. Interceptor for automatic Authorization: Bearer {token} injection in every request. On 401 response—Authenticator refreshes token and automatically retries. This frees business logic from manual token management.
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()
}
}
Pickup Point Map
Display points on Google Maps with clustering (ClusterManager). Tap marker—BottomSheetDialog with address, hours, photo. Find nearest PVZ—ST_DWithin if filtering on server, or locally via sort by Location.distanceTo().
Timeline: three-five days—authentication, tariff calculation, order creation, tracking, PVZ map.