В украинском e-commerce Новая Почта — безальтернативный стандарт: около 80% заказов проходят через эту службу. По данным Новой Почты, до 5% накладных содержат ошибки — при 150 заказах в день это 7-8 некорректных отправлений. Каждая ошибка ведёт к возврату и потере лояльности. Интеграция через API снижает этот показатель до 0.5%. Автоматизация создания накладных, трекинга и выбора отделения устраняет ручной ввод и сокращает время обработки на 60%.
Мы (TrueTech) за 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%. Ни один сторонний плагин не даёт такого уровня интеграции без доработок.
Этапы настройки
- Получение API-ключа — регистрируетесь в кабинете Новой Почты, создаёте API-ключ.
- Установка модуля — подключаем готовое решение с настройками отправителя (Ref контрагента, адреса, контакты).
- Настройка свойств заказа — привязываем поля для номера отделения, телефона, ФИО.
- Тестирование — создаём тестовую накладную, проверяем трекинг.
- Деплой на боевой — включаем агент для обновления статусов.
Что происходит при сбое API?
Если API Новой Почты временно недоступен, модуль не блокирует оформление заказа. Заказ сохраняется с пометкой "Ожидает отправки", а агент повторяет запрос при следующем выполнении. Максимальная задержка — 2 часа. При ошибках валидации (например, неверный Ref) администратор получает email с описанием проблемы.
Кейс из практики
Один из наших клиентов — магазин одежды, ~150 заказов в сутки, 99% через Новую Почту. Основная проблема: клиенты вводили номер отделения произвольно («відд 5», «5», «відділення №5»). Мы реализовали нормализацию ввода и fuzzy-поиск по справочнику отделений при оформлении заказа. После внедрения число неверно оформленных накладных сократилось с ~15 в неделю практически до нуля. Заказы начали уходить без ручной корректировки.
Сроки и гарантии
| Этап | Срок (рабочие дни) |
|---|---|
| Диагностика и требования | 1 — 2 |
| Разработка ядра (создание накладной) | 4 — 5 |
| Выбор отделения с подсказками | +2 |
| Трекинг и уведомления | +2 |
| Наложенный платёж | +1 |
| Тестирование и деплой | 1 — 2 |
Средний срок полного внедрения — до 8 рабочих дней. Работаем строго по договору с фиксацией сроков. Гарантируем стабильную работу модуля после сдачи. Сертифицированные специалисты 1С-Битрикс с опытом от 5 лет и более 50 проектов интеграции с Новой Почтой.
Что входит в работу
- Модуль интеграции с исходным кодом для 1С-Битрикс;
- Документация по установке, настройке и эксплуатации;
- Обучение администратора (до 2 часов);
- Техническая поддержка в течение 30 дней после сдачи;
- Передача всех доступов (репозиторий, админка, API-ключ).
Хотите так же? Свяжитесь с нами для оценки вашего проекта. Закажите интеграцию под ключ — мы подготовим коммерческое предложение и покажем демо на ваших данных. Получите консультацию уже сегодня.