שילוב של 1C-Bitrix עם שירות המשלוחים UkrPoshta (אוקראינה)

Integration של 1C-Bitrix עם שירות המשלוחים UkrPoshta (אוקראינה)

לעתים קרובות אנו נתקלים בחנויות שצריכות לספק סחורה ליישובים שבהם אין סניפים של Nova Poshta. UkrPoshta הוא המפעיל הממשלתי היחיד המכסה את כל אוקראינה, כולל כפרים ועיירות קטנות. לאחר הארגון מחדש, ה-API הפך למודרני: REST עם אימות JWT. עם זאת, מפתחים נתקלים לעתים קרובות ביצירה הרציפה והחובה של אובייקטים (כתובת → לקוח → משלוח) ובניתוח מחרוזות כתובת. בואו נעבור על היישום ב-Bitrix. כל שלב דורש טיפול זהיר, אחרת האינטגרציה עלולה להימשך שבועות. צברנו ניסיון עם למעלה מ-10 פרויקטים שבהם UkrPoshta הייתה חברת השילוח העיקרית, ואנו מוכנים לחלוק את הפרטים.

כיצד לאמת ב-API של UkrPoshta?

האימות מתבצע באמצעות טוקן Bearer בכותרת Authorization: Bearer <token>. כדי לקבל את הטוקן, שלחו בקשת POST אל /api/2.0/client-token, תוך העברת המפתח מחשבונכם האישי. כתובת ה-API הבסיסית: https://www.ukrposhta.ua/ecom/0.0.1. לטוקן יש תקופת תוקף מוגבלת, ולכן יש לרענן אותו מעת לעת. ב-Bitrix, נוח לאחסן אותו בהגדרות המודול ולעדכן באמצעות סוכן (agent). פסק הזמן של הטוקן הוא 30 דקות, ולכן הסוכן צריך לפעול לפחות כל 25 דקות. בדקו שאין הגבלות על הפעלת סוכנים בהגדרות האירוח שלכם.

יצירת משלוח

UkrPoshta דורשת יצירה רציפה של אובייקטים: כתובת → לקוח → משלוח. להלן דוגמה למטפל ב-PHP עבור רכיב bitrix:sale.order.ajax:

class UkrPoshtaHandler {
    public function createShipment(\Bitrix\Sale\Shipment $shipment): string {
        $order = $shipment->getOrder();
        $props = $order->getPropertyCollection();

        // Шаг 1: создать адрес получателя
        $addr = $this->apiPost('/addresses', [
            'postcode' => $props->getItemByOrderPropertyCode('ZIP')?->getValue(),
            'city' => $props->getItemByOrderPropertyCode('CITY')?->getValue(),
            'street' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
            'houseNumber' => '1',
        ]);
        $addressUuid = $addr['uuid'];

        // Шаг 2: создать получателя
        $client = $this->apiPost('/clients', [
            'firstName' => $this->parseFirstName($props),
            'lastName' => $this->parseLastName($props),
            'phoneNumber' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'type' => 'INDIVIDUAL',
            'addressId' => $addressUuid,
        ]);
        $clientUuid = $client['uuid'];

        // Шаг 3: создать отправление
        $response = $this->apiPost('/shipments', [
            'sender' => ['uuid' => $this->getOption('SENDER_UUID')],
            'recipient' => ['uuid' => $clientUuid],
            'deliveryType' => 'W2D',
            'weight' => max((int)$shipment->getWeight(), 20),
            'length' => (int)$this->getOption('DEFAULT_LENGTH', 20),
            'width' => (int)$this->getOption('DEFAULT_WIDTH', 20),
            'height' => (int)$this->getOption('DEFAULT_HEIGHT', 5),
            'declaredPrice' => (int)round($order->getPrice()),
            'description' => 'Товар',
            'paidByRecipient' => false,
        ]);

        return $response['uuid'] ?? '';
    }
}

class UkrPoshtaHandler { public function createShipment(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); // Шаг 1: создать адрес получателя $addr = $this->apiPost('/addresses', [ 'postcode' => $props->getItemByOrderPropertyCode('ZIP')?->getValue(), 'city' => $props->getItemByOrderPropertyCode('CITY')?->getValue(), 'street' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), 'houseNumber' => '1', ]); $addressUuid = $addr['uuid']; // Шаг 2: создать получателя $client = $this->apiPost('/clients', [ 'firstName' => $this->parseFirstName($props), 'lastName' => $this->parseLastName($props), 'phoneNumber' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), 'type' => 'INDIVIDUAL', 'addressId' => $addressUuid, ]); $clientUuid = $client['uuid']; // Шаг 3: создать отправление $response = $this->apiPost('/shipments', [ 'sender' => ['uuid' => $this->getOption('SENDER_UUID')], 'recipient' => ['uuid' => $clientUuid], 'deliveryType' => 'W2D', 'weight' => max((int)$shipment->getWeight(), 20), 'length' => (int)$this->getOption('DEFAULT_LENGTH', 20), 'width' => (int)$this->getOption('DEFAULT_WIDTH', 20), 'height' => (int)$this->getOption('DEFAULT_HEIGHT', 5), 'declaredPrice' => (int)round($order->getPrice()), 'description' => 'Товар', 'paidByRecipient' => false, ]); return $response['uuid'] ?? ''; } } — החנות משלמת עבור המשלוח. אם paidByRecipient: false, הנמען משלם בעת קבלת החבילה. שימו לב: ה-API של UkrPoshta מחזיר שגיאה אם שדה true חסר. בפרויקט אמיתי, יש לקחת אותו ממאפיין הזמנה, אחרת הניתוח עלול להיכשל.

סוגי משלוחים

בחירת הסוג משפיעה על העלות וזמני האספקה. מניסיון, W2D הוא הנפוץ ביותר בחנויות מקוונות — לקוחות מעדיפים משלוח עד הבית.

כיצד ליישם מעקב אחר משלוחים?

לאחר יצירת משלוח, שמרו את ה-UUID שלו. לאחר מכן הגדירו סוכן ב-Bitrix שקורא ל-D2D כל 3-4 שעות. ניתן לתעד את הסטטוסים שהתקבלו או להציג אותם בלוח הניהול של ההזמנה. הנה יישום פשוט:

// Агент вызывается каждые 3 часа
public function trackShipments(): string
{
    $shipments = \Bitrix\Sale\Shipment::getList([
        'filter' => ['!UKRPOSHTA_UUID' => null, '!=STATUS' => 'DELIVERED']
    ]);
    foreach ($shipments as $shipment) {
        $statuses = $this->apiGet("/shipments/{$shipment['UKRPOSHTA_UUID']}/statuses");
        // Обновляем статус в заказе
        if (!empty($statuses)) {
            \Bitrix\Sale\Order::update($shipment['ORDER_ID'], [
                'UKRPOSHTA_STATUS' => end($statuses)['code']
            ]);
        }
    }
    return 'trackShipments();';
}

גישה זו מאפשרת לראות את המיקום הנוכחי של החבילה ללא עדכונים ידניים.

קבלת תווית

// Печать марки — кнопка в административной части заказа Битрикс
public function getLabel(string $shipmentUuid): string
{
    $response = $this->apiGet("/shipments/{$shipmentUuid}/label");
    return base64_decode($response['pdf_base64'] ?? '');
}

המתודה מחזירה קובץ PDF שניתן לשמור או להציג למשתמש. באזור הניהול, נוח להוסיף כפתור "הדפסת תווית" ישירות בכרטיס המשלוח.

מה כדאי לדעת על משלוחים בינלאומיים?

למסלולים UA→BY, UA→PL ואחרים: הצהרת מכס CN22/CN23, מגבלת משקל עד 30 ק"ג, קוד HS חובה לסחורות. אנו ממליצים להוסיף מאפיין משתמש GET /shipments/{uuid}/statuses למוצרים בבלוק המידע ולהעביר אותו אוטומטית להצהרה. ללא זה, UkrPoshta תדחה את הבקשה. כמו כן, שימו לב: עבור משלוחים בינלאומיים, יש לציין את הקוד // Агент вызывается каждые 3 часа public function trackShipments(): string { $shipments = \Bitrix\Sale\Shipment::getList([ 'filter' => ['!UKRPOSHTA_UUID' => null, '!=STATUS' => 'DELIVERED'] ]); foreach ($shipments as $shipment) { $statuses = $this->apiGet("/shipments/{$shipment['UKRPOSHTA_UUID']}/statuses"); // Обновляем статус в заказе if (!empty($statuses)) { \Bitrix\Sale\Order::update($shipment['ORDER_ID'], [ 'UKRPOSHTA_STATUS' => end($statuses)['code'] ]); } } return 'trackShipments();'; } בכתובת הנמען ובמדינת השולח.

מאפייני שדה הכתובת

UkrPoshta מצפה לשדות נפרדים: רחוב, מספר בית, דירה. ב-Bitrix, הכתובת מאוחסנת בדרך כלל כמחרוזת אחת. יש להוסיף שדות נפרדים לטופס ההזמנה או ליישם ניתוח מחרוזת כתובת. הגישה השנייה נותנת דיוק של כ-85%, בעוד הראשונה אמינה יותר. בפרויקטים שלנו, אנו משתמשים במאפייני הזמנה מותאמים אישית "רחוב", "בית", "דירה" — זה מבטל שגיאות זיהוי. לדוגמה, בעת ניתוח, מספר הבית מתבלבל לעתים קרובות עם הדירה, במיוחד בכתובות כמו "רחוב גגארין 10, דירה 5".

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

• הגדרת מודול המשלוחים וקבלת טוקנים
• יצירת מאפייני הזמנה מותאמים אישית לשדות כתובת נפרדים
• יישום מטפל המשלוחים עם קריאות ל-API של UkrPoshta
• הפקה והדפסה של שטר מטען בפורמט PDF
• הגדרת מעקב רקע (סוכן עם מרווח של 3-4 שעות)
• שילוב הצהרת מכס לחבילות בינלאומיות
• הכנת תיעוד ומסירת גישה

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

לוחות זמנים

לוחות הזמנים ניתנים בהנחה שכל הגישות של הלקוח מוכנות. בממוצע, הפרויקט אורך שבוע. אנו עובדים עם Bitrix ויישמנו למעלה מ-10 אינטגרציות עם שירותי דואר אוקראיניים. פנו אלינו — נעזור לכם להגדיר משלוחים דרך UkrPoshta בחנות שלכם.