שילוב Europochta עם 1C-Bitrix: הגדרה מלאה

אינטגרציה של Europochta עם 1C-Bitrix: הגדרה מלאה

בעת אינטגרציה של שירות המשלוחים Europochta עם 1C-Bitrix, עולות לעיתים קרובות בעיות: חישוב משקל לא סטנדרטי של חבילות (סף מינימלי של 0.05 ק"ג), בלבול עם מזומן במשלוח, וחוסר במעקב אוטומטי. אנו פותרים משימות אלו כבר שנים רבות וביצענו למעלה מ-30 אינטגרציות עבור חנויות מקוונות בלארוסיות. הפתרון שלנו כולל הכל, מהגדרת API ועד למפת נקודות איסוף באתר. Europochta היא מפעילת דואר פרטית עם רשת רחבה של נקודות איסוף. ה-API מסופק לשותפים לאחר רישום.

באילו בעיות נתקלות חנויות?

הקשיים הטכניים העיקריים: חישוב משקל לא סטנדרטי (דורש סף מינימלי של 0.05 ק"ג), העברה שגויה של קוד מזומן במשלוח, וחוסר בסנכרון סטטוסים. בנוסף, ביצועים נמוכים עקב בקשות API תכופות במהלך חישוב משלוח. רכיבי משלוח סטנדרטיים ב-Bitrix אינם מותאמים ל-Europochta — בקשות תכופות מאטות את העמוד. הרכיב שלנו משתמש במטמון מתויג ומפחית את עומס השרת פי 2-3. חיסכון ממוצע בזמן עיבוד הזמנה אחת הוא עד 60%.

למה לשלב את Europochta דרך הרכיב שלנו?

אנו משתמשים במטמון מתויג לתוצאות חישוב, מה שמפחית את עומס השרת פי 2-3. בניגוד לפתרונות סטנדרטיים, הרכיב שלנו תומך בקביעה אוטומטית של cod בהתבסס על אמצעי התשלום, מה שמונע שגיאות ידניות. אנו מעבירים את cod כערך מספרי עם שתי ספרות אחרי הנקודה העשרונית, כפי שנקבע בתיעוד הרשמי של API של Europochta.

איך להגדיר חישוב עלות ללא שגיאות?

class EuropachtaHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult
    {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $order = $shipment->getOrder();
        $response = $this->apiPost('/rate/calculate', [
            'from_city' => $this->getOption('SENDER_CITY'),
            'to_city' => $this->getOrderCity($shipment),
            'weight' => max($shipment->getWeight() / 1000, 0.05),
            'declared' => round($order->getPrice()),
            'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'),
        ]);
        if (!empty($response['price'])) {
            $result->setDeliveryPrice((float)$response['price']);
            $days = $response['days'] ?? '2–5';
            $result->setPeriodDescription("{$days} дней");
        }
        return $result;
    }
}

יצירת הזמנה עם מזומן במשלוח

public function createOrder(\Bitrix\Sale\Shipment $shipment): string {
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();
    $payload = [
        'external_id' => 'bitrix_' . $order->getId(),
        'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'),
        'weight' => max($shipment->getWeight() / 1000, 0.05),
        'declared' => round($order->getPrice()),
        'cod' => $this->getCodAmount($order),
        'sender' => [
            'name' => $this->getOption('SENDER_NAME'),
            'phone' => $this->getOption('SENDER_PHONE'),
            'address' => $this->getOption('SENDER_ADDRESS'),
        ],
        'recipient' => [
            'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'city' => $this->getOrderCity($shipment),
            'pvz_id' => $props->getItemByOrderPropertyCode('EUROPOCHTA_PVZ')?->getValue(),
        ],
        'items' => $this->buildItems($shipment),
    ];
    $response = $this->apiPost('/order/create', $payload);
    return (string)($response['order_id'] ?? '');
}

השדה class EuropachtaHandler extends \Bitrix\Sale\Delivery\Services\Base { protected function calculateConcrete( \Bitrix\Sale\Shipment $shipment ): \Bitrix\Sale\Delivery\CalculationResult { $result = new \Bitrix\Sale\Delivery\CalculationResult(); $order = $shipment->getOrder(); $response = $this->apiPost('/rate/calculate', [ 'from_city' => $this->getOption('SENDER_CITY'), 'to_city' => $this->getOrderCity($shipment), 'weight' => max($shipment->getWeight() / 1000, 0.05), 'declared' => round($order->getPrice()), 'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'), ]); if (!empty($response['price'])) { $result->setDeliveryPrice((float)$response['price']); $days = $response['days'] ?? '2–5'; $result->setPeriodDescription("{$days} дней"); } return $result; } } הוא סכום המזומן במשלוח. אם ההזמנה שולמה מראש, אנו מעבירים public function createOrder(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $payload = [ 'external_id' => 'bitrix_' . $order->getId(), 'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'), 'weight' => max($shipment->getWeight() / 1000, 0.05), 'declared' => round($order->getPrice()), 'cod' => $this->getCodAmount($order), 'sender' => [ 'name' => $this->getOption('SENDER_NAME'), 'phone' => $this->getOption('SENDER_PHONE'), 'address' => $this->getOption('SENDER_ADDRESS'), ], 'recipient' => [ 'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), 'city' => $this->getOrderCity($shipment), 'pvz_id' => $props->getItemByOrderPropertyCode('EUROPOCHTA_PVZ')?->getValue(), ], 'items' => $this->buildItems($shipment), ]; $response = $this->apiPost('/order/create', $payload); return (string)($response['order_id'] ?? ''); } . אם יש מזומן במשלוח, אנו מעבירים את סכום ההזמנה המלא. אנו קובעים אוטומטית את ה-cod לפי אמצעי התשלום, מה שמונע שגיאות ידניות.

טיפול בשגיאות API ואימות נתונים

טיפול חזק בשגיאות הוא קריטי במהלך אינטגרציה. ה-API של Europochta יכול להחזיר קודי שגיאה: cod (אישורים לא חוקיים), 0 (פורמט בקשה לא חוקי), 401 (עיר לא נמצאה בספרייה), 400 (שגיאה בצד השרת). כל מקרה דורש אסטרטגיה שונה: עבור 404, בדוק מפתחות API בהגדרות; עבור 500, אמת נתוני כתובת ומשקל; עבור 401, הצע למשתמש לבחור עיר חלופית או אזור משלוח; עבור 400, נסה שוב את הבקשה לאחר 10-30 שניות עם השהיה אקספוננציאלית. יש לתעד את כל השגיאות עם מידע מלא על פרמטרי הבקשה לצורך ניפוי באגים. אנו משתמשים במערכת הרישום המובנית של Bitrix ושולחים שגיאות קריטיות כהתראות למנהלים.

למה חשוב ליישם מזומן במשלוח בצורה נכונה?

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

איך אנו מאיצים את שירות המשלוחים?

לצורך מטמון רשימת נקודות האיסוף, אנו משתמשים ב-404 עם TTL של 12 שעות. סוכן בודק סטטוסי הזמנות כל 3-4 שעות, מכיוון ש-Europochta אינה מספקת webhooks. הרכיב שלנו מותאם כך שעמוד התשלום לא יאט גם תחת עומסים גבוהים.

בדיקת האינטגרציה ופתרון בעיות

לפני המעבר לייצור, בדוק את כל התרחישים: חישוב עלות משלוח למשקלים שונים (כולל מקרה הגבול של 0.05 ק"ג), יצירת הזמנות עם אמצעי תשלום שונים, סנכרון סטטוסים עבור חבילות שנמסרו והוחזרו. מומלץ לעבוד תחילה עם סביבת ה-sandbox של Europochta (אם זמינה), ולאחר מכן לעבור לייצור עם תעבורה נמוכה. בדוק באופן קבוע את יומני הסוכן בלוח הניהול של Bitrix כדי לזהות תקלות API או נתוני כתובת שגויים. שגיאות נפוצות: פורמט טלפון שגוי (השתמש בפורמט בינלאומי +375...), עיר שאינה בספריית Europochta, חריגה ממגבלת קצב ה-API (בדרך כלל 100 בקשות לדקה — הוסף הגבלת קצב ברמת הרכיב).

אבטחה ושיטות עבודה מומלצות

מפתחות API ואישורים עבור Europochta לעולם לא צריכים להישמר בקוד — השתמש במשתני סביבה או באחסון פרמטרים מאובטח ב-Bitrix (קובץ delivered או אפשרות returned). כל הבקשות ל-API של Europochta חייבות לעבור דרך HTTPS עם אימות תעודת SSL. בעת רישום, לעולם אל תשמור את מפתח ה-API המלא או נתוני משתמש רגישים (נתוני דרכון, כתובות מלאות) ביומנים — רשום רק מזהי הזמנות וסטטוסים. הגבל גישה ללוח הניהול של הרכיב למנהלים מהימנים באמצעות הרשאות משתמש של Bitrix. מומלץ לסובב מפתחות API באופן קבוע (כל 90 יום) ולבדוק יומני גישה לפעילות חריגה.

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

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

לוח זמנים

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