Як підключити Нову Пошту до інтернет-магазину
Коротко
- → Рівень інтеграції залежить від обсягу: до 5 замовлень/день — базовий, 5-30 — середній, 30+ — повна автоматизація через API
- → Починайте з базового або середнього рівня — повна інтеграція має сенс лише коли ручна обробка з'їдає години
- → API Нової Пошти: всі запити POST із JSON, потрібен API-ключ із особистого кабінету (Налаштування → Безпека)
- → WooCommerce має готові плагіни для Нової Пошти — пошук відділень і поштоматів без написання коду
Навіщо взагалі інтегрувати Нову Пошту
Нова Пошта — де-факто монополіст доставки в Україні. Понад 80% замовлень з інтернет-магазинів йдуть через неї. Якщо у вас є інтернет-магазин і клієнт не може обрати відділення при оформленні замовлення — ви втрачаєте конверсію.
Різниця між «у нас є доставка Новою Поштою» і реальною інтеграцією — як між «ми приймаємо оплату» і підключеним платіжним шлюзом. В одному випадку менеджер вручну створює накладну, в іншому — система робить це сама.
Що дає повноцінна інтеграція: автоматичний розрахунок вартості доставки в кошику, вибір відділення або поштомату на чекауті, створення ТТН (товаро-транспортної накладної) одним кліком, відстеження статусу посилки — і все це без ручної роботи менеджера.
Три рівні інтеграції
Не кожному інтернет-магазину потрібна повна автоматизація. Рівень інтеграції залежить від кількості замовлень на день.
| Рівень | Що робить | Для кого |
|---|---|---|
| Базовий | Віджет вибору відділення, ТТН вручну в кабінеті НП | 1-5 замовлень/день |
| Середній | API-розрахунок вартості, ТТН одним кліком з адмінки | 5-50 замовлень/день |
| Повний | CRM + автостатуси + зворотня доставка + масовий друк | 50+ замовлень/день |
Базовий: віджет вибору відділення
Клієнт обирає місто і відділення з випадаючого списку на сторінці оформлення замовлення. Дані зберігаються в замовленні, менеджер створює ТТН вручну в кабінеті Нової Пошти. Підходить для магазинів з 1-5 замовленнями на день. Мінімум коду, мінімум ризиків.
Середній: API-розрахунок + автоматична ТТН
Вартість доставки рахується автоматично при оформленні. ТТН створюється з адмінки магазину одним кліком — без переходу в кабінет Нової Пошти. Підходить для 5-50 замовлень на день. Це рівень, на якому зупиняється більшість магазинів, і це правильно.
Повний: CRM + статуси + зворотня доставка
Усе з попереднього рівня, плюс: автоматичне оновлення статусів доставки, повідомлення клієнту про зміну статусу, обробка зворотньої доставки та грошових переказів, масовий друк накладних. Потрібен для 50+ замовлень на день і зазвичай інтегрується з CRM-системою.
Рекомендація: починайте з базового або середнього рівня. Повна інтеграція має сенс, коли ручна обробка замовлень починає з'їдати час менеджера — а це зазвичай від 30-50 замовлень на день.
Як працює API Нової Пошти
API (що таке API) Нової Пошти — це REST-подібний інтерфейс на адресі https://api.novaposhta.ua/v2.0/json/. Усі запити — POST із JSON-тілом. Для роботи потрібен API-ключ, який генерується в особистому кабінеті: Налаштування → Безпека → Мої ключі API.
Кожен запит має однакову структуру: apiKey, modelName (група методів), calledMethod (конкретний метод) і methodProperties (параметри). Наприклад, щоб отримати список відділень у Києві, потрібна модель AddressGeneral і метод getWarehouses.
Ключові методи API
- Address → getWarehouses — список відділень та поштоматів. Фільтр по місту, типу відділення, рядку пошуку
- Address → getCities — довідник міст. Потрібен для випадаючого списку міст на чекауті
- Address → getSettlements — повний довідник населених пунктів (включаючи села)
- InternetDocument → save — створення ТТН. Найскладніший метод з десятками параметрів
- InternetDocument → getDocumentPrice — розрахунок вартості доставки
- TrackingDocument → getStatusDocuments — відстеження статусу посилки
Документація доступна на developers.novaposhta.ua. Чесно скажу: вона не ідеальна. Один і той же результат можна отримати кількома способами, і не завжди зрозуміло який правильний. На DOU регулярно скаржаться на якість документації. Але працювати можна — якщо вже маєте досвід із API.
WooCommerce: які плагіни обрати
Якщо ваш магазин на WordPress + WooCommerce, плагін — найшвидший шлях до інтеграції. На ринку три основних варіанти:
Nova Post for WooCommerce (офіційний)
Офіційний плагін від самої Нової Пошти, з'явився у 2026 році. Автоматичне створення відправлень, друк етикеток, розрахунок тарифів, вибір відділення на чекауті, відстеження. Працює і для міжнародних доставок (Нова Пошта Глобал). Мінус — поки молодий, менше відгуків і менше обкатаний ніж альтернативи.
Plugin Nova Poshta for WooCommerce
Найпопулярніший сторонній плагін. Розрахунок вартості для кур'єрської та складської доставки, безкоштовна доставка від заданої суми, синхронізація довідників. Є безкоштовна і PRO-версія. Мінус — підтримка буває повільною, бувають конфлікти після оновлень WooCommerce.
WC Ukraine Shipping (SmartyParcel)
Універсальне рішення: Нова Пошта + Укрпошта + Meest + Rozetka Delivery в одному плагіні. Створення ТТН, відстеження, друк накладних. Можливість розділити доставку на відділення і кур'єрську як окремі методи. Якщо у вас кілька служб доставки — це найзручніший варіант.
Який обрати
Тільки Нова Пошта і хочете офіційну підтримку → Nova Post for WooCommerce. Тільки Нова Пошта і потрібна перевірена стабільність → Plugin Nova Poshta for WooCommerce. Кілька служб доставки → WC Ukraine Shipping. У будь-якому випадку тестуйте на стейджинг-сайті перед продакшеном — конфлікти з темою або іншими плагінами бувають.
Кастомна інтеграція: коли плагін не підходить
Плагін не підходить у трьох випадках: ваш магазин не на WordPress, вам потрібна нестандартна логіка (наприклад, різні відправники для різних міст), або ви інтегруєте з обліковою системою (1С, BAS, Odoo).
Кастомна інтеграція — це PHP-бекенд (або Node.js), який спілкується з API Нової Пошти напряму. Для PHP є готова бібліотека lis-dev/nova-poshta-api-2 (Composer), яка обгортає всі методи API у зручні PHP-виклики. Для JavaScript є @shopana/novaposhta-api-client на npm.
Що зазвичай входить у кастомну інтеграцію:
- Вибір міста з автодоповненням (запит
getCities) - Список відділень і поштоматів для обраного міста (запит
getWarehouses) - Розрахунок вартості доставки з урахуванням ваги, габаритів, типу доставки
- Створення ТТН з адмінки магазину
- Webhook або cron для оновлення статусів
Порахувати вартість магазину з інтеграцією можна через калькулятор. Орієнтовно кастомна інтеграція Нової Пошти додає 5 000 – 15 000 грн до вартості розробки, залежно від рівня.
Поштомати та адресна доставка
Нова Пошта має три типи доставки, і кожен потребує різної логіки на сайті.
На відділення (WarehouseWarehouse)
Класика. Клієнт обирає місто і відділення з випадаючого списку на чекауті. Найпростіший тип для інтеграції — один запит getWarehouses і готово. 80-90% замовлень на старті йдуть саме так.
На поштомат (WarehousePostomat)
Технічно це окремий тип відділень в API. Головний нюанс — не кожна посилка вміститься: є обмеження по вазі (до 30 кг) і габаритах комірки. Фільтруйте тип через параметр TypeOfWarehouseRef, інакше клієнт обере поштомат для 20-кілограмової коробки і буде неприємний сюрприз.
Адресна доставка кур'єром
Три комбінації в API: WarehouseDoors, DoorsWarehouse, DoorsDoors. Клієнт вводить вулицю і номер будинку, для чого потрібен запит getStreet з автодоповненням. Складніше реалізувати, але попит зростає — особливо в Києві, Львові, Одесі, де людям простіше отримати на двері.
Мій підхід: починаю з відділень і поштоматів, а адресну доставку додаю тільки коли бачу реальний попит від клієнтів магазину. На старті це зайва складність.
Типові помилки при інтеграції
Бачив ці помилки десятки разів — і в чужих проєктах, і в плагінах. Всі вони призводять до одного: чекаут ламається, клієнт іде.
Довідники без кешу
Запит getWarehouses по всій Україні повертає тисячі записів. Якщо кожен відвідувач при кожному завантаженні чекауту тягне весь довідник з API — ви швидко вичерпаєте ліміт запитів і отримаєте повільний чекаут. Кешуйте на сервері, оновлюйте раз на добу через cron.
Перевірка тільки HTTP-коду
API Нової Пошти завжди повертає HTTP 200 — навіть коли все пішло не так. Реальні помилки лежать у полі errors тіла відповіді. Якщо перевіряти тільки статус-код — ви місяцями не побачите, що щось зламалось. Я на цьому попався один раз — більше не повторюю.
API-ключ у фронтенді
API-ключ не повинен бути в JavaScript-коді на клієнті. Усі запити — тільки через серверний бекенд. Інакше будь-хто відкриє DevTools, скопіює ключ і використає його для своїх потреб. Це базова безпека, але я досі бачу це навіть у комерційних плагінах.
Прострочений ключ
API-ключ має термін дії. Коли він закінчиться — усі запити тихо перестануть працювати, і ви дізнаєтесь про це від клієнтів. Поставте собі нагадування в календар за місяць до закінчення.
Застарілий довідник відділень
Нова Пошта постійно відкриває і закриває відділення. Якщо ваш довідник не оновлювався місяць — клієнти обиратимуть відділення, яких уже фізично нема. А ті, що відкрились нещодавно, не з'являться у списку.
Вага «за замовчуванням»
Вартість доставки без реальної ваги товару — неточна. Якщо у вас товари від 100 г до 20 кг, а розрахунок іде по «середній вазі 1 кг» — клієнти бачать одну суму на чекауті, а платять іншу при отриманні. Це підриває довіру і генерує звернення в підтримку.
Скільки коштує інтеграція
Орієнтовні ціни на 2026 рік:
- WooCommerce плагін (базовий): безкоштовно. Встановлення + налаштування — 2 000 – 5 000 грн
- WooCommerce плагін (PRO): 500 – 2 000 грн/рік за ліцензію + налаштування
- Кастомна інтеграція (базовий рівень): 5 000 – 10 000 грн. Вибір відділення + розрахунок доставки
- Кастомна інтеграція (середній): 10 000 – 20 000 грн. Все вище + створення ТТН + відстеження
- Кастомна інтеграція (повний): 20 000 – 40 000 грн. CRM + статуси + масовий друк + зворотня доставка
Саме API Нової Пошти — безкоштовне. Ви платите тільки за розробку інтеграції. Точну вартість з урахуванням вашого магазину можна розрахувати через калькулятор вартості сайту.
Часті запитання
Для базових функцій (отримання довідників, розрахунок вартості, відстеження) достатньо звичайного акаунту на сайті Нової Пошти і згенерованого API-ключа. Для створення ТТН через API потрібен бізнес-акаунт з підключеним сервісом «Бізнес-кабінет». Реєстрація безкоштовна.
У Нової Пошти є ліміти, але офіційно вони не публікують точні цифри. На практиці для малого і середнього магазину лімітів вистачає з головою. Якщо кешувати довідники і не робити зайвих запитів, навіть 500 замовлень на день не створять проблем. При дуже великих обсягах варто звернутися до менеджера Нової Пошти для розширеного доступу.
Shopify — так, через сторонні додатки або API-інтеграцію. Tilda — обмежено: є віджет вибору відділення, але повноцінної інтеграції з автоматичним створенням ТТН нема. Для серйозного магазину Tilda в принципі не найкращий вибір — обмеження платформи заважатимуть.
Якщо довідники закешовані на вашому сервері — клієнти зможуть обрати відділення навіть при тимчасовій недоступності API. Не працюватиме тільки розрахунок вартості в реальному часі та створення ТТН. На практиці API Нової Пошти працює стабільно, але закладати фолбек для критичних функцій — правильний підхід.
Оптимально — cron-задача раз на добу, вночі. Запит getWarehouses по всіх містах, збереження результату в базу даних або файловий кеш. Деякі плагіни роблять це автоматично. Якщо кастомна інтеграція — налаштуйте cron вручну і логуйте помилки.
Так. При створенні ТТН через метод InternetDocument/save є параметри для накладеного платежу (BackwardDeliveryData). Вказуєте суму, і Нова Пошта збере гроші з отримувача і перекаже вам на рахунок. Це одна з найпопулярніших функцій для українських інтернет-магазинів.
Так. На WooCommerce найпростіше через плагін WC Ukraine Shipping — він підтримує обидві служби в одному інтерфейсі. Для кастомної інтеграції підключаєте API кожної служби окремо. У Укрпошти теж є API, хоча воно менш розвинуте ніж у Нової Пошти.
Не знайшли відповідь?
Висновок
Інтеграція Нової Пошти — не розкіш, а базова вимога для будь-якого інтернет-магазину в Україні. Клієнт, який не може обрати відділення на чекауті, йде до конкурента. Менеджер, який вручну створює 30 ТТН на день, витрачає години замість хвилин.
Для WooCommerce — починайте з плагіну, не вигадуйте велосипед. Для кастомних проєктів — закладайте інтеграцію в бюджет від початку, а не дописуйте після запуску.
Якщо плануєте магазин і не знаєте з чого почати — загляньте у скільки коштує інтернет-магазин. Там розклав усі статті витрат, включаючи інтеграції з доставкою.
