שילוב בלפושטה באתר שלך: חישוב, מעקב, API

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

התעריפים של Belpochta תלויים במשקל, מרחק ונפח. למשלוחים בינלאומיים, חל משקל נפחי (אורך × רוחב × גובה / 5000), שלעתים קרובות מתעלמים ממנו. זה יכול לגרום לשגיאות משמעותיות בעלות. חישוב דרך ה-API הארגוני מדויק הרבה יותר משיטת הטבלה עבור מידות חבילה לא סטנדרטיות. ה-API מאפשר יצירת הזמנות עם מזומן במשלוח; חלה עמלה.

למה שילוב Belpochta קשה יותר ממה שזה נראה?

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

שיטת טבלה לעומת API: השוואה

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

אנו מציעים אינטגרציה מקיפה במפתח פתוח:

• ביקורת של העגלה הנוכחית ושיטות המשלוח
• הטמעת ווידג'ט לבחירת סניף Belpochta
• מחשבון עלות משלוח (טבלאות או API)
• יצירת הזמנות דרך API ארגוני
• עמוד מעקב עבור הלקוח
• תיעוד והדרכת מנהלים
• תמיכה לאחר ההשקה

איך אנחנו עושים את זה

חישוב באמצעות טבלאות תעריפים

התעריפים של Belpochta בנויים לפי קטגוריות משקל ואזורי משלוח (בתוך מינסק, בתוך בלארוס, בינלאומי). דוגמאות לתעריפים לחבילות מקומיות זמינות לפי בקשה. יישום המחשבון קורא מטבלה הניתנת להגדרה.

class BelpochtaTariffCalculator {
    private array $domesticParcels = [
        0.1 => 3.20,
        0.25 => 3.70,
        0.5 => 4.30,
        1.0 => 5.10,
        2.0 => 6.40,
        3.0 => 7.70,
        5.0 => 9.60,
        10.0 => 13.50,
        15.0 => 17.20,
        20.0 => 20.80,
        31.5 => 25.60,
    ];

    private float $courierSurcharge = 3.50;

    public function calculateDeclaredValueFee(float $value): float {
        return max(0.50, $value * 0.005);
    }

    public function calculate(
        float $weightKg,
        bool $toDoor = false,
        float $declaredValue = 0,
        string $type = 'parcel'
    ): array {
        $basePrice = null;
        foreach ($this->domesticParcels as $maxWeight => $price) {
            if ($weightKg <= $maxWeight) {
                $basePrice = $price;
                break;
            }
        }

        if ($basePrice === null) {
            throw new \InvalidArgumentException('Вес превышает максимально допустимый (31.5 кг)');
        }

        $total = $basePrice;
        if ($toDoor) $total += $this->courierSurcharge;
        if ($declaredValue > 0) $total += $this->calculateDeclaredValueFee($declaredValue);

        return [
            'base' => $basePrice,
            'courier_fee' => $toDoor ? $this->courierSurcharge : 0,
            'declared_fee' => $declaredValue > 0 ? $this->calculateDeclaredValueFee($declaredValue) : 0,
            'total' => round($total, 2),
            'currency' => 'BYN',
            'min_days' => 3,
            'max_days' => 14,
        ];
    }
}

אינטגרציה דרך API ארגוני

ללקוחות עם חוזה, API זמין דרך החשבון האישי. האימות משתמש במפתח API בכותרת:

class BelpochtaApiClient {
    private string $baseUrl = 'https://api.belpochta.by/v1';

    public function calculateShipping(array $params): array
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.belpochta.api_key'),
            'Content-Type' => 'application/json',
        ])->post($this->baseUrl . '/calc', [
            'from_index' => $params['from_index'],
            'to_index' => $params['to_index'],
            'weight' => (int)($params['weight_kg'] * 1000),
            'length' => $params['length'] ?? 0,
            'width' => $params['width'] ?? 0,
            'height' => $params['height'] ?? 0,
            'service_type'=> $params['service_type'] ?? 'PARCEL',
        ]);

        return $response->json();
    }

    public function createOrder(array $orderData): array
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.belpochta.api_key'),
        ])->post($this->baseUrl . '/orders', $orderData);

        if ($response->failed()) {
            throw new BelpochtaException('Order creation failed: ' . $response->body());
        }

        return $response->json();
    }
}

מיקודים וכתובות

המיקודים הבלארוסיים הם בני 6 ספרות, מתחילים ב-2. המיקודים של מינסק נעים בהתאם. אימות וחיפוש עיר:

public function validateBelarusPostalCode(string $code): bool
{
    return (bool)preg_match('/^2[0-9]{5}$/', $code);
}

public function getCityByIndex(string $postalCode): ?string
{
    return Cache::remember("belpochta_city_{$postalCode}", now()->addWeek(), function () use ($postalCode) {
        $response = Http::get('https://api.belpochta.by/v1/address/by-index', [
            'index' => $postalCode,
        ]);
        return $response->json('city');
    });
}

EMS ומעקב

למשלוחים דחופים — EMS Belpochta. מעקב דרך מעקב ציבורי או API:

public function trackParcel(string $trackNumber): array
{
    $response = Http::withHeaders([
        'Authorization' => 'Bearer ' . config('services.belpochta.api_key'),
    ])->get($this->baseUrl . '/tracking/' . $trackNumber);

    if ($response->notFound()) {
        return ['error' => 'Отправление не найдено'];
    }

    return collect($response->json('events') ?? [])
        ->map(fn($e) => [
            'date' => $e['date'],
            'time' => $e['time'],
            'status' => $e['operation'],
            'place' => $e['place'],
            'index' => $e['index'],
        ])
        ->toArray();
}

המרת מטבע

אם החנות פועלת במטבע אחר, אנו משתמשים בשער החליפין של הבנק הלאומי של בלארוס (API חינמי):

public function convertToDisplayCurrency(float $byn, string $targetCurrency = 'USD'): float
{
    $rate = Cache::remember("exchange_rate_BYN_{$targetCurrency}", now()->addHour(), function () use ($targetCurrency) {
        $response = Http::get('https://api.nbrb.by/exrates/rates/' . $targetCurrency, [
            'periodicity' => 0,
        ]);
        return $response->json('Cur_OfficialRate');
    });

    return round($byn * $rate, 2);
}

איך לבחור בין טבלאות ל-API?

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

התהליך שלנו

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

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

• מחשבון באמצעות טבלאות תעריפים: בין 2 ל-3 ימים.
• אינטגרציה מלאה עם API (כולל חוזה עם Belpochta): בין 5 ל-7 ימים. ההשקעה נקבעת באופן אישי לאחר ביקורת. אם אתם רוצים לחסל שגיאות חישוב, קבלו ייעוץ. נמצא את הפתרון האופטימלי עבור החנות שלכם.

טעויות אינטגרציה נפוצות

• קטגוריית משקל שגויה — הלקוח מזין משקל מסוים, אבל הקוד מעגל כלפי מעלה. השתמשו בהשוואה מדויקת class BelpochtaTariffCalculator { private array $domesticParcels = [ 0.1 => 3.20, 0.25 => 3.70, 0.5 => 4.30, 1.0 => 5.10, 2.0 => 6.40, 3.0 => 7.70, 5.0 => 9.60, 10.0 => 13.50, 15.0 => 17.20, 20.0 => 20.80, 31.5 => 25.60, ]; private float $courierSurcharge = 3.50; public function calculateDeclaredValueFee(float $value): float { return max(0.50, $value * 0.005); } public function calculate( float $weightKg, bool $toDoor = false, float $declaredValue = 0, string $type = 'parcel' ): array { $basePrice = null; foreach ($this->domesticParcels as $maxWeight => $price) { if ($weightKg <= $maxWeight) { $basePrice = $price; break; } } if ($basePrice === null) { throw new \InvalidArgumentException('Вес превышает максимально допустимый (31.5 кг)'); } $total = $basePrice; if ($toDoor) $total += $this->courierSurcharge; if ($declaredValue > 0) $total += $this->calculateDeclaredValueFee($declaredValue); return [ 'base' => $basePrice, 'courier_fee' => $toDoor ? $this->courierSurcharge : 0, 'declared_fee' => $declaredValue > 0 ? $this->calculateDeclaredValueFee($declaredValue) : 0, 'total' => round($total, 2), 'currency' => 'BYN', 'min_days' => 3, 'max_days' => 14, ]; } } .
• התעלמות ממידות — Belpochta משתמשת במשקל נפחי עבור קופסאות גדולות. שיטת הטבלה אינה מתחשבת בכך; יש לציין זאת במפורש.
• תעריפים מיושנים — יש לעדכן טבלאות בכל שינוי. אנו נרשמים להתראות על שינויים.
• חוסר במטמון שערי מטבע — שאילתה לבנק הלאומי בכל חישוב מאטה את העמוד. השתמשו במטמון עם TTL סביר.