שילוב 1C-Bitrix עם שירות המשלוחים Kuranty (בלארוס)

שילוב 1C-Bitrix עם שירות המשלוחים Kuranty (בלארוס)

שילוב שירות המשלוחים Kuranty עם 1C-Bitrix הוא משימה העומדת בפני חנויות מקוונות בלארוסיות כאשר מודולים סטנדרטיים אינם מתאימים. ה-API של Kuranty דורש הרשאת JWT וטיפול נכון בסטטוסים. הצוות שלנו יישם מספר שילובים כאלה—ממחשבון פשוט ועד מחזור מלא עם נקודות איסוף ומעקב. הנה איך לעשות זאת נכון ומה חשוב לקחת בחשבון.

למה לבחור ב-Kuranty למשלוחים בבלארוס?

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

איך עובד ה-API של Kuranty?

ה-API הוא REST עם הרשאת JWT. כתובת בסיס: https://api.kuranty.by/v2. אסימון מתקבל דרך POST /auth/token עם שם משתמש וסיסמה, ותוקפו 24 שעות. אנו שומרים את האסימון במטמון למשך 23 שעות כדי להימנע מפניות ל-API בכל חישוב.

שיטות עיקריות:

• POST /delivery/cost — חישוב עלות
• POST /delivery/create — יצירת משלוח
• GET /delivery/{uuid}/status — סטטוס משלוח
• GET /pickup-points — רשימת נקודות איסוף

חישוב עלות

אנו מיישמים מחלקת handler המרחיבה את \Bitrix\Sale\Delivery\Services\Base. בשיטת calculateConcrete, אנו מקבלים את עיר הנמען ממאפייני ההזמנה, שולחים בקשה עם משקל וסכום ההזמנה. התשובה כוללת עלות וזמן משלוח.

class KurantyHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    private function getAuthToken(): string
    {
        $cache = \Bitrix\Main\Data\Cache::createInstance();
        if ($cache->initCache(3600 * 23, 'kuranty_token', '/kuranty/')) {
            return $cache->getVars();
        }

        $response = $this->apiPost('/auth/token', [
            'login' => $this->getOption('LOGIN'),
            'password' => $this->getOption('PASSWORD'),
        ]);

        $token = $response['token'] ?? '';
        $cache->startDataCache();
        $cache->endDataCache($token);
        return $token;
    }

    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $order = $shipment->getOrder();
        $props = $order->getPropertyCollection();
        $city = $this->getOrderCity($props);

        if (!$city) {
            $result->addError(new \Bitrix\Main\Error('Город доставки не определён'));
            return $result;
        }

        $response = $this->apiPost('/delivery/cost', [
            'from_city' => $this->getOption('SENDER_CITY'),
            'to_city' => $city,
            'weight' => max($shipment->getWeight() / 1000, 0.1),
            'sum' => round($order->getPrice()),
            'type' => $this->getOption('DELIVERY_TYPE', 'pickup'), // pickup или courier
        ], $this->getAuthToken());

        if (!empty($response['cost'])) {
            $result->setDeliveryPrice((float)$response['cost']);
            $days = $response['days_min'] . '–' . $response['days_max'];
            $result->setPeriodDescription("{$days} дней");
        }

        return $result;
    }
}

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

יצירת משלוח

לאחר ביצוע ההזמנה, יש ליצור משלוח במערכת Kuranty. שיטת class KurantyHandler extends \Bitrix\Sale\Delivery\Services\Base { private function getAuthToken(): string { $cache = \Bitrix\Main\Data\Cache::createInstance(); if ($cache->initCache(3600 * 23, 'kuranty_token', '/kuranty/')) { return $cache->getVars(); } $response = $this->apiPost('/auth/token', [ 'login' => $this->getOption('LOGIN'), 'password' => $this->getOption('PASSWORD'), ]); $token = $response['token'] ?? ''; $cache->startDataCache(); $cache->endDataCache($token); return $token; } protected function calculateConcrete( \Bitrix\Sale\Shipment $shipment ): \Bitrix\Sale\Delivery\CalculationResult { $result = new \Bitrix\Sale\Delivery\CalculationResult(); $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $city = $this->getOrderCity($props); if (!$city) { $result->addError(new \Bitrix\Main\Error('Город доставки не определён')); return $result; } $response = $this->apiPost('/delivery/cost', [ 'from_city' => $this->getOption('SENDER_CITY'), 'to_city' => $city, 'weight' => max($shipment->getWeight() / 1000, 0.1), 'sum' => round($order->getPrice()), 'type' => $this->getOption('DELIVERY_TYPE', 'pickup'), // pickup или courier ], $this->getAuthToken()); if (!empty($response['cost'])) { $result->setDeliveryPrice((float)$response['cost']); $days = $response['days_min'] . '–' . $response['days_max']; $result->setPeriodDescription("{$days} дней"); } return $result; } } בונה את ה-payload: משקל, סכום, מזומן במשלוח, כתובת ופרטי קשר. התשובה מכילה את ה-UUID של ההזמנה ב-Kuranty, אותו אנו שומרים במאפיין הזמנה.

public function createDelivery(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();
    $payload = [
        'external_id' => 'bx_' . $order->getId(),
        'type' => $this->getOption('DELIVERY_TYPE', 'pickup'),
        'from_city' => $this->getOption('SENDER_CITY'),
        'to_city' => $this->getOrderCity($props),
        'pickup_point' => $props->getItemByOrderPropertyCode('KURANTY_POINT')?->getValue(),
        'recipient' => [
            'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        ],
        'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
        'weight' => max($shipment->getWeight() / 1000, 0.1),
        'sum' => round($order->getPrice()),
        'cod' => $order->isPaid() ? 0.0 : round($order->getPrice()),
        'comment' => 'Заказ #' . $order->getId(),
    ];
    $response = $this->apiPost('/delivery/create', $payload, $this->getAuthToken());
    return (string)($response['uuid'] ?? '');
}

נקודות איסוף באתר

כדי להציג נקודות איסוף על מפה, אנו משתמשים ב-API של createDelivery. אנו שומרים את הנתונים במטמון למשך 6 שעות—Kuranty מעדכנת את הרשימה לעתים רחוקות. התשובה כוללת קואורדינטות (lat, lon), המאפשרות לנו למקם נקודות על מפות Yandex עם סמנים מותאמים אישית.

public function getPickupPoints(?string $city = null): array
{
    $cacheKey = 'kuranty_pvz_' . md5((string)$city);
    $cache = \Bitrix\Main\Data\Cache::createInstance();
    if ($cache->initCache(3600 * 6, $cacheKey, '/kuranty/')) {
        return $cache->getVars();
    }
    $params = $city ? ['city' => $city] : [];
    $points = $this->apiGet('/pickup-points', $params, $this->getAuthToken());
    $cache->startDataCache();
    $cache->endDataCache($points ?? []);
    return $points ?? [];
}

מעקב

Kuranty אינה מספקת webhooks—יש לבדוק את סטטוס המשלוח ידנית. אנו מיישמים סוכן Bitrix הבודק סטטוס עבור כל הזמנה פעילה כל 2–3 שעות ומעדכן אותו במאפייני ההזמנה. שיטת public function createDelivery(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $payload = [ 'external_id' => 'bx_' . $order->getId(), 'type' => $this->getOption('DELIVERY_TYPE', 'pickup'), 'from_city' => $this->getOption('SENDER_CITY'), 'to_city' => $this->getOrderCity($props), 'pickup_point' => $props->getItemByOrderPropertyCode('KURANTY_POINT')?->getValue(), 'recipient' => [ 'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), ], 'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), 'weight' => max($shipment->getWeight() / 1000, 0.1), 'sum' => round($order->getPrice()), 'cod' => $order->isPaid() ? 0.0 : round($order->getPrice()), 'comment' => 'Заказ #' . $order->getId(), ]; $response = $this->apiPost('/delivery/create', $payload, $this->getAuthToken()); return (string)($response['uuid'] ?? ''); } מקבלת UUID ומחזירה מערך סטטוסים נוכחי.

public function getStatus(string $uuid): array
{
    return $this->apiGet("/delivery/{$uuid}/status", [], $this->getAuthToken()) ?? [];
}

מה כלול בשילוב

השוואת Kuranty עם שירותי משלוחים בלארוסיים אחרים

Kuranty מנצחת במהירות בערים ובמספר נקודות האיסוף אך מפסידה ל-Belpochta בעלות. עבור חנויות מקוונות עם נפח גבוה, שילוב שירותים הוא יתרון גדול יותר.

הערכות זמנים

למה להזמין אצלנו את השילוב?

הצוות שלנו מביא ניסיון של למעלה מ-5 שנים עם 1C-Bitrix ויותר מ-50 פרויקטים מוצלחים של שילוב שירותי משלוחים. אנו מספקים אחריות על הקוד ותמיכה לאחר ההשקה. כל המומחים שלנו מוסמכים על ידי הספק. תקבלו הצעת מחיר מפורטת ומפת דרכים תוך יום אחד לאחר פנייתכם אלינו.

הזמינו שילוב מפתח—צרו קשר להערכת הפרויקט שלכם.