В українському e-commerce інтеграція 1С-Бітрікс з Новою Поштою через API Нової Пошти автоматизує створення накладної та трекінг посилок. Ця інтеграція дозволяє значно скоротити витрати часу та помилок. За даними Нової Пошти, до 5% накладних містять помилки — при 150 замовленнях на день це 7-8 некоректних відправлень. Кожна помилка веде до повернення та втрати лояльності. За нашими даними, одне помилкове відправлення коштує магазину в середньому 200 грн через повернення та втрату лояльності. Інтеграція через API знижує цей показник до 0.5%. Автоматичне створення накладної краще за ручне в 5 разів за швидкістю та в 10 разів за кількістю помилок. Автоматизація також скорочує час обробки на 60%. Загальна економія на поверненнях та обробці помилок сягає 1500 грн на місяць. Вартість такої інтеграції — від 10 000 грн.
Інтеграція 1С-Бітрікс з Новою Поштою
Ми (TrueTech) за 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%. Жоден сторонній плагін не дає такого рівня інтеграції без доопрацювань.
Етапи налаштування
- Отримання API-ключа — реєструєтеся в кабінеті Нової Пошти, створюєте API-ключ.
- Встановлення модуля — підключаємо готове рішення з налаштуваннями відправника (Ref контрагента, адреси, контакти).
- Налаштування властивостей замовлення — прив'язуємо поля для номера відділення, телефону, ПІБ.
- Тестування — створюємо тестову накладну, перевіряємо трекінг.
- Деплой на бойовий — вмикаємо агент для оновлення статусів.
Процес впровадження інтеграції 1С-Бітрікс з Новою Поштою зазвичай займає до 8 робочих днів. Якщо API Нової Пошти тимчасово недоступний, модуль не блокує оформлення замовлення. Замовлення зберігається з позначкою "Очікує відправки", а агент повторює запит при наступному виконанні. Максимальна затримка — 2 години. При помилках валідації (наприклад, невірний Ref) адміністратор отримує email з описом проблеми.
Таблиця: Ручна vs Автоматична інтеграція
| Критерій | Ручна робота | Автоматична інтеграція |
|---|---|---|
| Час створення накладної | 2-3 хвилини | 10-30 секунд (в 5 разів швидше) |
| Частота помилок | 5% накладних | 0.5% (в 10 разів менше) |
| Витрати на помилки | ~200 грн за одне повернення | Мінімізовані |
| Витрати часу на 150 замовлень | 7-9 годин на тиждень | Автоматично |
Детальний опис превентивних заходів
Модуль перевіряє номер відділення через API перед збереженням замовлення. Якщо номер неіснуючий, поле підсвічується помилкою. Для назв міст використовується fuzzy-пошук за довідником Нової Пошти, що дозволяє виправити помилки на льоту. Ref-ідентифікатори кешуються на 24 години та автоматично оновлюються при першому запиті після завершення кешу.Кейс із практики
Один із наших клієнтів — магазин одягу, ~150 замовлень на добу, 99% через Нову Пошту. Основна проблема: клієнти вводили номер відділення довільно («відд 5», «5», «відділення №5»). Ми реалізували нормалізацію введення та fuzzy-пошук за довідником відділень при оформленні замовлення. Після впровадження кількість невірно оформлених накладних скоротилася з ~15 на тиждень практично до нуля. Замовлення почали йти без ручної корекції.
Строки та гарантії
| Етап | Строк (робочі дні) |
|---|---|
| Діагностика та вимоги | 1 — 2 |
| Розробка ядра (створення накладної) | 4 — 5 |
| Вибір відділення з підказками | +2 |
| Трекінг та сповіщення | +2 |
| Післяплата | +1 |
| Тестування та деплой | 1 — 2 |
Середній строк повного впровадження — до 8 робочих днів. Працюємо строго за договором з фіксацією строків. Гарантуємо стабільну роботу модуля після здачі. Сертифіковані спеціалісти 1С-Бітрікс з досвідом від 5 років та понад 50 проектів інтеграції з Новою Поштою.
Що входить у роботу
- Модуль інтеграції з вихідним кодом для 1С-Бітрікс;
- Документація зі встановлення, налаштування та експлуатації;
- Навчання адміністратора (до 2 годин);
- Технічна підтримка протягом 30 днів після здачі;
- Передача всіх доступів (репозиторій, адмінка, API-ключ).