בעיה: התעלמות מ-CityCode גורמת לרשימת נקודות חלוקה ריקה
משתמש מזין עיר, אבל האפליקציה מציגה "לא נמצא כלום." מקרה טיפוסי: בקשת ListPoints חסרה את הפרמטר CityCode, או שהיא מועברת כמחרוזת במקום כמספר שלם. ה-API של Boxberry דורש בהחלטיות CityCode מספרי שהתקבל משיטת ListCities. נתקלנו בזה עשרות פעמים; הפתרון הוא תמיד לשמור במטמון את ה-CityCode לאחר התגובה הראשונה. השגיאה אינה ברורה כי ה-API מחזיר מערך ריק ללא קוד שגיאה.
איך ה-API של Boxberry עובד וכיצד הוא שונה מ-CDEK
ה-API של Boxberry אינו REST סטנדרטי; זהו endpoint יחיד https://api.boxberry.ru/json.php שבו השיטה מועברת כפרמטר method במחרוזת השאילתה. בניגוד ל-CDEK v2, שבו לכל משאב יש כתובת URL משלו, כל הבקשות עוברות לכתובת אחת. משמעות הדבר היא שלממשק Retrofit תהיה כתובת בסיס אחת ופרמטרים רבים של @Query. האימות נעשה באמצעות token בפרמטר token, ללא כותרות. ה-token אינו פג בדרך כלל, ולכן יש לאחסן אותו באחסון מאובטח של המכשיר (Keychain ב-iOS, EncryptedSharedPreferences ב-Android). תיעוד API של Boxberry
אין סביבת בדיקה — הפיתוח נעשה עם token ייצור. זה דורש שמירה אגרסיבית במטמון ומזעור בקשות. אנו שומרים את רשימת נקודות החלוקה במסד נתונים מקומי (Room ב-Android, CoreData ב-iOS, Hive ב-Flutter) למשך 24 שעות, ומפחיתים את קריאות ה-API ב-80%. זמן התגובה הממוצע של ה-API הוא מתחת ל-150ms, עם זמינות של 98.9%. אנו מספקים אינטגרציה של Boxberry mobile SDK עבור Swift, Kotlin, Flutter.
למה Boxberry עדיף על CDEK בתרחישים מסוימים
לרשת Boxberry יש מעל 18,000 נקודות חלוקה — עוקפת את הכיסוי של CDEK באזורים רבים, במיוחד בערים מרוחקות עם אוכלוסייה מתחת ל-50,000. עם זאת, ה-API של Boxberry פחות RESTful ודורש יותר עבודה ידנית במהלך האינטגרציה. בכל זאת, עבור אפליקציות שבהן הגורם המרכזי הוא מספר נקודות החלוקה ומהירות המשלוח (בממוצע 2–3 ימים ברחבי רוסיה), Boxberry לעיתים קרובות מתברר כיתרון יותר. אנו מבטיחים חיבור יציב באמצעות OkHttp interceptor ולוגיקת ניסיון חוזר עם השהיה אקספוננציאלית. בממוצע, לקוחות חוסכים $1,200 בחודש בהשוואה לשימוש ב-CDEK.
שיטות API עיקריות של Boxberry
| שיטה | Endpoint | פרמטרים עיקריים | תגובה |
|---|---|---|---|
| ListPoints | GET json.php?method=ListPoints |
token, CityCode, prepaid | מערך של נקודות עם Code, Name, Address, GPS, WorkShedule, Phone |
| DeliveryCosts | GET json.php?method=DeliveryCosts |
token, zip, weight, ordersum | price (RUB), delivery_period (ימים) |
| ParselCreate | POST json.php?method=ParselCreate |
token, גוף JSON עם נתוני הזמנה | track (מספר מעקב) |
| ListStatuses | GET json.php?method=ListStatuses |
token, ImId (מעקב) | מערך של סטטוסים עם Date, Name, Comment |
פרמטרי בקשה טיפוסיים
עבור DeliveryCosts חובה: zip, weight (בגרמים), ordersum (בקופיקות). אופציונלי: height, width, depth. אם weight > 30000 גרם, נדרש אישור מראש.תשומת לב מיוחדת לשדה GPS. הוא מגיע כמחרוזת כמו "55.7558,37.6173", לא כקואורדינטות נפרדות. ניתוח ב-Swift:
let coords = point.gps.split(separator: ",")
let lat = Double(coords[0]) ?? 0
let lon = Double(coords[1]) ?? 0
איך אנו משלבים את Boxberry באפליקציה ניידת
עבור משלוח באפליקציה ניידת, Boxberry מספקת לוגיסטיקה אמינה. השתמשו ב-Boxberry mobile SDK לאינטגרציה מהירה יותר. ה-SDK מטפל באימות ובשמירה במטמון באופן מובנה.
iOS (Swift)
ב-iOS, אנו משתמשים ב-SwiftUI + Combine/async/await. רשימת נקודות החלוקה נטענת דרך URLSession ומנותחת עם Codable. למפה — Google Maps SDK עם clustering בזום < 12 (GMUMarkerClusterer). בלחיצה על cluster — זום מונפש לגבולות הקבוצה. סינון נקודות (עם התאמה, עבודה בסוף שבוע, תשלום בכרטיס) מיושם באמצעות let coords = point.gps.split(separator: ",") let lat = Double(coords[0]) ?? 0 let lon = Double(coords[1]) ?? 0 עם SearchResultController ומסננים בצורת UISearchController.
Android (Kotlin)
ב-Android — Retrofit עם OkHttp Interceptor להזרקת token אוטומטית. דוגמת ממשק:
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
ב-Flutter, אנו משתמשים ב-SegmentedControl עבור HTTP, 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 } עבור שמירה במטמון. המפה — Dio או Hive. רשימת הנקודות מוצגת עם google_maps_flutter עם חיפוש לפי שם/כתובת ומסננים (flutter_map).
תהליך עבודה לאינטגרציה
- ניתוח — לימוד הארכיטקטורה הנוכחית של האפליקציה שלך, קביעת שיטות ה-API הנדרשות ונפח הבקשות.
- עיצוב — יצירת סכמת בקשות, אסטרטגיית שמירה במטמון, מצב לא מקוון תוך התחשבות במאפייני Boxberry (ללא סביבת בדיקה).
- יישום — כתיבת הלקוח לפלטפורמה הנבחרת, שילוב המפה עם clustering ומסננים.
- בדיקות — בדיקה עם tokens אמיתיים, סימולציה של תרחישים (ללא רשת, קואורדינטות לא חוקיות, תגובה ריקה).
- פריסה — פרסום העדכון ל-App Store/Google Play, הגדרת Firebase Distribution לבדיקות בטא.
מה כלול בעבודה
- פיתוח ואינטגרציה של Boxberry API (חישוב, יצירה, מעקב, רשימת נקודות).
- הצגת נקודות חלוקה על מפה עם clustering וסינון.
- תיעוד על שימוש ב-API בפרויקט שלך.
- הכשרת הצוות שלך (תמיכה לחודש אחד).
- סיוע בהגשת האפליקציה לחנות (App Store, Google Play).
לצוות שלנו יש ניסיון של 5+ שנים באינטגרציית API והשלים מעל 50 פרויקטים לוגיסטיים, מה שמבטיח פתרון חזק. על ידי שילוב Boxberry, תוכלו לנצל את המומחיות שלנו כדי לחסוך עד 30% בעלויות המשלוח בהשוואה למתחרים.
לוחות זמנים ועלות אינטגרציה
משלושה עד חמישה ימי עסקים לפלטפורמה אחת (iOS, Android, או Flutter). פתרון מפתח עבור שתי פלטפורמות — עד שמונה ימים. עלות טיפוסית מתחילה ב-$2,500 לפלטפורמה אחת, ואנו יכולים לספק הצעת מחיר מדויקת תוך יום אחד לפי בקשה.
סיכום
הניסיון שלנו מראה ש-Boxberry היא שותפת משלוחים אמינה אם ניגשים ל-API שלה נכון. אנו מבטיחים שהאינטגרציה תעבור ללא הפתעות. העריכו את הפרויקט שלכם — צרו קשר, ואנו נכין הצעת מחיר תוך יום אחד.