Інтеграція логістичних сервісів Російської пошти в мобільний додаток
Російська пошта надає REST API для трекінгу відправлень, розрахунку тарифів, оформлення замовлень на доставку та генерації етикеток. Документація існує, але робота з нею вимагає розуміння ряду невочевидних обмежень.
API Російської пошти: що доступно
Офіційний портал розробників — otpravka.pochta.ru. Два основних розділи:
Відправка (Shipment API): створення замовлень, оформлення партій, генерація PDF-етикеток, розрахунок вартості доставки. Вимагає договір з Російською поштою та вихід токена через особистий кабінет.
Трекінг (Tracking API): відслідковування відправлень за трек-номером. Доступний у двох режимах — Single (один запит на один трек-номер, обмеження 100 запитів на день) та Batch (до 3000 трек-номерів за запит, вимагає окремої угоди).
Авторизація та типові помилки
Авторизація через Basic Auth: Authorization: Basic base64(login:password) плюс заголовок X-User-Authorization: Basic base64(token). Два різні заголовки — це перше, на чому спотикаються. Токен з особистого кабінету — не пароль користувача.
Розрахунок тарифів (POST /1.0/tariff) приймає object-type (посилка, лист, бандероль), вагу в грамах, поштові індекси відправника та одержувача. Повертає вартість у копійках — ділимо на 100. Без перетворення одиниць додаток покаже ціну в 100 разів більшою.
Адресні дані. API вимагає індекси у форматі ФІАС або довідника Російської пошти. Довільну адресу "вул. Ленина, 5" API не зрозуміє — потрібна попередня нормалізація через сервіс адресних підсказок.
Реалізація трекінгу в мобільному додатку
Трекінг — найпопулярніша функція. Запит на отримання статусів:
POST https://tracking.russianpost.ru/rtm34?wsdl
Важливо: Tracking API працює через SOAP, а не REST. Для мобільного додатка оборачиваємо в backend-прокси — парсити SOAP на пристрої громіздко, простіше повернути чистий JSON клієнту.
Список операцій (статусів) для однієї відправки може містити 20+ записів. На екрані показуємо останній статус та стислу історію. Коди операцій публічні, але розшифровка — у окремому довіднику на порталі розробників.
Фонове оновлення статусів
Трекінг оновлюємо не за запитом користувача, а у фоні: на iOS — BGAppRefreshTask, на Android — WorkManager з PeriodicWorkRequest з інтервалом мінімум 15 хвилин. При зміні статусу відправляємо локальне push-уведомлення.
Кешуємо список трек-номерів та останні статуси локально — користувач повинен бачити дані навіть без інтернету.
Генерація етикеток
Якщо додаток використовується для відправки посилок (e-commerce, маркетплейс), потрібен повний цикл: створення замовлення → формування партії → запит етикетки (PDF, формат F7 або F7п). Етикетку можна друкувати на термопринтері через Bluetooth — на iOS використовуємо UIPrintInteractionController, на Android PrintManager. Інтеграція з принтерами Zebra або Honeywell через їхній SDK додає ще 2-3 дні.
Терміни: інтеграція трекінгу — 5-7 днів. Повний цикл відправки з генерацією етикеток — 2-3 тижні.