Nova Poshta Premium for OpenCart 4.x

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

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

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

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

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

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

Що включено в ліцензії

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

2 990 грн — одноразово, ліцензія назавжди. Купуєте раз, користуєтесь скільки завгодно — ніяких щорічних платежів, ніяких списань. Усі поточні Преміум-функції відкриваються одразу після активації ліцензії і працюють без обмеження за часом.

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

Оновлення модуля під нові версії OpenCart і API Нової Пошти отримуєте безкоштовно протягом усього часу володіння ліцензією. Якщо в майбутньому випустимо v2.0 з принципово новими можливостями — буде окрема пропозиція upgrade зі знижкою для існуючих клієнтів.

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

• OpenCart 4.0.2 – 4.1.x (4.2+ також працює)
• 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-адмінці.
2. Активуйте у списку, потім зайдіть у налаштування → натисніть «Завершити встановлення» (створить таблиці БД, події, крон-задачі).
3. Вставте API-ключ із вашого кабінету НП, натисніть «Перевірити підключення» — побачите «Зʼєднання працює».
4. Оберіть ваше місто і відділення → завантажте профіль відправника → збережіть.
5. Готово — у кошику зʼявиться блок з вибором НП-доставки.
6. Для Преміум-функцій: вставте ліцензійний ключ із email після оплати → «Активувати ліцензію».

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

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 секретом.