משתמש מזין כתובת באפליקציה שלך — המערכת מחזירה 400 Bad Request. דואר רוסיה דוחה את הבקשה עקב פורמט נתונים לא תקין. ה-REST API של דואר רוסיה נראה פשוט, אבל מפתחים נתקלים במלכודות: אימות Basic כפול, פרוטוקול SOAP למעקב במקום REST, ונורמליזציה חובה של כתובות דרך FIAS או Dadata. בואו נפרק את זה. לדוגמה, בחישוב תעריפים, משקל חייב להיות בגרמים ותשובת העלות בקופיקות. טעות אחת ביחידות — והמחיר באפליקציה שונה פי 100. במאמר זה, אנו חולקים פתרונות אמיתיים: איך להגדיר אימות ללא שגיאות 401, למה עדיף לנתב מעקב דרך backend, ואיך לנרמל כתובות דרך Dadata. אנו משווים ביצועים של קריאות SOAP ישירות מול JSON proxy.
אנחנו צוות פיתוח מובייל עם 5 שנות ניסיון בשילוב APIs של תחבורה (דואר רוסיה, CDEK, Boxberry). שלטנו בניואנסים של כל שירות והשלמנו מעל 30 אינטגרציות. המהנדסים שלנו מתאימים אינטגרציה לכל ארכיטקטורה — SwiftUI, Jetpack Compose, Flutter. הזמינו אינטגרציה סוהר — מניתוח תיעוד ועד פרסום בחנות. בואו נבחן את הפרויקט שלכם.
איך להגדיר אימות כראוי?
- קבלו שם משתמש וסיסמה מחשבון אישי של דואר רוסיה.
- צרו את כותרת Basic:
Authorization: Basic base64(login:password). - קבלו API token עבור החוזה שצוין בסעיף "אינטגרציה".
- הוסיפו כותרת שנייה:
X-User-Authorization: Basic base64(токен). - בדקו את שיטת התעריף (
POST /1.0/tariff).
אימות דרך Basic Auth עם שתי כותרות הוא המלכודת הראשונה. ה-token מהחשבון האישי אינו סיסמת המשתמש. אנו מבטיחים שאחרי ניפוי באגים לא תראו 401. בניסיון שלנו, לקוח נאבק עם אימות במשך חודש — פתרנו את זה בשיחה אחת.
למה מעקב דורש backend proxy?
מעקב הוא התכונה המבוקשת ביותר. בקשה לקבלת סטטוסים:
POST https://tracking.russianpost.ru/rtm34?wsdl מעקב API עובד דרך SOAP, לא REST. עבור אפליקציות מובייל, אנו עוטפים אותו ב-backend proxy — ניתוח SOAP במכשיר הוא מסורבל; קל יותר להחזיר JSON נקי ללקוח. קריאות SOAP ישירות מאפליקציית מובייל הן רעיון רע: כל עדכון סטטוס דורש ניתוח XML עם 20+ פעולות. שרת proxy על Node.js או Firebase Functions מעבד נתונים אלה פי 3-5 מהר יותר במכשיר נייד. רשימת הפעולות עבור משלוח אחד יכולה להכיל 20+ רשומות. על המסך, אנו מציגים את הסטטוס העדכני והיסטוריה קצרה. פענוח קודי פעולות נמצא בספרייה נפרדת בפורטל המפתחים. עוד על הפרוטוקול: SOAP.
למה ה-API דורש נורמליזציה של כתובות?
ה-API של דואר רוסיה אינו מקבל מחרוזות שרירותיות. הוא דורש מיקוד מהספרייה הרשמית או FIAS. אנו משלבים Dadata לנורמליזציה: המשתמש מזין חלק מהכתובת, והצעות מחזירות תשובה מובנית עם מיקוד וקוד FIAS. זה מפחית שגיאות ב-80% בהשוואה להזנה ידנית. לפי התיעוד הרשמי של דואר רוסיה, הכתובת חייבת להכיל מיקוד תקף — אחרת, הבקשה נדחית עם שגיאה 400.
השוואת תרחישי אינטגרציה
| תכונה | לוחות זמנים | מורכבות | טכנולוגיות מומלצות |
|---|---|---|---|
| מעקב בלבד | 5–7 ימים | נמוכה | Swift/Combine, Kotlin/Flow |
| מחזור שליחה מלא | 2–3 שבועות | בינונית | + Firebase Cloud Functions, WorkManager |
| יצירת תוויות | +3–5 ימים | גבוהה | + Zebra SDK, UIPrintInteractionController |
שגיאות נפוצות ופתרונותיהן
| שגיאה | סיבה | פתרון |
|---|---|---|
| 400 Bad Request | כתובת או פורמט משקל לא תקינים | בדקו נורמליזציה דרך Dadata, ודאו שמשקל בגרמים |
| 401 Unauthorized | שם משתמש/סיסמה או token שגויים | הפרידו כותרות Authorization ו-X-User-Authorization, בדקו תוקף token |
| 500 Internal Server Error | שגיאה פנימית בשרת | נסו שוב עם השהיה אקספוננציאלית, שמרו תשובות מוצלחות במטמון |
איך לעדכן סטטוסים ברקע?
אנו מעדכנים מעקב לא לפי בקשת משתמש אלא ברקע: ב-iOS — POST https://tracking.russianpost.ru/rtm34?wsdl , ב-Android — BGAppRefreshTask עם מרווח WorkManager של לפחות 15 דקות. כשהסטטוס משתנה, שלחו התראת push מקומית. שמרו במטמון רשימת מספרי מעקב וסטטוסים אחרונים — המשתמש רואה נתונים גם ללא אינטרנט. זה חשוב במיוחד עבור מרקטים שבהם השליח עשוי להיות באזור עם כיסוי חלש.
יצירת תוויות
אם האפליקציה משמשת לשליחת חבילות (e-commerce, מרקט), יש צורך במחזור מלא: יצירת הזמנה → יצירת אצווה → בקשת תווית (PDF, פורמט F7 או F7p). ניתן להדפיס תוויות במדפסת תרמית דרך Bluetooth — ב-iOS השתמשו ב-PeriodicWorkRequest, ב-Android UIPrintInteractionController. אינטגרציה עם מדפסות Zebra או Honeywell דרך ה-SDK שלהן מוסיפה 2-3 ימים ללוח הזמנים.
מה כלול בעבודה
- תיעוד אינטגרציה (תרשים proxy, תיאורי נקודות קצה)
- גישה מוגדרת לסביבות בדיקה וייצור של דואר רוסיה
- מודול קוד מקור ב-Swift/Kotlin/Dart עם הערות
- בדיקות יחידה ואינטגרציה לתרחישים מרכזיים
- הדרכת צוות (שעתיים אונליין)
- שבועיים של תמיכה לאחר השקה
הניסיון שלנו
אנחנו סטודיו לפיתוח מובייל עם 5 שנות ניסיון. השלמנו 30+ אינטגרציות עם שירותי משלוחים (דואר רוסיה, CDEK, Boxberry). אנו מחזיקים בהסמכת App Development with Swift והרשאת Google Play Console. כל פרויקט עובר בדיקת קוד ובדיקות עומס. קבלו ייעוץ — ספרו לנו על האפליקציה שלכם, ואנו נציע ארכיטקטורת אינטגרציה אופטימלית.