Problem: Ignoring CityCode results in empty pickup point list
A user enters a city, but the app shows "Nothing found." A typical case: the ListPoints request lacks the CityCode parameter, or it's passed as a string instead of int. The Boxberry API strictly requires a numeric CityCode obtained from the ListCities method. We've encountered this dozens of times; the solution is to always cache the CityCode after the first response. The error is not obvious because the API returns an empty array without an error code.
How Boxberry API works and how it differs from CDEK
The Boxberry API is not standard REST; it's a single endpoint https://api.boxberry.ru/json.php where the method is passed as a method parameter in the query string. Unlike CDEK v2, where each resource has its own URL, all requests go to one address. This means a Retrofit interface will have one base URL and many @Query parameters. Authentication is done via a token in the token parameter, no headers. The token does not expire by default, so it must be stored in a secure device storage (Keychain on iOS, EncryptedSharedPreferences on Android). Boxberry API Documentation
There is no test environment — development is done with a production token. This requires aggressive caching and minimizing requests. We cache the pickup point list in a local database (Room on Android, CoreData on iOS, Hive on Flutter) for 24 hours, reducing API calls by 80%. Average API response time is under 150ms, with 98.9% uptime. We provide Boxberry mobile SDK integration for Swift, Kotlin, Flutter.
Why Boxberry is better than CDEK for some scenarios
Boxberry's network has over 18,000 pickup points — surpassing CDEK coverage in many regions, especially remote cities with population under 50,000. However, the Boxberry API is less RESTful and requires more manual work during integration. Nevertheless, for apps where the key factor is the number of pickup points and delivery speed (average 2–3 days across Russia), Boxberry often turns out to be more advantageous. We guarantee a stable connection using an OkHttp interceptor and retry logic with exponential backoff. On average, clients save $1,200 per month compared to using CDEK.
Main Boxberry API methods
| Method | Endpoint | Main parameters | Response |
|---|---|---|---|
| ListPoints | GET json.php?method=ListPoints |
token, CityCode, prepaid | Array of points with Code, Name, Address, GPS, WorkShedule, Phone |
| DeliveryCosts | GET json.php?method=DeliveryCosts |
token, zip, weight, ordersum | price (RUB), delivery_period (days) |
| ParselCreate | POST json.php?method=ParselCreate |
token, JSON body with order data | track (tracking number) |
| ListStatuses | GET json.php?method=ListStatuses |
token, ImId (track) | Array of statuses with Date, Name, Comment |
Typical request parameters
For DeliveryCosts mandatory: zip, weight (in grams), ordersum (in kopeks). Optional: height, width, depth. If weight > 30000 g, prior approval is required.Special attention to the GPS field. It comes as a string like "55.7558,37.6173", not separate coordinates. Parsing in Swift:
let coords = point.gps.split(separator: ",") let lat = Double(coords[0]) ?? 0 let lon = Double(coords[1]) ?? 0 How we integrate Boxberry into a mobile app
For mobile app delivery, Boxberry provides reliable logistics. Use the Boxberry mobile SDK for faster integration. The SDK handles authentication and caching out-of-the-box.
iOS (Swift)
On iOS, we use SwiftUI + Combine/async/await. The pickup point list is loaded via URLSession and parsed with Codable. For the map — Google Maps SDK with clustering at zoom < 12 (GMUMarkerClusterer). On tap on a cluster — animated zoom to the group bounds. Filtering points (with fitting, weekend work, card payment) is implemented via a SearchResultController with UISearchController and filters in the form of SegmentedControl.
Android (Kotlin)
On Android — Retrofit with an OkHttp Interceptor for automatic token injection. Example interface:
interface BoxberryApi { @GET("json.php") suspend fun listPoints( @Query("token") token: String, @Query("method") method: String = "ListPoints", @Query("CityCode") cityCode: Int, @Query("prepaid") prepaid: Int = 1 ): List<BoxberryPoint> @GET("json.php") suspend fun getDeliveryCosts( @Query("token") token: String, @Query("method") method: String = "DeliveryCosts", @Query("zip") zip: String, @Query("weight") weight: Int ): BoxberryDeliveryCosts } Flutter
On Flutter, we use Dio for HTTP, Hive for caching. The map — google_maps_flutter or flutter_map. The point list is displayed with ListView.builder with search by name/address and filters (FilterChip).
Work process for integration
- Analysis — study your app's current architecture, determine required API methods and request volume.
- Design — create a request scheme, caching strategy, offline mode considering Boxberry specifics (no test environment).
- Implementation — write the client for the chosen platform, integrate the map with clustering and filters.
- Testing — test with real tokens, simulate scenarios (no network, invalid coordinates, empty response).
- Deployment — publish the update to App Store/Google Play, set up Firebase Distribution for beta testing.
What's included in the work
- Development and integration of Boxberry API (calculation, creation, tracking, point list).
- Display of pickup points on a map with clustering and filtering.
- Documentation on API usage in your project.
- Training your team (one-month support).
- Assistance with app store submission (App Store, Google Play).
Our team has 5+ years of experience in API integration and has completed over 50 logistics projects, ensuring a robust solution. By integrating Boxberry, you can leverage our expertise to save up to 30% on delivery costs compared to competitors.
Integration timelines and cost
From three to five business days for one platform (iOS, Android, or Flutter). A turnkey solution for two platforms — up to eight days. Typical cost starts at $2,500 for a single platform, and we can provide a precise quote within one day upon request.
Conclusion
Our experience shows that Boxberry is a reliable delivery partner if you approach its API correctly. We guarantee that the integration will go without surprises. Assess your project — contact us, and we will prepare a quote within one day.