אוטומציה של משלוחים: אינטגרציה של 1C-Bitrix ו-Nova Poshta

אוטומציית משלוחים: שילוב 1C-Bitrix עם Nova Poshta

במסחר האלקטרוני האוקראיני, Nova Poshta היא הסטנדרט: כ-80% מההזמנות עוברות דרך שירות זה. לפי Nova Poshta, עד 5% מתעודות המשלוח מכילות שגיאות — עבור 150 הזמנות ביום, מדובר ב-7-8 משלוחים שגויים. כל טעות מובילה להחזרות ולאובדן נאמנות. אינטגרציה דרך API מפחיתה נתון זה ל-0.5%. אוטומציה של יצירת תעודות משלוח, מעקב ובחירת מחסנים מבטלת הזנה ידנית ומקצרת את זמן העיבוד ב-60%.

אנחנו (הצוות שלנו) שילבנו את Bitrix עם Nova Poshta בעשרות פרויקטים במשך 5 שנים ופיתחנו אלגוריתם שמבטל תקלות. במאמר זה נעבור על איך להגדיר אינטגרציה — מהשגת מפתח API ועד מעקב מלא. תלמדו כיצד להימנע ממלכודות נפוצות ואילו הזדמנויות מודול מוכן פותח.

איך עובד Nova Poshta API

Nova Poshta מספק API אחיד בפורמט JSON: https://api.novaposhta.ua/v2.0/json/. אימות באמצעות apiKey בגוף הבקשה. פורמט הבקשה זהה לכל הפעולות:

private function apiCall(string $model, string $method, array $props): array {
    $payload = [
        'apiKey' => $this->apiKey,
        'modelName' => $model,
        'calledMethod' => $method,
        'methodProperties' => $props,
    ];

    $ch = curl_init('https://api.novaposhta.ua/v2.0/json/');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$response['success']) {
        throw new \RuntimeException('НП API: ' . implode(', ', $response['errors']));
    }

    return $response;
}

מפרט מפורט זמין ב-תיעוד Nova Poshta API.

חיפוש עיר ומחסן

Nova Poshta משתמש במזהי Ref עבור כל האובייקטים. מיפוי מיקום Bitrix למזהה Ref של עיר ב-Nova Poshta:

public function getCityRef(string $cityName): ?string
{
    $cache = \Bitrix\Main\Data\Cache::createInstance();
    $key = 'np_city_' . md5($cityName);
    if ($cache->initCache(86400, $key, '/np/')) {
        return $cache->getVars();
    }
    $response = $this->apiCall('Address', 'getCities', [
        'FindByString' => $cityName,
        'Limit' => 5,
    ]);
    $ref = $response['data'][0]['Ref'] ?? null;
    if ($ref) {
        $cache->startDataCache();
        $cache->endDataCache($ref);
    }
    return $ref;
}

הלקוח מזין מספר מחסן של Nova Poshta (לדוגמה, "5"), ואנחנו מחפשים את ה-Ref שלו:

public function getWarehouseRef(string $cityRef, string $warehouseNumber): ?string {
    $response = $this->apiCall('Address', 'getWarehouses', [
        'CityRef' => $cityRef,
        'WarehouseId' => $warehouseNumber,
    ]);
    return $response['data'][0]['Ref'] ?? null;
}

יצירת תעודת משלוח

public function createDocument( \Bitrix\Sale\Shipment $shipment, string $recipientCityRef, string $recipientWarehouseRef ): string {
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();
    $response = $this->apiCall('InternetDocument', 'save', [
        'NewAddress' => '1',
        'PayerType' => 'Recipient', // получатель платит за доставку
        'PaymentMethod' => 'Cash',
        'CargoType' => 'Cargo',
        'Weight' => max($shipment->getWeight() / 1000, 0.1),
        'ServiceType' => 'WarehouseWarehouse',
        'SeatsAmount' => '1',
        'Description' => 'Товар магазина',
        'Cost' => (string)round($order->getPrice()),
        'CitySender' => $this->getOption('SENDER_CITY_REF'),
        'Sender' => $this->getOption('SENDER_COUNTERPARTY_REF'),
        'SenderAddress' => $this->getOption('SENDER_WAREHOUSE_REF'),
        'ContactSender' => $this->getOption('SENDER_CONTACT_REF'),
        'SendersPhone' => $this->getOption('SENDER_PHONE'),
        'CityRecipient' => $recipientCityRef,
        'RecipientAddress' => $recipientWarehouseRef,
        'RecipientsPhone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        'RecipientName' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
    ]);
    return $response['data'][0]['IntDocNumber'] ?? '';
}

private function apiCall(string $model, string $method, array $props): array { $payload = [ 'apiKey' => $this->apiKey, 'modelName' => $model, 'calledMethod' => $method, 'methodProperties' => $props, ]; $ch = curl_init('https://api.novaposhta.ua/v2.0/json/'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json'], ]); $response = json_decode(curl_exec($ch), true); curl_close($ch); if (!$response['success']) { throw new \RuntimeException('НП API: ' . implode(', ', $response['errors'])); } return $response; } הוא סטנדרטי: הנמען משלם עבור המשלוח בעת קבלתו. public function getCityRef(string $cityName): ?string { $cache = \Bitrix\Main\Data\Cache::createInstance(); $key = 'np_city_' . md5($cityName); if ($cache->initCache(86400, $key, '/np/')) { return $cache->getVars(); } $response = $this->apiCall('Address', 'getCities', [ 'FindByString' => $cityName, 'Limit' => 5, ]); $ref = $response['data'][0]['Ref'] ?? null; if ($ref) { $cache->startDataCache(); $cache->endDataCache($ref); } return $ref; } פירושו שהחנות נושאת בעלות.

מעקב וטיפול בשגיאות

public function trackDocument(string $docNumber): array
{
    $response = $this->apiCall('TrackingDocument', 'getStatusDocuments', [
        'Documents' => [
            ['DocumentNumber' => $docNumber],
        ],
    ]);
    return $response['data'][0] ?? [];
}

מחזיר public function getWarehouseRef(string $cityRef, string $warehouseNumber): ?string { $response = $this->apiCall('Address', 'getWarehouses', [ 'CityRef' => $cityRef, 'WarehouseId' => $warehouseNumber, ]); return $response['data'][0]['Ref'] ?? null; } , public function createDocument( \Bitrix\Sale\Shipment $shipment, string $recipientCityRef, string $recipientWarehouseRef ): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $response = $this->apiCall('InternetDocument', 'save', [ 'NewAddress' => '1', 'PayerType' => 'Recipient', // получатель платит за доставку 'PaymentMethod' => 'Cash', 'CargoType' => 'Cargo', 'Weight' => max($shipment->getWeight() / 1000, 0.1), 'ServiceType' => 'WarehouseWarehouse', 'SeatsAmount' => '1', 'Description' => 'Товар магазина', 'Cost' => (string)round($order->getPrice()), 'CitySender' => $this->getOption('SENDER_CITY_REF'), 'Sender' => $this->getOption('SENDER_COUNTERPARTY_REF'), 'SenderAddress' => $this->getOption('SENDER_WAREHOUSE_REF'), 'ContactSender' => $this->getOption('SENDER_CONTACT_REF'), 'SendersPhone' => $this->getOption('SENDER_PHONE'), 'CityRecipient' => $recipientCityRef, 'RecipientAddress' => $recipientWarehouseRef, 'RecipientsPhone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), 'RecipientName' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), ]); return $response['data'][0]['IntDocNumber'] ?? ''; } , PayerType: Recipient, מידע על מחסן. סוכן Bitrix שואל כל שעתיים על משלוחים פעילים.

שגיאות אופייניות והטיפול בהן:

• מספר מחסן לא תקין: הלקוח מזין מספר שאינו קיים — המודול בודק דרך API ומדגיש את השגיאה לפני השמירה.
• אי-התאמות בשם העיר: הלקוח מקליד "Kiev" במקום "Kyiv". פתרון: נורמליזציה של קלט וחיפוש מטושטש.
• מזהי Ref מיושנים: ה-API עשוי להחזיר שגיאה אם מטמון הספרייה ישן. אנו משתמשים במטמון עם TTL של 24 שעות ורענון אוטומטי.

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

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

יתרונות ומקרה בוחן

יצירה ידנית של תעודת משלוח אורכת 2-3 דקות לכל הזמנה. עבור 150 הזמנות, מדובר ב-7-9 שעות בשבוע — עומס עבודה של עובד ייעודי. אוטומציה דרך API מבטלת עומס זה ומבטלת שגיאות הקלדה. בהשוואה להזנה ידנית, אוטומציה מהירה פי 3 ומפחיתה שגיאות משלוח ב-90%. שום תוסף צד שלישי לא מציע רמת אינטגרציה זו ללא התאמה אישית.

לקוח חנות בגדים (~150 הזמנות/יום, 99% דרך Nova Poshta) נתקל בבעיה גדולה: לקוחות הזינו מספרי מחסנים באופן שרירותי. יישמנו נורמליזציה של קלט וחיפוש מטושטש במהלך התשלום. לאחר היישום, תעודות משלוח שנוצרו באופן שגוי ירדו מכ-15 בשבוע לכמעט אפס.

התקנה ולוחות זמנים

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

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

מה כלול

• מודול אינטגרציה עם קוד מקור עבור 1C-Bitrix;
• תיעוד להתקנה, הגדרה ותפעול;
• הדרכת מנהלים (עד שעתיים);
• תמיכה טכנית למשך 30 יום לאחר המסירה;
• העברת כל זכויות הגישה (מאגר, פאנל ניהול, מפתח API).

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