CDEK Logistics Integration into a Mobile App

We integrate the CDEK API into mobile apps turnkey: from cost calculation to tracking and pickup point map. Our experience — over 5 years with the CDEK API. We guarantee stable integration accounting for all authentication and versioning nuances. We have completed over 50 successful projects for e-commerce and logistics.

CDEK is one of Russia's largest logistics providers with well-developed API documentation. Integration seems standard at first: tariff request, order creation, tracking. But CDEK has authentication peculiarities, both obsolete and current API versions simultaneously, and several different endpoints for different tasks.

What Problems Does CDEK Integration Solve?

Manual data entry for delivery causes 40% of errors during order placement. Customers get confused with tariffs, cannot track their parcel, and complain about delivery times. Integration eliminates these pains: automatic cost calculation, real-time status synchronization, unified pickup point map. The user sees the exact price and point on the map — conversion increases.

Why Choose API v2?

CDEK supports two API versions in parallel. api.cdek.ru/v2/ is the current REST version with OAuth2. api.cdek.ru/v1/ is legacy XML/SOAP, still working but no new features are added. We use only v2. v2 is 2 times faster in response time and supports full tracking.

How to Implement Seamless Authentication?

Authentication in v2 is 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. We cache the token on the client and refresh it 60 seconds before expiration. Not requesting a new token on each request reduces API load by 30% and stays within rate limits.

Test environment: api.edu.cdek.ru/v2/ with test credentials from the documentation. We always develop on the test environment. If the token expires during a request, we intercept 401 and automatically retry with a new token — the user sees no interruption.

Key Endpoints

Tariff calculation:

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

Returns delivery cost for each tariff. CDEK city codes are their own reference, not matching KLADR. City list: GET /v2/location/cities.

Pickup points list: GET /v2/deliverypoints?city_code=44&type=PVZ returns a GeoJSON-compatible list with coordinates — ready to be placed on a map as markers.

Order creation: POST /v2/orders with mandatory fields: tariff, sender, receiver, items with weight and dimensions, delivery type. Response contains uuid of the order.

Tracking: GET /v2/orders?uuid=... or by track ?cdek_number=... returns an array of events with timestamps.

What Does the Pickup Point Map Provide?

Displaying pickup points on a map with clustering is one of the key features. The API returns coordinates, address, and photo. We implement search for the nearest pickup point by the user's current location (via Location.distanceTo() on Android or CLLocation on iOS). Filtering by pickup point type (warehouse, pickup point, post office) and by working hours.

Implementation on iOS

URLSession or Alamofire. Create CDEKApiClient with methods getToken(), calculateTariff(), getPickupPoints(), createOrder(), trackOrder(). Store token in Keychain via KeychainWrapper. Cache pickup points for one day in Core Data. Handle network errors and automatic retries with exponential backoff.

Implementation on Android

Retrofit + OkHttp. Interceptor to automatically add Authorization: Bearer {token}. On 401 — Authenticator updates token and retries the request.

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() } } 

Typical Integration Errors with CDEK

• Incorrect scope. In the token request, you must specify grant_type=client_credentials and pass client_id/client_secret. Missing any parameter leads to 400.
• Token expiration without auto-refresh. If 401 is not handled and refreshed, the user sees a delivery error. Our Authenticator on Android and interceptor on iOS solve this.
• Rate limit exceeded. API v2 allows 10 requests/second. Frequent requests (e.g., on each character input in the city field) can result in 429. Solution: throttling and caching the city list.
• Incorrect weight format. Weight is specified in grams. Wrong field value can give incorrect cost. We validate data on the client side.

Integration Process

1. Audit of the current app and selection of the optimal approach.
2. OAuth2 authentication setup and test environment configuration.
3. Implementation of key endpoints: calculation, order, tracking, pickup points.
4. Testing on the test environment and debugging.
5. Deployment and monitoring.

Timeline and What's Included

Integration timeline — from 3 to 5 days: authentication, tariff calculation, order creation, tracking, pickup point map. Included: integration documentation, basic tests, team training. Contact us for a consultation — we will assess your project and offer the optimal solution. Source: CDEK documentation

Order integration today — get stable work with the CDEK API without headaches.