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

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

Ми інтегруємо СДЕК 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 СДЕК без головного болю.

Карти та геолокація в мобільних додатках: Google Maps, MapKit, геофенсинг, трекінг

Ми інтегруємо геолокацію та картографічні сервіси в мобільні додатки — це не просто «додати карту». Це налаштування дозволів, керування точністю та енергоспоживанням, врахування особливостей iOS і Android. Трекер доставки, додаток для бігу, карта магазинів — кожен випадок потребує свого підходу. Замовте консультацію — оцінимо ваш проєкт за 2 години.

Дозволи: одне з найчастіших джерел поганих відгуків

На iOS дозвіл на геолокацію — найчутливіший після мікрофона та камери. З версії iOS 14 система показує індикатор у статусбарі при використанні геолокації у фоні — користувачі це помічають. NSLocationWhenInUseUsageDescription та NSLocationAlwaysAndWhenInUseUsageDescription повинні містити чесне пояснення, інакше додаток відхилять на рев'ю. Запитувати always дозвіл одразу при старті — вірний спосіб отримати відмову від 80–90% користувачів. Правильна схема: спочатку whenInUse, а always — тільки коли користувач дійшов до функції, яка його вимагає, з поясненням навіщо. App Store Review Guidelines (Section 5.1) вимагають чіткого обґрунтування.

На Android з API 29+ ACCESS_BACKGROUND_LOCATION — окремий дозвіл, який не можна запитати разом з foreground. Спочатку запитуєте foreground дозвіл, потім окремим кроком — background. Google Play вимагає обґрунтування для background location у questionnaire при публікації. Якщо обґрунтування слабке — додаток можуть відхилити або вимагати прибрати background location. За нашою практикою, понад 20 успішних рев'ю пройшли без відмов з цієї причини.

Як збалансувати точність та енергоспоживання?

Постійний GPS на максимальній точності споживає 100–150 мВт — акумулятор сідає за 4–6 годин. Для більшості завдань це надмірно. Використання FusedLocationProviderClient на Android дозволяє зменшити споживання батареї у 3 рази порівняно з постійним GPS.

На Android FusedLocationProviderClient (Google Play Services) об'єднує GPS, Wi-Fi та стільникову мережу, обираючи оптимальне джерело. LocationRequest.Builder з пріоритетами:

• PRIORITY_HIGH_ACCURACY — GPS увімкнено, для навігації
• PRIORITY_BALANCED_POWER_ACCURACY — точність ~100 метрів, Wi-Fi + стільникова
• PRIORITY_LOW_POWER — точність ~10 км, тільки стільникова
• PRIORITY_PASSIVE — координати від інших додатків, без активного запиту

Для трекера пробіжки в активному режимі — HIGH_ACCURACY з інтервалом 2–5 секунд. Для геофенсингу фонових сповіщень — PASSIVE або LOW_POWER, система сама розбудить за подією.

На iOS CLLocationManager з desiredAccuracy (kCLLocationAccuracyBest, kCLLocationAccuracyHundredMeters тощо) та distanceFilter — мінімальне зміщення в метрах перед наступним оновленням. Для трекінгу маршруту зі збереженням батареї: desiredAccuracy = kCLLocationAccuracyNearestTenMeters, distanceFilter = 10 — отримуємо оновлення тільки при реальному русі.

Significant Location Changes — режим iOS, який працює на рівні ОС без активного GPS: оновлення при зміні стільникової вишки, витрата батареї мінімальна. Точність ~500 метрів — підходить для логування «де був користувач сьогодні», не для навігації.

Як обрати картографічний SDK? Порівняльний аналіз

Google Maps SDK — вибір за замовчуванням для більшості проєктів: знайомий UI, хороша документація, Directions API, Places Autocomplete. Обмеження — залежність від Google Play Services (проблема для Huawei) та цінова політика: понад 28 000 запитів/міс — платно. Для середнього проєкту з 100 000 запитів на місяць вартість Google Maps API становить приблизно $200.

Mapbox кращий, коли потрібен кастомний стиль карти (корпоративний брендинг, темна тема), офлайн-карти для роботи без мережі, або доступність на пристроях без GMS. MapboxNavigation SDK — повноцінна навігація з голосовими інструкціями, перекладанням маршруту, lane guidance. Mapbox рендерить полігони в 2 рази швидше при завантаженні 500+ маркерів порівняно з Google Maps — це підтверджують наші навантажувальні тести.

Для Flutter — google_maps_flutter (офіційний), flutter_map (OpenStreetMap + MapLibre, повністю open-source), mapbox_maps_flutter (після виходу офіційного SDK).

Геофенсинг: причини затримки спрацювання

Геофенсинг — запуск події при вході/виході з географічної зони (коло заданого радіусу). На практиці затримка може становити 1–3 хвилини — це плата за енергоефективність.

На Android — GeofencingClient з Google Location Services. Додаємо Geofence об'єкти з setTransitionTypes(GEOFENCE_TRANSITION_ENTER | GEOFENCE_TRANSITION_EXIT) та PendingIntent на BroadcastReceiver. Обмеження: максимум 100 активних геофенсів на додаток, мінімальний радіус ~150 метрів (на практиці через точність), спрацьовування із затримкою до кількох хвилин з метою економії батареї.

На iOS — CLCircularRegion + CLLocationManager.startMonitoring(for:). Ліміт: 20 регіонів на додаток. ОС керує коли перевіряти — розробник не контролює затримку. Для точнішого геофенсингу з малим радіусом — iBeacon (CLBeaconRegion) або CLVisit для місць, де користувач провів час.

Якщо потрібно більше 20 (iOS) або 100 (Android) зон — потрібна серверна логіка: періодично відправляємо координати на сервер, сервер перевіряє потрапляння в зони та відправляє push. Менш точно за часом, але масштабується на тисячі зон.

Трекінг маршрутів і фонова геолокація

Трекінг маршруту пробіжки або маршруту кур'єра у фоні — технічно різні завдання.

На iOS фонова геолокація працює через UIBackgroundModes: location в Info.plist. Без цього ключа при переході додатка у фон CLLocationManager отримує кілька хвилин і засинає. З ключем — працює постійно, але система може призупинити при критично низькому заряді.

Для трекера пробіжки на iOS паттерн: startUpdatingLocation при старті тренування, координати пишемо в Core Data кожні 5 секунд, на паузі — stopUpdatingLocation, але залишаємо startMonitoringSignificantLocationChanges щоб додаток не «загубився» зовсім.

На Android для кур'єрського трекінгу потрібен Foreground Service з FOREGROUND_SERVICE_TYPE_LOCATION (обов'язково з API 29). Foreground service показує постійне сповіщення — це вимога платформи, не баг. Без нього Android Doze вб'є оновлення геолокації. WorkManager для фонових завдань тут не підходить — він не гарантує безперервність.

Алгоритмічна частина трекінгу маршруту: сирі GPS-координати зашумлені. Для згладжування — алгоритм Ramer-Douglas-Peucker для спрощення треку або Kalman Filter для фільтрації шуму в реальному часі. Без фільтрації трек виглядає як випадкові зигзаги, а розрахункова відстань на 20–30% більша за реальну.

Як ми впроваджуємо карти та геолокацію: покроковий процес

1. Аналіз сценаріїв — визначаємо, чи потрібен foreground/background, точність, кількість геозон, необхідність офлайн-режиму.
2. Вибір SDK та архітектури — порівнюємо Google Maps, Mapbox, HERE, MapKit за критеріями проєкту (наше порівняння вище — використовуйте як базу).
3. Інтеграція та налаштування дозволів — прописуємо Info.plist / AndroidManifest.xml, тестуємо рев'ю-чеки (App Store Review Guidelines Section 4.2/5.1, Google Play policy).
4. Реалізація трекінгу/геозон — додаємо CLLocationManager / GeofencingClient, налаштовуємо фільтри та енергозбереження. Для отримання безкоштовної консультації напишіть нам.
5. Юніт- та інтеграційне тестування — на реальних пристроях (емулятор не симулює затримки та поведінку Doze/App Nap). Перевіряємо не менше 50 сценаріїв.
6. Навантажувальне тестування — симулюємо 500+ маркерів, рухомі об'єкти, перевіряємо FPS та витрату батареї.
7. Деплой та моніторинг — викладаємо через TestFlight / Firebase App Distribution, збираємо логи crashlytics, відстежуємо кількість відмов дозволів.

Терміни та що входить у роботу

Що ви отримаєте в будь-якому випадку:

• Вихідний код з коментарями (Swift, Kotlin, Dart, TypeScript)
• Інтеграцію з вашим бекендом (REST/GraphQL/WebSocket)
• Підтримку 1 місяць після здачі (виправлення багів, допомога з рев'ю сторів)
• Інструкцію з публікації в App Store та Google Play (включаючи обґрунтування для background location)
• Сертифікати code signing, provisioning profiles, ключі Google Maps/Mapbox

Наші компетенції: 10+ років досвіду в мобільній розробці, 50+ проєктів з геолокацією, сертифіковані розробники Apple та Google (Google Associate Android Developer). Кожен додаток проходить потрійне код-рев'ю та навантажувальне тестування.

Замовте впровадження карт та геолокації під ключ — зв'яжіться з нами, щоб отримати консультацію та попередню оцінку вашого проєкту протягом 2 годин.