Автоматизация доставки: интеграция 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-ключ).

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