Nova Poshta Premium — Нова Пошта для WooCommerce

Nova Poshta Premium для WooCommerce — модуль, який під’єднує ваш магазин до Нової Пошти за 10 хвилин. Покупець обирає місто і відділення прямо в чекауті, вартість доставки рахується за живим тарифом НП, а ТТН створюється з картки замовлення або автоматично — коли замовлення переходить у потрібний статус.

Віджет не просто додається збоку: він замінює поля адреси. Вулиця, місто, область та індекс заповнюються з обраного відділення, тож покупцю нема чого вводити вручну, а у вас у замовленні лишається коректна адреса доставки.

Базова версія безкоштовна — вибір відділення, тариф, створення ТТН і журнал відправлень. Ліцензія Преміум додає післяплату в ТТН, автоматичне оновлення статусів, зворотні накладні, звірку післяплат і вебхуки.

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

У чекауті замість звичного набору полів адреси покупець бачить один блок: місто з підказками (або список популярних міст в один клік) і список відділень та поштоматів цього міста. Після вибору вартість доставки в підсумку одразу перераховується за тарифом Нової Пошти.

Блок працює і на класичному чекауті, і на чекауті-блоках (Checkout Blocks): вибір зберігається через сесію WooCommerce, тому обидва варіанти поводяться однаково. Якщо покупець обрав Нову Пошту, але не вибрав відділення — замовлення не оформиться, поки вибір не зроблено.

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

Усі відправлення — в одному журналі: номер ТТН із посиланням на трекінг, отримувач, поточний статус, суми післяплати й номери грошових переказів.

У картці замовлення видно, яке саме відділення обрав покупець, і є кнопка створення ТТН — без переходів у кабінет НП.

Налаштування — одна сторінка

Модуль додається як звичайний метод доставки WooCommerce. Усі налаштування — на одній сторінці: ключ API, профіль відправника, правила ціни, вигляд віджета й автоматизація ТТН. Кнопки «Перевірити підключення» і «Тестова перевірка тарифу» одразу показують, чи все налаштовано правильно.

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

1. Вставляєте API-ключ із кабінету Нової Пошти й натискаєте «Перевірити підключення».
2. Обираєте своє місто, відділення та профіль відправника — з них створюватимуться ТТН.
3. Покупець у чекауті обирає місто й відділення, бачить вартість доставки за тарифом НП.
4. Замовлення зберігає місто, відділення й адресу доставки, а в журналі з’являється чернетка відправлення.
5. ТТН створюється кнопкою в замовленні або автоматично — при переході в обраний вами статус.
6. Статуси доставки оновлюються з API НП (автоматично — на Преміум, вручну кнопкою — на безкоштовній версії).

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

Безкоштовно: вибір міста та відділення в чекауті (класичний і блоковий), розрахунок тарифу, заміна й автозаповнення полів адреси, створення ТТН вручну та за статусом замовлення, журнал відправлень, кеш довідників, шифрування ключа.

Преміум: післяплата (грошовий переказ) у ТТН, автоматичне оновлення статусів щогодини, зворотні ТТН в один клік, звірка післяплат із сумами й номерами переказів, вихідні вебхуки на події доставки з підписом HMAC-SHA256.

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

• WordPress 6.2 або новіший
• WooCommerce 7.0 або новіший (сумісність з HPOS)
• PHP 7.4 або новіший
• API-ключ Нової Пошти з особистого кабінету

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

Модуль працює через офіційний API Нової Пошти (api.novaposhta.ua/v2.0). Довідники міст і відділень зберігаються у власних таблицях і оновлюються за розкладом, тому чекаут не чекає на зовнішній запит. API-ключ зберігається в базі в зашифрованому вигляді й ніколи не показується назад у формі. Жодних чужих iframe і підміни шаблонів чекауту — тільки штатні хуки WooCommerce.

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

1. Завантажте архів і встановіть його через «Плагіни → Додати новий → Завантажити плагін».
2. Активуйте плагін.
3. WooCommerce → Налаштування → Доставка → додайте метод «Нова Пошта» у потрібну зону.
4. Вставте API-ключ, збережіть і заповніть блок «Звідки відправляєте».

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

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

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

1.1.0 — пробний період Преміум на 7 днів за кліком: ключ приходить на e-mail, картка не потрібна. Свіжий інстал більше нічого не вмикає сам — Преміум-можливості видно на своїх місцях, неактивними, з позначкою Pro і поясненням, що вони дають. Зʼявився окремий екран «Вебхуки» (WooCommerce → Нова Пошта → Вебхуки): ендпоінти, секрет для підпису HMAC-SHA256, вибір подій і журнал доставок із повторами — раніше вебхуки можна було завести лише прямим записом у базу. Ключ ліцензії більше не затирається звичайним «Зберегти зміни». У журналі відправлень колонка «Отримувач» показує покупця, а напрямок переїхав у власну колонку «Куди».

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

1.0.0 — перший реліз: віджет вибору відділення для класичного чекауту й Checkout Blocks, живий тариф, створення ТТН, журнал відправлень, трекінг статусів, ліцензія Преміум.