Интеграция Почты России в мобильное приложение

Пользователь вводит адрес в приложении — система возвращает 400 Bad Request. Почта России отклоняет запрос из-за невалидного формата данных. REST API Почты России кажется простым, но на практике разработчиков ждут ловушки: двойная Basic-авторизация, SOAP-протокол для трекинга вместо REST, обязательная нормализация адресов через ФИАС или Dadata. Разберёмся по порядку. Например, при расчёте тарифа вес нужно указывать в граммах, а стоимость ответа — в копейках. Одна ошибка в единицах — и цена в приложении отличается в 100 раз. В этой статье делимся реальными решениями: как настроить авторизацию без ошибок 401, почему трекинг лучше проксировать через бэкенд, и как нормализовать адреса через Dadata. Сравним производительность прямого SOAP-вызова и JSON-прокси.

Мы — команда мобильных разработчиков с 5-летним опытом интеграции транспортных API (Почта России, СДЭК, Boxberry). За это время мы разобрались в нюансах каждого сервиса и провели более 30 интеграций. Наши инженеры адаптируют интеграцию под любую архитектуру — SwiftUI, Jetpack Compose, Flutter. Закажите интеграцию под ключ — от анализа документации до публикации в сторах. Оценим проект бесплатно.

Как правильно настроить авторизацию?

1. Получите логин и пароль в личном кабинете Почты России.
2. Сформируйте Basic-заголовок: Authorization: Basic base64(login:password).
3. Получите API-токен для указанного договора в разделе «Интеграция».
4. Добавьте второй заголовок: X-User-Authorization: Basic base64(токен).
5. Протестируйте метод получения тарифа (POST /1.0/tariff).

Авторизация через Basic Auth с двумя заголовками — первая ловушка. Токен из личного кабинета — не пароль пользователя. Мы гарантируем, что после отладки вы не увидите 401. В нашей практике был проект, где клиент месяц не мог пройти авторизацию — помогли за один созвон.

Почему трекинг требует бэкенд-прокси?

Трекинг — самая востребованная функция. Запрос на получение статусов:

POST https://tracking.russianpost.ru/rtm34?wsdl

Tracking API работает через SOAP, а не REST. Для мобильного приложения оборачиваем в backend-прокси — парсить SOAP на устройстве громоздко, проще возвращать клиенту чистый JSON. Прямой вызов SOAP из мобильного приложения — плохая идея: каждое обновление статуса требует разбора XML с 20+ операциями. Прокси-сервер на Node.js или Firebase Functions обрабатывает эти данные в 3-5 раз быстрее на мобильном устройстве. Список операций для одного отправления может содержать 20+ записей. На экране показываем последний статус и краткую историю. Расшифровка кодов операций — в отдельном справочнике на портале разработчика. Подробнее о протоколе SOAP.

Почему API требует нормализации адресов?

API Почты России не принимает произвольные строки. Требуется индекс из официального справочника или ФИАС. Мы подключаем сервис Dadata для нормализации: пользователь вводит часть адреса, а подсказки возвращают структурированный ответ с индексом и кодом ФИАС. Это сокращает количество ошибок на 80% по сравнению с ручным вводом. Согласно официальной документации Почты России, адрес должен содержать корректный почтовый индекс — иначе запрос отклоняется с ошибкой 400.

Сравнение интеграционных сценариев

Типичные ошибки и их решения

Как обновлять статусы в фоне?

Трекинг обновляем не по запросу пользователя, а в фоне: на iOS — BGAppRefreshTask, на Android — WorkManager с PeriodicWorkRequest интервалом не менее 15 минут. При изменении статуса отправляем локальный пуш-нотификацию. Кэшируем список трек-номеров и последние статусы — пользователь видит данные даже без интернета. Это особенно важно для маркетплейсов, где курьер может быть в зоне плохого покрытия.

Генерация этикеток

Если приложение используется для отправки посылок (e-commerce, маркетплейс), нужен полный цикл: создание заказа → формирование партии → запрос этикетки (PDF, формат F7 или F7п). Этикетку можно печатать на термопринтере через Bluetooth — на iOS используем UIPrintInteractionController, на Android PrintManager. Интеграция с принтерами Zebra или Honeywell через их SDK добавляет ещё 2-3 дня к сроку.

Что входит в работу

• Документация по интеграции (схема прокси, описание эндпоинтов)
• Настроенные доступы к тестовому и боевому контуру Почты
• Исходный код модуля на Swift/Kotlin/Dart с комментариями
• Unit-тесты и интеграционные тесты для key-сценариев
• Обучение вашей команды (2 часа онлайн)
• Поддержка 2 недели после релиза

Наш опыт

Мы — студия мобильной разработки с 5-летним стажем. За плечами 30+ интеграций с сервисами доставки (Почта России, СДЭК, Boxberry). У нас есть сертификат App Development with Swift и авторизация Google Play Console. Каждый проект проходит code review и нагрузочное тестирование. Получите консультацию — расскажите о вашем приложении, и мы предложим оптимальную архитектуру интеграции.

Интеграция API в мобильное приложение: с чего начать

Запрос уходит, ответ не приходит, timeout — 30 секунд. Пользователь смотрит на спиннер. Сети нет — мобильная карта в метро. Или сеть есть, но сервер вернул 200 с HTML-страницей ошибки вместо JSON — и приложение крашит при JSONDecoder.decode(). Мы видим такие кейсы на каждом втором проекте. Поэтому интеграция API в мобильное приложение — это не просто вызов endpoint'а, а проектирование надёжного сетевого слоя: обработка ошибок, кэширование, offline-режим, certificate pinning. Закажите аудит текущего сетевого слоя — оценим проект за 1 день.

Почему стандартные библиотеки недостаточны? URLSession и OkHttp предоставляют базовый HTTP-клиент, но для production нужны retry с exponential backoff, валидация статус-кодов, типизированная десериализация и мониторинг состояния сети. Без этого приложение теряет данные и пользователей. Мы уже 5 лет занимаемся мобильной разработкой и реализовали более 30 проектов с интеграцией API на iOS, Android и Flutter — от стартапов до enterprise-решений.

Как выбрать протокол для интеграции 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%. Экономия трафика составила около 15 000 ₽ в месяц при 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 отслеживают состояние сети и триггерят обновление.

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.

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 — запросы с пересекающимися данными обновляют кеш без дублирования. Apollo GraphQL Documentation

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 (меньше зависимостей).

gRPC: для высоконагруженных сервисов

gRPC с protobuf — бинарная сериализация: меньше размер, быстрее парсинг. grpc-swift для iOS, grpc-kotlin для Android. Protobuf-схема компилируется в типизированные классы. Streaming (server-side, client-side, bidirectional) — нативная возможность. Порог применения: высокая частота запросов (trading, IoT) или критичная latency. Для обычного CRUD REST проще в дебаге и мониторинге.

Certificate Pinning и безопасность

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

Что входит в работу

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

Сроки и стоимость

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