שילוב CDEK לוגיסטיקה באפליקציה מובייל

שילוב CDEK Logistics באפליקציית מובייל

אנו משלבים את ה-API של CDEK באפליקציות מובייל במתכונת turnkey: מחישוב עלות ועד מעקב ומפת נקודות איסוף. הניסיון שלנו — מעל 5 שנים עם ה-API של CDEK. אנו מבטיחים אינטגרציה יציבה תוך התחשבות בכל ניואנסים של אימות וגרסאות. השלמנו מעל 50 פרויקטים מוצלחים למסחר אלקטרוני ולוגיסטיקה.

CDEK הוא אחד מספקי הלוגיסטיקה הגדולים ברוסיה עם תיעוד API מפותח היטב. האינטגרציה נראית סטנדרטית במבט ראשון: בקשת תעריף, יצירת הזמנה, מעקב. אבל ל-CDEK יש מוזרויות אימות, גרסאות API מיושנות ונוכחיות בו-זמנית, ומספר נקודות קצה שונות למשימות שונות.

אילו בעיות פותר שילוב CDEK?

הזנת נתונים ידנית למשלוח גורמת ל-40% מהשגיאות במהלך ביצוע הזמנה. לקוחות מתבלבלים עם תעריפים, לא יכולים לעקוב אחר החבילה שלהם, ומתלוננים על זמני אספקה. האינטגרציה מבטלת את הכאבים הללו: חישוב עלות אוטומטי, סנכרון סטטוס בזמן אמת, מפת נקודות איסוף אחידה. המשתמש רואה את המחיר המדויק והנקודה על המפה — ההמרה עולה.

למה לבחור ב-API v2?

CDEK תומך בשתי גרסאות API במקביל. api.cdek.ru/v2/ היא גרסת ה-REST הנוכחית עם OAuth2. api.cdek.ru/v1/ היא XML/SOAP legacy, שעדיין עובדת אך לא מתווספות לה תכונות חדשות. אנו משתמשים רק ב-v2. v2 מהירה פי 2 בזמן תגובה ותומכת במעקב מלא.

איך ליישם אימות חלק?

אימות ב-v2 הוא תהליך OAuth2 client credentials:

POST https://api.cdek.ru/v2/oauth/token grant_type=client_credentials&client_id=...&client_secret=... 

מחזיר POST https://api.cdek.ru/v2/oauth/token grant_type=client_credentials&client_id=...&client_secret=... עם TTL של 3600 שניות. אנו שומרים את הטוקן במטמון בצד הלקוח ומרעננים אותו 60 שניות לפני פקיעתו. אי בקשת טוקן חדש בכל בקשה מפחית את עומס ה-API ב-30% ונשאר במגבלות הקצב.

סביבת בדיקה: access_token עם פרטי בדיקה מהתיעוד. אנו תמיד מפתחים בסביבת הבדיקה. אם הטוקן פג במהלך בקשה, אנו מיירטים 401 ומנסים שוב אוטומטית עם טוקן חדש — המשתמש לא רואה שום הפרעה.

נקודות קצה מרכזיות

חישוב תעריף:

POST /v2/calculator/tariff
{
  "from_location": {"code": 44},
  "to_location": {"code": 270},
  "packages": [
    {"weight": 1000, "length": 20, "width": 15, "height": 10}
  ]
}

מחזיר עלות משלוח עבור כל תעריף. קודי הערים של CDEK הם הפניה משלהם, שאינה תואמת ל-KLADR. רשימת ערים: api.edu.cdek.ru/v2/.

רשימת נקודות איסוף: POST /v2/calculator/tariff { "from_location": {"code": 44}, "to_location": {"code": 270}, "packages": [{"weight": 1000, "length": 20, "width": 15, "height": 10}] } מחזירה רשימה תואמת GeoJSON עם קואורדינטות — מוכנה להצבה על מפה כסמנים.

יצירת הזמנה: GET /v2/location/cities עם שדות חובה: תעריף, שולח, מקבל, פריטים עם משקל ומידות, סוג משלוח. התשובה מכילה GET /v2/deliverypoints?city_code=44&type=PVZ של ההזמנה.

מעקב: POST /v2/orders או לפי מספר מעקב uuid מחזיר מערך של אירועים עם חותמות זמן.

מה מספקת מפת נקודות האיסוף?

הצגת נקודות איסוף על מפה עם clustering היא אחת התכונות המרכזיות. ה-API מחזיר קואורדינטות, כתובת ותמונה. אנו מיישמים חיפוש נקודת איסוף קרובה לפי מיקום המשתמש הנוכחי (באמצעות GET /v2/orders?uuid=... באנדרואיד או ?cdek_number=... ב-iOS). סינון לפי סוג נקודת איסוף (מחסן, נקודת איסוף, דואר) ולפי שעות פעילות.

יישום ב-iOS

Location.distanceTo() או CLLocation. צור URLSession עם מתודות Alamofire, CDEKApiClient, getToken(), calculateTariff(), getPickupPoints(). שמור טוקן ב-createOrder() באמצעות trackOrder(). שמור נקודות איסוף במטמון ליום אחד ב-Core Data. טיפול בשגיאות רשת וניסיונות חוזרים אוטומטיים עם exponential backoff.

יישום באנדרואיד

Retrofit + OkHttp. Keychain להוספת KeychainWrapper אוטומטית. על 401 — Interceptor מעדכן טוקן ומנסה שוב את הבקשה.

class TokenAuthenticator(private val tokenRepo: TokenRepository) : Authenticator {
    override fun authenticate(route: Route?, response: Response): Request? {
        val newToken = runBlocking { tokenRepo.refreshToken() }
        return response.request.newBuilder()
            .header("Authorization", "Bearer $newToken")
            .build()
    }
}

שגיאות אינטגרציה טיפוסיות עם CDEK

• Scope שגוי. בבקשת הטוקן, יש לציין Authorization: Bearer {token} ולהעביר Authenticator/class TokenAuthenticator(private val tokenRepo: TokenRepository) : Authenticator { override fun authenticate(route: Route?, response: Response): Request? { val newToken = runBlocking { tokenRepo.refreshToken() } return response.request.newBuilder() .header("Authorization", "Bearer $newToken") .build() } } . חסר כל פרמטר מוביל ל-400.
• פקיעת טוקן ללא רענון אוטומטי. אם 401 לא מטופל ומרענן, המשתמש רואה שגיאת משלוח. ה-Authenticator שלנו באנדרואיד וה-interceptor ב-iOS פותרים זאת.
• חריגה ממגבלת קצב. API v2 מאפשר 10 בקשות/שנייה. בקשות תכופות (למשל, על כל הזנת תו בשדה העיר) יכולות לגרום ל-429. פתרון: throttling ושמירת רשימת הערים במטמון.
• פורמט משקל שגוי. משקל מצוין בגרמים. ערך שדה שגוי יכול לתת עלות לא נכונה. אנו מאמתים נתונים בצד הלקוח.

תהליך האינטגרציה

1. ביקורת על האפליקציה הנוכחית ובחירת הגישה האופטימלית.
2. הגדרת אימות OAuth2 והגדרת סביבת בדיקה.
3. יישום נקודות קצה מרכזיות: חישוב, הזמנה, מעקב, נקודות איסוף.
4. בדיקה בסביבת הבדיקה וניפוי שגיאות.
5. פריסה וניטור.

ציר זמן ומה כלול

ציר זמן אינטגרציה — מ-3 עד 5 ימים: אימות, חישוב תעריף, יצירת הזמנה, מעקב, מפת נקודות איסוף. כלול: תיעוד אינטגרציה, בדיקות בסיסיות, הדרכת צוות. צור קשר לייעוץ — נבחן את הפרויקט שלך ונציע פתרון אופטימלי. מקור: תיעוד CDEK

הזמן אינטגרציה היום — קבל עבודה יציבה עם ה-API של CDEK ללא כאבי ראש.