Автоматизация доставки: интеграция 1С-Битрикс с Новой Почтой

В украинском e-commerce Новая Почта — безальтернативный стандарт: около 80% заказов проходят через эту службу. По данным Новой Почты, до 5% накладных содержат ошибки — при 150 заказах в день это 7-8 некорректных отправлений. Каждая ошибка ведёт к возврату и потере лояльности. Интеграция через API снижает этот показатель до 0.5%. Автоматизация создания накладных, трекинга и выбора отделения устраняет ручной ввод и сокращает время обработки на 60%.

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

Как работает API Новой Почты?

Новая Почта предоставляет единый JSON-API: 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; } 

Подробная спецификация доступна в официальной документации.

Поиск города и отделения

НП использует 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'] ?? ''; } 

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

Трекинг

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

Возвращает StatusCode, Status, ScheduledDeliveryDate, информацию об отделении. Агент Битрикс опрашивает раз в 2 часа для активных отправлений.

Типичные ошибки и их обработка

При интеграции часто встречаются следующие ошибки:

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

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

Как избежать ошибок при создании накладной?

Превентивные меры включают валидацию номера отделения через API перед сохранением заказа, нормализацию ввода и автоматическую подстановку Ref города по названию. Fuzzy-поиск по справочнику Новой Почты позволяет исправить опечатки на лету.

Преимущества автоматизации

Ручное создание накладной занимает 2-3 минуты на заказ. При 150 заказах это 7-9 часов в неделю — работа отдельного сотрудника. Автоматизация через API устраняет эту нагрузку и исключает опечатки. По сравнению с ручным вводом, автоматизация сокращает время обработки на 60% и снижает количество ошибок доставки на 90%. Ни один сторонний плагин не даёт такого уровня интеграции без доработок.

Этапы настройки

1. Получение API-ключа — регистрируетесь в кабинете Новой Почты, создаёте API-ключ.
2. Установка модуля — подключаем готовое решение с настройками отправителя (Ref контрагента, адреса, контакты).
3. Настройка свойств заказа — привязываем поля для номера отделения, телефона, ФИО.
4. Тестирование — создаём тестовую накладную, проверяем трекинг.
5. Деплой на боевой — включаем агент для обновления статусов.

Что происходит при сбое API?

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

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

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

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

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

Что входит в работу

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

Хотите так же? Свяжитесь с нами для оценки вашего проекта. Закажите интеграцию под ключ — мы подготовим коммерческое предложение и покажем демо на ваших данных. Получите консультацию уже сегодня.