Інтеграція логістичних сервісів Білпошти в мобільний додаток

Ми часто стикаємося із задачею: власники e-commerce проектів у Білорусі втрачають до 20% клієнтів через невидимість посилок. Наша команда спеціалізується на інтеграції Білпошти в мобільний додаток та мобільній логістиці Білпошти, щоб трекінг, розрахунок вартості доставки Білпошти та карта відділень Білпошти працювали без збоїв. Розповімо, як це зробити правильно, спираючись на досвід 50+ реалізованих проектів.

Проблема: розрив між інтернет-магазином і реальною логістикою

Коли клієнт оформлює замовлення, а потім не бачить його статус, навантаження на підтримку зростає: кожен п'ятий запит — «Де моє замовлення?». Калькулятор доставки на сайті Білпошти — окремий сервіс, який не вбудований у додаток. Інтеграція через офіційний API закриває ці діри: трекінг у реальному часі, калькуляція тарифів прямо в кошику та геолокація найближчих відділень.

Як інтегрувати трекінг Білпошти в додаток?

Публічний API трекінгу повертає історію відправлення за номером формату S10 (14 символів, наприклад CP123456789BY). Валідацію робимо регулярним виразом ^[A-Z]{2}[0-9]{9}[A-Z]{2}$. Відповідь містить коди операцій (101 — прийнято, 102 — на сортуванні, 201 — доставлено) та тексти російською та білоруською. Для багатомовних додатків локалізацію потрібно обробляти окремо: сервер надсилає локалізований текст, а не ключ.

Покрокова інструкція:

1. Виконати асинхронний GET-запит до ендпоінту /api/v1/track?code={track_number} через URLSession з конфігурацією URLSessionConfiguration.
2. Отримати JSON-відповідь і десеріалізувати її через JSONDecoder (Swift) або Gson (Kotlin). Для Belpochta API Swift використовуємо async/await, для Belpochta integration Kotlin — Retrofit та Coroutines.
3. Відобразити статус в UI: для трекінг S10 SwiftUI застосовуємо LazyVStack з секціями, обробляючи помилки через Result type (iOS) або sealed class (Android).
4. Кешувати відповіді за допомогою URLCache (iOS) та LruCache (Android), оновлювати у фоні через Background Fetch (iOS) або WorkManager (Android).

Приклад запиту:

GET /api/v1/track?code=CP123456789BY

{
  "track": {
    "code": "CP123456789BY",
    "status": "delivered",
    "operations": [
      {"code": 101, "date": "2025-03-01", "location": "Minsk"},
      {"code": 201, "date": "2025-03-05", "location": "Gomel"}
    ]
  }
}

Відповідь парсимо через JSONDecoder (Swift) або Gson (Kotlin). Підтримуємо async/await для iOS 15+ та Coroutines для Android. Для надійності використовуємо кешування (NSCache на iOS, LruCache на Android) і повторні спроби з експоненційною затримкою.

Чому парсинг публічного калькулятора — не рішення?

Багато хто намагається заощадити час і парсить веб-калькулятор. Це призводить до трьох проблем:

• нестабільність: при будь-якій зміні HTML/JS парсер ламається;
• юридичні ризики: порушення умов використання сайту;
• немає підтримки корпоративних тарифів.

Офіційний API працює в 5 раз стабільніше (99,9% uptime проти ~80% у парсера) та в 7 раз швидше (120 мс проти 800 мс). Кращий шлях — укласти договір з Білпоштою та отримати доступ до закритого API. Він дозволяє розраховувати тарифи, створювати електронні супровідні документи та отримувати статистику.

Додаткове порівняння продуктивності (на 10 000 запитів):

Карта відділень: 3300 точок на карті

Білпошта налічує понад 3300 відділень. Для відображення найближчих використовуємо публічний JSON-довідник (оновлюється раз на тиждень) або API геолокації. На iOS — MapKit з кастомними анотаціями, на Android — Google Maps SDK або MapLibre для офлайну. Фільтруємо за режимом роботи, типом послуг (EMS, грошові перекази). Згідно з документацією Білпошти, всі відділення мають актуальні координати, що спрощує геопошук.

Що дає інтеграція: цифри та факти

• Зниження навантаження на підтримку: до 60% питань «Де посилка?» відпадає.
• Збільшення конверсії в кошику: +15% при наявності калькулятора доставки, що в 1.5 рази більше порівняно з відсутністю.
• Час відгуку трекінгу: <200 мс для 95% запитів.
• Середній проект окупається за 2–3 місяці, приносячи економію до €500 на місяць на підтримці.
• Для великих магазинів (1000+ замовлень/день) додаткова виручка від підвищення конверсії може становити €2000+ щомісяця.
• Вартість базової інтеграції трекінгу стартує від €500.
• Економія на підтримці до €500/міс та додатковий дохід до €2000/міс.

Під ключ: що входить в інтеграцію

Ми беремо на себе весь цикл:

• аналіз вимог та прототипування;
• проектування мережевого шару (APIManager на Swift, Retrofit на Android);
• реалізація трекінгу, калькулятора, карти;
• тестування на реальних пристроях (iOS 14–17, Android 10–14) з використанням URLProtocol (iOS) та MockWebServer (Android);
• публікація в App Store / Google Play з урахуванням гайдлайнів;
• документація та навчання підтримки.

Строки та гарантії

Базова інтеграція трекінгу — від 3 до 5 днів. Комплексне рішення з розрахунком тарифів та картою відділень — 2–3 тижні після отримання доступу до API. Ми гарантуємо стабільну роботу інтеграції протягом 6 місяців: якщо API Білпошти зміниться, адаптуємо код безкоштовно. Досвід нашої команди — понад 10 років у мобільній розробці та 50+ проектів у сфері логістики та електронної комерції.

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

Наші послуги охоплюють усі ключові напрями: інтеграція Білпошти мобільний додаток, трекінг Білпошти API, розрахунок вартості доставки Білпошти, карта відділень Білпошти, мобільна логістика Білпошта, Belpochta API Swift, Belpochta integration Kotlin, трекінг S10 SwiftUI, парсинг калькулятора Білпошти, доставка в мобільному додатку.

Інтеграція API в мобільний додаток: з чого почати

Запит йде, відповідь не приходить, timeout — 30 секунд. Користувач дивиться на спінер. Мережі немає — мобільна карта в метро. Або мережа є, але сервер повернув 200 з HTML-сторінкою помилки замість JSON — і додаток крашиться при JSONDecoder.decode(). Ми бачимо такі кейси на кожному другому проєкті. Тому інтеграція API в мобільний додаток — це не просто виклик endpoint'у, а проектування надійного мережевого шару: обробка помилок, кешування, offline-режим, certificate pinning. Гарантуємо стабільну роботу навіть при нестабільному з'єднанні — замовте аудит поточного мережевого шару.

Стандартних бібліотек (URLSession, OkHttp) недостатньо для production: вони надають лише базовий HTTP-клієнт. Для реальної експлуатації потрібні retry з exponential backoff, валідація статус-кодів, типізована десеріалізація та моніторинг стану мережі. Без цього додаток втрачає дані та користувачів. Ми маємо понад 5 років досвіду в мобільній розробці, реалізували 30+ проєктів з інтеграцією API на iOS, Android та Flutter — від стартапів до enterprise-рішень. Сертифіковані iOS/Android розробники гарантують якість коду.

Як вибрати протокол для інтеграції API?

REST залишається стандартом для більшості проєктів. Але коли на екрані профілю потрібно 5 полів з 40, GraphQL виключає over-fetching і скорочує трафік на 30–60%. gRPC виправданий при тисячах запитів на хвилину (trading, IoT) — бінарна серіалізація в 3–5 разів швидше JSON. WebSocket — єдиний вибір для real-time без polling (повідомлення, сповіщення).

Приклад з практики: для фінтех-додатку ми замінили REST (40 полів) на GraphQL — розмір відповіді скоротився з 12 КБ до 2,5 КБ, час рендеру екрана впав на 70%. Економія трафіку була значною при 100 000 активних користувачів.

Як забезпечити надійність з'єднання та offline-first?

Користувачі втрачають мережу в метро, ліфті, тунелі. Мобільний додаток зобов'язаний працювати без інтернету — хоча б у read-only режимі. Ми впроваджуємо патерн offline-first:

1. При відкритті екрану спочатку показуємо дані з локального кешу (Core Data / Room).
2. Паралельно виконуємо мережевий запит, оновлюємо UI після відповіді.
3. Якщо мережа недоступна — показуємо кешовані дані та позначку «немає з'єднання».
4. При відновленні мережі автоматично синхронізуємо зміни.

Для кешування HTTP-відповідей використовуємо URLCache (iOS) та OkHttp Cache (Android) з підтримкою Cache-Control. Для структурованих даних — SwiftData / Room. NWPathMonitor / ConnectivityManager.NetworkCallback відстежують стан мережі та тригерять оновлення. Connection Pooling і HTTP/2 multiplexing зменшують latency при паралельних запитах.

REST та вибір клієнтської бібліотеки

Alamofire (iOS) — де-факто стандарт для Swift-проєктів. Поверх URLSession додає request chaining, response validation, automatic retry, certificate pinning через ServerTrustManager. AF.request() з .validate() повертає помилку для будь-якого статус-коду поза 200–299. Без .validate() Alamofire вважає 404 та 500 успішними відповідями. З Swift Concurrency — async-версія через serializingDecodable.

Retrofit (Android) — анотаційний HTTP-клієнт поверх OkHttp. Інтерфейс з анотаціями компілюється в реалізацію. @GET, @POST, @Path, @Query, @Body — декларативний опис API. OkHttp під капотом: connection pooling, transparent gzip, HTTP/2 multiplex. HttpLoggingInterceptor — логування в debug-збірці. Authenticator — автоматичний refresh токена при 401. Згідно з OkHttp Official Guide, правильна конфігурація кешу зменшує кількість мережевих запитів на 40%.

Ktor (KMM/Flutter) — мультиплатформний HTTP-клієнт. На iOS працює через Darwin engine (URLSession), на Android — через OkHttp. Єдиний код для обох платформ при KMM-архітектурі.

GraphQL: коли REST не справляється

REST повертає фіксовану структуру. Екран профілю вимагає name, avatar, email — сервер віддає 40 полів. Over-fetching. GraphQL вирішує це: клієнт запитує рівно потрібні поля. Це критично для мобайлу, де трафік і час парсингу — реальні обмеження. Apollo iOS та Apollo Kotlin генерують типізовані класи за схемою: schema.graphql + query-файли → строгі типи на етапі компіляції. Subscriptions через WebSocket — real-time без polling. Обмеження: GraphQL складніше кешувати на рівні HTTP. Apollo використовує нормалізований in-memory кеш InMemoryNormalizedCache — запити з перетинаючимися даними оновлюють кеш без дублювання.

WebSocket: real-time без зайвого трафіку

Polling (setInterval кожні 5 секунд) — витрата батареї та трафіку. WebSocket — постійне двоспрямоване з'єднання. iOS: URLSessionWebSocketTask (нативний, iOS 13+). Android: OkHttp WebSocket. Обов'язкова обробка reconnect: при onFailure — експоненційний backoff (1с → 2с → 4с → 8с → максимум 60с). Socket.IO — надбудова з автоматичним reconnect, але для нових проєктів краще нативний WebSocket (менше залежностей). TLS 1.3 забезпечує безпеку з'єднання.

Чому важливий certificate pinning?

Корпоративний проксі може перехопити HTTPS через підміну сертифіката. Certificate pinning запобігає цьому: додаток приймає тільки конкретний сертифікат або публічний ключ. Alamofire: ServerTrustManager з PinnedCertificatesTrustEvaluator. OkHttp: CertificatePinner з SHA-256 хешем. Операційна складність: при ротації сертифіката старі версії додатку перестають працювати. Рішення — pinning на публічний ключ CA або підтримка кількох пінів з grace period. Правильне впровадження pinning гарантує захист від MITM-атак.

Що входить у роботу

Ми передаємо: вихідний код мережевого шару, документацію по використовуваних бібліотеках, інструкцію з ротації сертифікатів, підтримку протягом 2 тижнів після здачі.

Терміни та вартість

Реалізація мережевого шару з REST, retry, кешуванням та offline-режимом — 1–2 тижні. Додавання GraphQL або WebSocket — ще 1–2 тижні. gRPC — 2–3 тижні, включаючи кодогенерацію. Вартість розраховується індивідуально після аналізу API та вимог до offline-поведінки. Оцінимо проєкт за 1 день — зв'яжіться з нами для консультації. Замовте аудит мережевого шару — отримайте гарантію стабільної роботи під навантаженням.