A user enters an address in your app — the system returns 400 Bad Request. Russian Post rejects the request due to invalid data format. The Russian Post REST API seems simple, but developers face pitfalls: double Basic authorization, SOAP protocol for tracking instead of REST, mandatory address normalization via FIAS or Dadata. Let's break it down. For example, when calculating tariffs, weight must be in grams and response cost in kopecks. One mistake in units — and the price in the app differs by 100 times. In this article, we share real solutions: how to set up authorization without 401 errors, why tracking is better proxied through a backend, and how to normalize addresses via Dadata. We compare performance of direct SOAP calls and JSON proxy.
We are a mobile development team with 5 years of experience integrating transport APIs (Russian Post, CDEK, Boxberry). We've mastered each service's nuances and completed over 30 integrations. Our engineers adapt integration to any architecture — SwiftUI, Jetpack Compose, Flutter. Order a turnkey integration — from documentation analysis to store publication. Let's evaluate your project for free.
How to Properly Set Up Authorization?
- Obtain login and password from your Russian Post personal account.
- Form the Basic header:
Authorization: Basic base64(login:password). - Get an API token for the specified contract in the "Integration" section.
- Add a second header:
X-User-Authorization: Basic base64(token). - Test the tariff method (
POST /1.0/tariff).
Authorization via Basic Auth with two headers is the first pitfall. The token from the personal account is not the user password. We guarantee that after debugging you won't see a 401. In our practice, a client struggled with authorization for a month — we resolved it in one call.
Why Does Tracking Require a Backend Proxy?
Tracking is the most requested feature. Request to get statuses:
POST https://tracking.russianpost.ru/rtm34?wsdl Tracking API works via SOAP, not REST. For mobile apps, we wrap it in a backend proxy — parsing SOAP on the device is cumbersome; it's easier to return clean JSON to the client. Direct SOAP calls from a mobile app are a bad idea: each status update requires parsing XML with 20+ operations. A proxy server on Node.js or Firebase Functions processes this data 3-5 times faster on a mobile device. The list of operations for one shipment can contain 20+ entries. On the screen, we show the latest status and a brief history. Decoding operation codes is in a separate directory on the developer portal. More about the protocol: SOAP.
Why Does the API Require Address Normalization?
The Russian Post API does not accept arbitrary strings. It requires an index from the official directory or FIAS. We integrate Dadata for normalization: the user enters part of the address, and suggestions return a structured response with the index and FIAS code. This reduces errors by 80% compared to manual input. According to official Russian Post documentation, the address must contain a valid postal index — otherwise, the request is rejected with error 400.
Integration Scenarios Comparison
| Feature | Timelines | Complexity | Recommended Stack |
|---|---|---|---|
| Only tracking | 5–7 days | Low | Swift/Combine, Kotlin/Flow |
| Full sending cycle | 2–3 weeks | Medium | + Firebase Cloud Functions, WorkManager |
| Label generation | +3–5 days | High | + Zebra SDK, UIPrintInteractionController |
Typical Errors and Their Solutions
| Error | Cause | Solution |
|---|---|---|
| 400 Bad Request | Invalid address or weight format | Check normalization via Dadata, ensure weight in grams |
| 401 Unauthorized | Wrong login/password or token | Separate Authorization and X-User-Authorization headers, check token expiry |
| 500 Internal Server Error | Server internal error | Retry with exponential backoff, cache successful responses |
How to Update Statuses in the Background?
We update tracking not on user request but in the background: on iOS — BGAppRefreshTask, on Android — WorkManager with PeriodicWorkRequest interval of at least 15 minutes. When status changes, send a local push notification. Cache the list of track numbers and last statuses — the user sees data even without internet. This is especially important for marketplaces where the courier may be in a poor coverage area.
Label Generation
If the app is used for sending parcels (e-commerce, marketplace), a full cycle is needed: order creation → batch formation → label request (PDF, format F7 or F7p). Labels can be printed on a thermal printer via Bluetooth — on iOS use UIPrintInteractionController, on Android PrintManager. Integration with Zebra or Honeywell printers via their SDK adds another 2-3 days to the timeline.
What's Included in the Work
- Integration documentation (proxy scheme, endpoint descriptions)
- Configured access to Russian Post test and production environments
- Source code module in Swift/Kotlin/Dart with comments
- Unit and integration tests for key scenarios
- Team training (2 hours online)
- 2 weeks of post-release support
Our Experience
We are a mobile development studio with 5 years of experience. We have completed 30+ integrations with delivery services (Russian Post, CDEK, Boxberry). We hold an App Development with Swift certification and Google Play Console authorization. Every project undergoes code review and load testing. Get a consultation — tell us about your app, and we'll propose the optimal integration architecture.