Nova Poshta Premium — модуль Нова Пошта для OpenCart 2.3, 3.x і 4.x

Nova Poshta Premium — модуль для OpenCart 3.x та 4.x, який під’єднує магазин до Нової Пошти за 10 хвилин. Покупець обирає місто і відділення прямо в кошику, а ТТН створюється автоматично, коли ви переводите замовлення в статус «В обробці». Без чужих iframe, без переписування checkout-у, без щоденного копіювання даних у кабінет НП.

Базова версія — безкоштовна. Скачати з офіційного OpenCart marketplace: opencart.com/…/extension_id=48538. Преміум-функції (накладений платіж, поворотні накладні, авто-оновлення статусів, webhooks, multi-warehouse) розблоковуються ліцензійним ключем — купити нижче.

Живе демо

Модуль можна помацати руками до покупки: відкрити демо-магазин на OpenCart 4. Додайте будь-який товар у кошик і перейдіть до оформлення замовлення — на кроці доставки з’явиться блок «Доставка Новою Поштою» з живим пошуком міст і відділень через API Нової Пошти. Замовлення тестові, нічого оплачувати не потрібно (оберіть «Оплата при отриманні»).

Як це виглядає для покупця

Що отримує адмін

Як це працює — крок за кроком

1. Покупець на сайті обирає Нову Пошту як спосіб доставки, шукає місто, обирає відділення.
2. Замовлення створюється у вашій OC-адмінці зі збереженою прив’язкою до конкретного відділення.
3. Ви переводите замовлення у статус-тригер (за замовчуванням «В обробці»).
4. Модуль автоматично кличе НП API: створює отримувача-приватну особу (з вашого checkout-у — ПІБ, телефон), потім друкує ТТН. Номер пишеться у замовлення.
5. З Преміумом: погодинно опитує НП про статус кожного активного відправлення, отримує номер виплати при післяплаті, шле webhook вашій CRM/ERP на кожну зміну статусу.

Скільки коштує

2 490 грн — разова покупка. Ліцензія безстрокова: платите один раз, оновлення й технічна підтримка входять у ціну. Один ключ — один домен і його піддомени.

Переносите магазин на інший домен — деактивуйте ліцензію на старому й активуйте на новому самостійно в кабінеті.

Ліцензія безстрокова — нічого не спливає і не вимикається. Один ключ — один домен; переносите магазин — деактивуйте ліцензію на старому домені й активуйте на новому самостійно.

Один ключ — два домени (production + staging). Переносите магазин — деактивуйте ліцензію на старому домені й активуйте на новому самостійно, без звернення до підтримки.

Спершу тріал, потім оплата. Свіжий інстал — це безкоштовна версія: Pro сам не вмикається і нічого не гасне через тиждень. Коли захочете подивитись Pro — натисніть «Спробувати Pro» в налаштуваннях модуля, вкажіть email і отримайте ключ на 7 днів (він же прийде листом). Тож звірку післяплати, зворотну ТТН і масові операції ви перевіряєте на власному магазині ще до покупки — саме тому повернення коштів після оплати не передбачене.

Технічні вимоги

• OpenCart 4.0.2 – 4.1.x (4.2+ також працює) — або окрема збірка під OpenCart 3.0.2 – 3.0.5.0
• PHP 8.1+ (тестовано на 8.5 — захист від нових deprecation warnings всередині JSON-ендпоінтів)
• MySQL 5.7+ / MariaDB 10.3+
• API-ключ Нової Пошти — безкоштовний у вашому кабінеті: my.novaposhta.ua → Налаштування → Безпека → API
• Один зареєстрований профіль відправника у бізнес-кабінеті НП — у більшості мерчантів він вже є (без нього НП не дозволяє створювати ТТН з будь-якого джерела)

Що під капотом

• Native для OpenCart 4.x — PSR-4 неймспейси, events-API, Twig. Не OCMOD, не XML-моди. Сумісність з наступними OC-релізами без переписування.
• API-ключ зашифрований у БД — XOR з per-install секретом від wp-salt. Якщо хтось дампне БД — ключ не зчитається у відкритому вигляді.
• Кеш міст і відділень з лінивим оновленням — щотижневий повний sync через cron, lazy load відділень для запитуваних міст (TTL 7 днів). Підказки в чекауті відповідають за 44 мс замість 211 мс прямого виклику API.
• Дві стадії створення ТТН — спочатку Counterparty.save для отримувача (PrivatePerson із номером телефону у форматі НП), потім InternetDocument.save. Працює для всіх типів відправника — приватна особа, ФОП, ТОВ.
• HMAC-підписані webhooks з повторами: 5/10/20/40 хв exponential backoff, до 4 спроб. Підписи sha256, заголовок X-NP-Signature.

Як встановити

1. Завантажте nova_poshta_premium.ocmod.zip через Розширення → Інсталятор у вашій OC-адмінці. Для OpenCart 3.0.x використовуйте збірку nova-poshta-premium-oc3-1.2.8.ocmod.zip (доступна у завантаженнях товару).
2. Активуйте у списку, потім зайдіть у налаштування → натисніть «Завершити встановлення» (створить таблиці БД, події, крон-задачі).
3. Вставте API-ключ із вашого кабінету НП, натисніть «Перевірити підключення» — побачите «Зʼєднання працює».
4. Оберіть ваше місто і відділення → завантажте профіль відправника → збережіть.
5. Готово — у кошику зʼявиться блок з вибором НП-доставки.
6. Для Преміум-функцій: вставте ліцензійний ключ із email після оплати → «Активувати ліцензію».

Історія версій

1.2.17 (OpenCart 4.x) / 1.3.1 (OpenCart 3.x) / 1.3.1 (OpenCart 2.3) — 14 серпня 2026

Виправлено створення зворотної ТТН: запит до Нової Пошти йшов без підтипу причини повернення, а відділення підставлялося в поле, яке очікує адресу контрагента, — через це кнопка «Зворотна ТТН» падала з помилкою в усіх складаннях. Тепер перед створенням модуль запитує в перевізника, чи можливе повернення для цієї накладної, і показує саме його відповідь (наприклад, повернення недоступне, поки відправлення ще не передане в Нову Пошту).

1.2.16 (OpenCart 4.x) / 1.2.8 (OpenCart 3.x) — 3 серпня 2026

Розрахунок вартості через API Нової Пошти став окремою опцією і за замовчуванням вимкнений. Раніше поле вартості було лише запасним: щойно налаштовані API-ключ і місто відправника, вартість у кошику завжди перебивалася тарифом перевізника — магазини, де доставку оплачує отримувач, не мали як це вимкнути. Поле перейменовано на «Вартість доставки»: саме воно й показується покупцю. Крім того, нульова вартість більше не виглядає як безкоштовна доставка — метод підписується «(оплата при отриманні)», а замість «0 ₴» показується «за тарифами перевізника». Виправлено й порожню плашку, що висіла під блоком вибору відділення, поки відділення не обране.

1.2.7 — 23 липня 2026

Виправлено фатальну помилку у розрахунку способів доставки: getQuote() завантажував неіснуючу в OpenCart 4.x catalog-модель localisation/geo_zone, через що увесь список способів доставки не з’являвся («Потрібна адреса доставки»). Перевірка гео-зони тепер робиться прямим запитом до zone_to_geo_zone, як у стокових методів. Плюс: блок міста/відділення тепер з’являється лише після вибору методу «Нова Пошта» (спочатку метод — потім поля), не конфліктує з віджетами інших перевізників, і має демо-набір міст/відділень для клікабельного тесту без API-ключа.

1.2.5 — 20 липня 2026

Виправлено роботу інструментів у налаштуваннях модуля до першого збереження: пошук міста, список відділень, тестова перевірка тарифу та завантаження профілю відправника тепер використовують API-ключ, введений у полі. Раніше вони читали лише вже збережений ключ, тоді як кнопка «Перевірити підключення» перевіряла введений — через це відразу після вставки ключа з’являлося «Ключ дійсний», а пошук міста відповідав «Нічого не знайдено». Тепер достатньо вставити ключ і одразу шукати місто.

1.2.4 — 17 липня 2026

Виправлено пошук міст на магазинах, де OpenCart працює через драйвер бази PDO (DB_DRIVER = pdo): запит падав із SQL-помилкою, тому поле показувало «Нічого не знайдено», хоча ключ і модуль були справні. На драйвері mysqli проблеми не було. Вибір відділень не зачіпався — саме тому це виглядало як проблема з API-ключем.

1.2.3 — 17 липня 2026

Виправлено пошук міст на хостингах, де не увімкнене розширення PHP mbstring: поле показувало «Нічого не знайдено», хоча API-ключ був дійсний, а вибір відділень працював. Функції mb_strtolower / mb_substr тепер викликаються лише за наявності, з UTF-8 безпечними фолбеками. Стосується збірок і для OpenCart 4.x, і для 3.x — після оновлення нічого переналаштовувати не треба.

1.2.2 — 9 липня 2026

Дрібні виправлення адмінки та оновлені скріншоти. Функціональних змін немає.

1.2.1 — 29 червня 2026

Окрема збірка під OpenCart 3.0.2 – 3.0.5.0 — повний порт 4.x-версії (non-namespaced класи, OC3 events, Bootstrap-3 адмінка). Синхронізація коду та документації. Лінія OpenCart 4.x — без функціональних змін.

1.2.0 — 23 червня 2026

Кастомізація вигляду чекаут-блоку: акцентний колір, заокруглення кутів (0–28px) і тема (авто під дизайн магазину / світла / темна) — блок підлаштовується під будь-яку тему OpenCart. Плюс доопрацювання локалізації та picker-а в кошику.

1.1.0 — 24 травня 2026

Production-ready реліз: реальний license-клієнт зі звіркою до catcode.com.ua, перевірка product_slug (ключ від іншого продукту не активує цей модуль), гейтинг Преміум-функцій через License::isPro(), 14-денний offline grace, plain-language локалізація без жаргону, merge-fix у save handler.

1.0.c–f — травень 2026

Накладений платіж (BackwardDelivery + синхронізація виплат), поворотні ТТН через AdditionalServiceGeneral.save з причиною “відмова від отримання”, транслітерація Latin → Кирилиця у ПІБ отримувача (НП не приймає латиницю), нормалізація телефону у формат НП.

1.0.b — травень 2026

Кеш міст і відділень: таблиці np_cities + np_warehouses, щотижневий cron syncCities, lazy warehouse cache з TTL 7 днів. Прискорення вибору складу у ~5 разів (211 мс → 44 мс) — підказки в кошику стають миттєвими.

1.0.a — травень 2026

Справжнє створення ТТН: налаштування Counterparty-відправника в адмінці + двоетапний createTTN (Counterparty.save → InternetDocument.save). До цього було чернетка-stub.

0.7 — травень 2026

Перший повний MVP: install hook з створенням таблиць БД, storefront picker у кошику, чернетка ТТН на нове замовлення, погодинний cron статусів, webhook-система, шифрування API-ключа через XOR з per-install секретом.