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

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

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

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

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

• Коли API Нової Пошти не відповідає — магазин продає далі: міста й відділення беруться зі збереженого довідника, вартість — останній тариф Нової Пошти, а ТТН стають у чергу й створюються самі, щойно API оживе. На тестовому стенді із «завислим» API оформлення замовлення тривало 46 с до оновлення, а після — близько 1 с (перший покупець на початку збою — до 7 с).
• Native для OpenCart 4.x — PSR-4 неймспейси, events-API, Twig. Не OCMOD, не XML-моди. Сумісність з наступними OC-релізами без переписування.
• API-ключ зашифрований у БД — AES-256-CBC з перевіркою HMAC, ключ шифрування похідний від шляху встановлення магазину й назви його БД. Так само шифрується ліцензійний ключ. Якщо хтось дампне БД — ключ не зчитається у відкритому вигляді.
• Кеш міст і відділень з лінивим оновленням — щотижневий повний 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.3.14.ocmod.zip (доступна у завантаженнях товару), для OpenCart 2.3 — nova-poshta-premium-oc2-1.3.11.ocmod.zip.
2. Активуйте у списку, потім зайдіть у налаштування → натисніть «Завершити встановлення» (створить таблиці БД, події, крон-задачі).
3. Вставте API-ключ із вашого кабінету НП, натисніть «Перевірити підключення» — побачите «Зʼєднання працює».
4. Оберіть ваше місто і відділення → завантажте профіль відправника → збережіть.
5. Готово — у кошику зʼявиться блок з вибором НП-доставки.
6. Для Преміум-функцій: вставте ліцензійний ключ із email після оплати → «Активувати ліцензію».