שילוב 1C-Bitrix עם שירות המשלוחים Kazpost

שילוב 1C-Bitrix עם שירות המשלוחים של Kazpost

המצב: לקוח איבד עד 30% מההזמנות עקב משלוח לא תקין לאזורי קזחסטן

חנות מקוונת עם מחזור חודשי של 5 מיליון טנגה פנתה אלינו. שליחים פרטיים מסרו רק לאלמטי ואסטנה; למרכזים מחוזיים, רק Kazpost. המודול המובנה של Bitrix נכשל: חישוב העלות החזיר שגיאות, לא הייתה אפשרות מעקב. יצירת תעודת משלוח ידנית ארכה שעתיים ביום, ושגיאות מיקוד הובילו להחזרות. ערכנו ביקורת והחלטנו לשכתב לחלוטין את מטפל המשלוחים באמצעות REST API של Kazpost. החיסכון בעיבוד הזמנות ידני הסתכם ב-15 שעות בחודש. כתוצאה מכך, לאחר היישום, הלקוח אוטומציה 90% מההזמנות, וזמן העיבוד ירד מ-30 דקות ל-2 דקות להזמנה. בנוסף, ביטלנו שגיאות עיגול שהתרחשו עקב המרת מטבע שגויה. כעת קונים מכל עיר בקזחסטן יכולים להזמין משלוחים באינטרנט, והחנות מקבלת עלויות עדכניות תוך התחשבות במשקל ובערך המוצהר.

כיצד עובדת אינטגרציית Kazpost

Kazpost הוא המפעיל הדוארי הלאומי עם למעלה מ-3500 סניפים. ה-API זמין לשותפים לאחר חתימת חוזה. כתובת בסיס: https://api.kazpost.kz/api/v1. אימות באמצעות X-Api-Key. שיטות עיקריות:

• POST /delivery/calculate — חישוב עלות
• POST /shipment/create — יצירת משלוח
• GET /shipment/{barcode}/track — מעקב
• GET /offices — רשימת סניפים לפי מיקוד

למידע נוסף על REST API — הארכיטקטורה שעליה מבוסס השירות.

חישוב עלות

class KazposhtaHandler extends \Bitrix\Sale\Delivery\Services\Base {
    protected function calculateConcrete(\Bitrix\Sale\Shipment $shipment): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $toIndex = $this->getPostIndex($shipment);
        if (!$toIndex) {
            $result->addError(new \Bitrix\Main\Error('Не указан почтовый индекс получателя'));
            return $result;
        }
        $response = $this->apiPost('/delivery/calculate', [
            'from_index' => $this->getOption('SENDER_INDEX'),
            'to_index' => $toIndex,
            'weight' => max((int)$shipment->getWeight(), 100),
            'declared_value' => round($shipment->getOrder()->getPrice()),
            'mail_type' => 'PARCEL',
            'mail_class' => 'ORDINARY',
        ]);
        if (!empty($response['total_rate'])) {
            $result->setDeliveryPrice((float)$response['total_rate']);
            $min = $response['delivery_days_min'] ?? 3;
            $max = $response['delivery_days_max'] ?? 14;
            $result->setPeriodDescription("{$min}–{$max} дней");
        }
        return $result;
    }
    private function getPostIndex(\Bitrix\Sale\Shipment $shipment): ?string {
        $props = $shipment->getOrder()->getPropertyCollection();
        $index = $props->getItemByOrderPropertyCode('ZIP')?->getValue();
        return preg_match('/^\d{6}$/', (string)$index) ? $index : null;
    }
}

המיקוד הוא שדה חובה. בטופס ההזמנה, אנו הופכים אותו לשדה חובה ומאמתים את הפורמט (6 ספרות).

כיצד להגדיר את מטפל המשלוחים

1. התקן את מודול המשלוחים של Kazpost או צור מחלקה משלך המרחיבה את class KazposhtaHandler extends \Bitrix\Sale\Delivery\Services\Base { protected function calculateConcrete( \Bitrix\Sale\Shipment $shipment ): \Bitrix\Sale\Delivery\CalculationResult { $result = new \Bitrix\Sale\Delivery\CalculationResult(); $toIndex = $this->getPostIndex($shipment); if (!$toIndex) { $result->addError(new \Bitrix\Main\Error('Не указан почтовый индекс получателя')); return $result; } $response = $this->apiPost('/delivery/calculate', [ 'from_index' => $this->getOption('SENDER_INDEX'), 'to_index' => $toIndex, 'weight' => max((int)$shipment->getWeight(), 100), 'declared_value' => round($shipment->getOrder()->getPrice()), 'mail_type' => 'PARCEL', 'mail_class' => 'ORDINARY', ]); if (!empty($response['total_rate'])) { $result->setDeliveryPrice((float)$response['total_rate']); $min = $response['delivery_days_min'] ?? 3; $max = $response['delivery_days_max'] ?? 14; $result->setPeriodDescription("{$min}–{$max} дней"); } return $result; } private function getPostIndex(\Bitrix\Sale\Shipment $shipment): ?string { $props = $shipment->getOrder()->getPropertyCollection(); $index = $props->getItemByOrderPropertyCode('ZIP')?->getValue(); return preg_match('/^\d{6}$/', (string)$index) ? $index : null; } } .
2. רשום את המטפל בלוח הניהול של Bitrix: הגדרות → שירותי משלוח → הוסף.
3. הוסף מאפייני הזמנה: \Bitrix\Sale\Delivery\Services\Base (מיקוד), ZIP, ADDRESS, FIO. למעקב — מאפיין מותאם אישית PHONE.
4. יישם את השיטות UF_KAZPOST_BARCODE ו-calculateConcrete כפי שמוצג לעיל.
5. הגדר סוכן לבדיקת סטטוסים תקופתית.

יצירת משלוח

public function createShipment(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();
    $response = $this->apiPost('/shipment/create', [
        'sender' => [
            'index' => $this->getOption('SENDER_INDEX'),
            'address' => $this->getOption('SENDER_ADDRESS'),
            'name' => $this->getOption('SENDER_NAME'),
            'phone' => $this->getOption('SENDER_PHONE'),
        ],
        'recipient' => [
            'index' => $props->getItemByOrderPropertyCode('ZIP')?->getValue(),
            'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
            'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        ],
        'parcel' => [
            'weight' => max((int)$shipment->getWeight(), 100),
            'declared_value' => round($order->getPrice()),
            'mail_type' => 'PARCEL',
            'description' => 'Товар',
        ],
        'payment_type' => 'PREPAID',
    ]);
    return $response['barcode'] ?? '';
}

אנו שומרים את הברקוד של המשלוח ב-createShipment.

מדוע הסוכן חיוני למעקב

ה-API של Kazpost אינו שולח webhooks — יש לבדוק סטטוסים. אנו יוצרים סוכן Bitrix הפועל כל 6 שעות. הוא בודק ברקודים של הזמנות בסטטוס "P" (שולם) וכאשר הסטטוס הוא "DELIVERED", הוא מעביר את ההזמנה ל-"F" (נמסר). חשוב להגדיר timeout לבקשות API (אנו ממליצים על 10–15 שניות) ולתעד שגיאות כך שהסוכן לא ייתקע אם Kazpost נכשל. מנגנון ניסיון חוזר לשגיאות 500–503 עוזר למנוע החמצת סטטוסים.

function checkKazposhtaStatus(): string {
    $orders = \Bitrix\Sale\Order::getList([
        'filter' => ['=PROPERTY_VAL.UF_KAZPOST_BARCODE' => true, '=STATUS_ID' => 'P'],
        'select' => ['ID']
    ]);
    foreach ($orders as $order) {
        $barcode = $order->getPropertyCollection()->getItemByOrderPropertyCode('UF_KAZPOST_BARCODE')->getValue();
        $track = new KazposhtaHandler()->track($barcode);
        if ($track['status'] === 'DELIVERED') {
            $order->setField('STATUS_ID', 'F');
            $order->save();
        }
    }
    return 'checkKazposhtaStatus();';
}

כאשר ה-API מחזיר שגיאה (לדוגמה, 400 עם גוף public function createShipment(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $response = $this->apiPost('/shipment/create', [ 'sender' => [ 'index' => $this->getOption('SENDER_INDEX'), 'address' => $this->getOption('SENDER_ADDRESS'), 'name' => $this->getOption('SENDER_NAME'), 'phone' => $this->getOption('SENDER_PHONE'), ], 'recipient' => [ 'index' => $props->getItemByOrderPropertyCode('ZIP')?->getValue(), 'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), 'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), ], 'parcel' => [ 'weight' => max((int)$shipment->getWeight(), 100), 'declared_value' => round($order->getPrice()), 'mail_type' => 'PARCEL', 'description' => 'Товар', ], 'payment_type' => 'PREPAID', ]); return $response['barcode'] ?? ''; } ), המטפל מציג את ההודעה: "המיקוד של הנמען שגוי." כל הבקשות מתועדות ב-UF_KAZPOST_BARCODE לצורך ניפוי שגיאות.

מלכודות אינטגרציה אופייניות

• פורמט מיקוד לא חוקי — חייב להיות 6 ספרות. אמת בצד הלקוח באמצעות מסכת קלט ובשרת באמצעות function checkKazposhtaStatus(): string { $orders = \Bitrix\Sale\Order::getList([ 'filter' => ['=PROPERTY_VAL.UF_KAZPOST_BARCODE' => true, '=STATUS_ID' => 'P'], 'select' => ['ID'] ]); foreach ($orders as $order) { $barcode = $order->getPropertyCollection()->getItemByOrderPropertyCode('UF_KAZPOST_BARCODE')->getValue(); $track = new KazposhtaHandler()->track($barcode); if ($track['status'] === 'DELIVERED') { $order->setField('STATUS_ID', 'F'); $order->save(); } } return 'checkKazposhtaStatus();'; } . בעת שגיאה, הצג "אנא בדוק את המיקוד של הנמען."
• מאפייני הזמנה חובה חסרים ({"error": "Invalid index"}, /bitrix/logs/kazpost.log, preg_match('/^\d{6}$/'), ZIP) — מנע נתונים ריקים עם שדות חובה בטופס ההזמנה. לפני ביצוע בקשת API, בדוק עם ADDRESS ו-FIO.
• סוכן לא מוגדר למעקב — סטטוסים לא יתעדכנו. ודא שהסוכן רשום בלוח הניהול ופועל לפי לוח זמנים (cron). בדוק יומנים ב-PHONE אם חסרים עדכונים.
• מפתח API שגוי — מחזיר 401. ודא שהמפתח נמצא במשתני סביבה ותאריך התפוגה שלו עם שותף Kazpost שלך (מפתחות דורשים חידוש חוזה תקופתי).

מאפייני משלוח Kazpost

• משלוח עד הבית זמין רק בערים גדולות (אלמטי, אסטנה, שימקנט); במקומות אחרים, המשלוח הוא לסניף הדואר.
• EMS מהיר ואמין יותר למשלוחים דחופים לערים גדולות.
• ה-API של Kazpost תומך במשלוח בתשלום בעת קבלה (COD), עם עמלה של כ-2% מהסכום.
• התעריפים מחושבים בטנגה — בדוק את הגדרות המטבע של החנות שלך.

ציר זמן ושלבים

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

• פיתוח מחלקת מטפל המשלוחים (בהתבסס על isset())
• הגדרת מאפייני הזמנה: מיקוד, כתובת, ברקוד
• יצירת סוכן המעקב
• אינטגרציה עם פיסקאליזציה (54-FZ) — נדון בנפרד
• בדיקות בסביבות בדיקה וייצור
• מסירת תיעוד וגישה

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

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