Пользователь вводит адрес в приложении — система возвращает 400 Bad Request. Почта России отклоняет запрос из-за невалидного формата данных. REST API Почты России кажется простым, но на практике разработчиков ждут ловушки: двойная Basic-авторизация, SOAP-протокол для трекинга вместо REST, обязательная нормализация адресов через ФИАС или Dadata. Разберёмся по порядку. Например, при расчёте тарифа вес нужно указывать в граммах, а стоимость ответа — в копейках. Одна ошибка в единицах — и цена в приложении отличается в 100 раз. В этой статье делимся реальными решениями: как настроить авторизацию без ошибок 401, почему трекинг лучше проксировать через бэкенд, и как нормализовать адреса через Dadata. Сравним производительность прямого SOAP-вызова и JSON-прокси.
Мы — команда мобильных разработчиков с 5-летним опытом интеграции транспортных API (Почта России, СДЭК, Boxberry). За это время мы разобрались в нюансах каждого сервиса и провели более 30 интеграций. Наши инженеры адаптируют интеграцию под любую архитектуру — SwiftUI, Jetpack Compose, Flutter. Закажите интеграцию под ключ — от анализа документации до публикации в сторах. Оценим проект бесплатно.
Как правильно настроить авторизацию?
- Получите логин и пароль в личном кабинете Почты России.
- Сформируйте Basic-заголовок:
Authorization: Basic base64(login:password). - Получите API-токен для указанного договора в разделе «Интеграция».
- Добавьте второй заголовок:
X-User-Authorization: Basic base64(токен). - Протестируйте метод получения тарифа (
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.
Сравнение интеграционных сценариев
| Функция | Сроки | Сложность | Рекомендуемый стек |
|---|---|---|---|
| Только трекинг | 5–7 дней | Низкая | Swift/Combine, Kotlin/Flow |
| Полный цикл отправки | 2–3 недели | Средняя | + Firebase Cloud Functions, WorkManager |
| Генерация этикеток | +3–5 дней | Высокая | + Zebra SDK, UIPrintInteractionController |
Типичные ошибки и их решения
| Ошибка | Причина | Решение |
|---|---|---|
| 400 Bad Request | Неверный формат адреса или веса | Проверить нормализацию через Dadata, убедиться, что вес в граммах |
| 401 Unauthorized | Неправильные логин/пароль или токен | Разделять заголовки Authorization и X-User-Authorization, проверять срок действия токена |
| 500 Internal Server Error | Внутренняя ошибка сервера | Повторить с экспоненциальной задержкой, кэшировать успешные ответы |
Как обновлять статусы в фоне?
Трекинг обновляем не по запросу пользователя, а в фоне: на 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 и нагрузочное тестирование. Получите консультацию — расскажите о вашем приложении, и мы предложим оптимальную архитектуру интеграции.