Автоматизація доставки: 1С-Бітрікс + Нова Пошта

В українському e-commerce інтеграція 1С-Бітрікс з Новою Поштою через API Нової Пошти автоматизує створення накладної та трекінг посилок. Ця інтеграція дозволяє значно скоротити витрати часу та помилок. За даними Нової Пошти, до 5% накладних містять помилки — при 150 замовленнях на день це 7-8 некоректних відправлень. Кожна помилка веде до повернення та втрати лояльності. За нашими даними, одне помилкове відправлення коштує магазину в середньому 200 грн через повернення та втрату лояльності. Інтеграція через API знижує цей показник до 0.5%. Автоматичне створення накладної краще за ручне в 5 разів за швидкістю та в 10 разів за кількістю помилок. Автоматизація також скорочує час обробки на 60%. Загальна економія на поверненнях та обробці помилок сягає 1500 грн на місяць. Вартість такої інтеграції — від 10 000 грн.

Інтеграція 1С-Бітрікс з Новою Поштою

Ми (наша команда) за 5 років інтегрували Бітрікс з Новою Поштою на десятках проєктів і виробили алгоритм, що виключає збої. Наш досвід підтверджує: автоматизація економить до 1500 грн на місяць на поверненнях та обробці помилок. У цій статті розберемо, як налаштувати інтеграцію — від отримання API-ключа до повноцінного трекінгу. Ви дізнаєтесь, як уникнути типових проблем і які можливості відкриває готовий модуль.

Інтеграція 1С-Бітрікс з Новою Поштою через API

Нова Пошта надає єдиний JSON-API: https://api.novaposhta.ua/v2.0/json/. Авторизація через apiKey в тілі запиту. Формат запиту єдиний для всіх операцій. При реалізації інтеграції 1С-Бітрікс з Новою Поштою ми використовуємо наступний базовий метод:

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; } 

Детальна специфікація доступна в офіційній документації.

Пошук міста та відділення

НП використовує Ref-ідентифікатори для всіх об'єктів. Маппінг локації Бітрікс → Ref міста НП:

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; } 

Клієнт вводить номер відділення НП (наприклад, «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'] ?? ''; } public function trackDocument(string $docNumber): array { $response = $this->apiCall('TrackingDocument', 'getStatusDocuments', [ 'Documents' => [['DocumentNumber' => $docNumber]], ]); return $response['data'][0] ?? []; } 

PayerType: Recipient — стандарт українського e-commerce: отримувач оплачує доставку при отриманні. PayerType: Sender — магазин бере вартість на себе.

Як уникнути помилок при інтеграції?

При інтеграції часто зустрічаються такі помилки:

• Невірний номер відділення: клієнт вводить неіснуючий номер — модуль перевіряє номер через API та підсвічує помилку до збереження замовлення.
• Розбіжності в назвах міст: клієнт пише «Киев» замість «Київ». Рішення — нормалізація введення та fuzzy-пошук за довідником Нової Пошти.
• Застарілі Ref-ідентифікатори: API може повернути помилку, якщо кеш довідників застарів. Ми використовуємо кешування з TTL 24 години та автоматичне оновлення при першому запиті після завершення.

Всі помилки логуються в системний журнал Бітрікс, а адміністратору надсилається сповіщення. Повторні спроби виконуються з експоненційною затримкою (до 3 разів).

Превентивні заходи включають валідацію номера відділення через API перед збереженням замовлення, нормалізацію введення та автоматичне підставляння Ref міста за назвою. Fuzzy-пошук за довідником Нової Пошти дозволяє виправити помилки на льоту.

Як впровадити інтеграцію?

Ручне створення накладної займає 2-3 хвилини на замовлення, а автоматичне — 10-30 секунд, тобто в 5 разів швидше. При 150 замовленнях це 7-9 годин на тиждень — робота окремого співробітника. Автоматизація через API усуває це навантаження та виключає помилки. Порівняно з ручним введенням, автоматизація скорочує час обробки на 60% і знижує кількість помилок доставки на 90%. Жоден сторонній плагін не дає такого рівня інтеграції без доопрацювань.

Етапи налаштування

1. Отримання API-ключа — реєструєтеся в кабінеті Нової Пошти, створюєте API-ключ.
2. Встановлення модуля — підключаємо готове рішення з налаштуваннями відправника (Ref контрагента, адреси, контакти).
3. Налаштування властивостей замовлення — прив'язуємо поля для номера відділення, телефону, ПІБ.
4. Тестування — створюємо тестову накладну, перевіряємо трекінг.
5. Деплой на бойовий — вмикаємо агент для оновлення статусів.

Процес впровадження інтеграції 1С-Бітрікс з Новою Поштою зазвичай займає до 8 робочих днів. Якщо API Нової Пошти тимчасово недоступний, модуль не блокує оформлення замовлення. Замовлення зберігається з позначкою "Очікує відправки", а агент повторює запит при наступному виконанні. Максимальна затримка — 2 години. При помилках валідації (наприклад, невірний Ref) адміністратор отримує email з описом проблеми.

Таблиця: Ручна vs Автоматична інтеграція

Кейс із практики

Один із наших клієнтів — магазин одягу, ~150 замовлень на добу, 99% через Нову Пошту. Основна проблема: клієнти вводили номер відділення довільно («відд 5», «5», «відділення №5»). Ми реалізували нормалізацію введення та fuzzy-пошук за довідником відділень при оформленні замовлення. Після впровадження кількість невірно оформлених накладних скоротилася з ~15 на тиждень практично до нуля. Замовлення почали йти без ручної корекції.

Строки та гарантії

Середній строк повного впровадження — до 8 робочих днів. Працюємо строго за договором з фіксацією строків. Гарантуємо стабільну роботу модуля після здачі. Сертифіковані спеціалісти 1С-Бітрікс з досвідом від 5 років та понад 50 проектів інтеграції з Новою Поштою.

Що входить у роботу

• Модуль інтеграції з вихідним кодом для 1С-Бітрікс;
• Документація зі встановлення, налаштування та експлуатації;
• Навчання адміністратора (до 2 годин);
• Технічна підтримка протягом 30 днів після здачі;
• Передача всіх доступів (репозиторій, адмінка, API-ключ).