README

Українська · English

Доставка Новою поштою для Magento 2: покупець обирає місто й відділення або вводить адресу для кур'єра під час оформлення замовлення. Менеджер бачить ці дані в адмінпанелі та може підготувати ТТН у формі відправлення.

Модуль запитує вартість і орієнтовну дату доставки у Нової пошти, враховує вагу та габарити товарів і підбирає пакування через BoxPacker. Якщо магазин відправляє товари з кількох міст, розрахунок порівнює доступні варіанти. Також можна встановити фіксовану вартість доставки.

Розрахунок у Magento Luma для однієї одиниці Configurable Product 16: вага 3 кг, габарити 150 × 250 × 350 мм. Доставка до відділення в Києві коштує 195 грн. Тариф і орієнтовну дату отримано через API Нової пошти; вони залежать від маршруту, товарів і налаштувань відправника.

Як покупець обирає доставку

Для доставки в Україні покупець обирає спосіб Нової пошти, шукає населений пункт за назвою та вказує місце отримання. У результатах пошуку міста є назва області, щоб розрізняти населені пункти з однаковими назвами.

Для відділення доступний пошук точок видачі у вибраному місті. Список використовує довідники Nova Poshta Catalog.
Для доставки до дверей покупець обирає вулицю, вводить номер будинку й квартири. Позначка Приватний будинок дозволяє оформити адресу без квартири.
Після зміни міста поля відділення й вулиці очищуються, щоб у замовленні не залишилася адреса з попереднього міста.

Для того самого товару доставка до адреси в Києві коштує 255 грн за розрахунком Нової пошти. Назви полів залежать від локалізації магазину.

Після переходу до оплати розрахована вартість доставки входить до підсумку замовлення. Покупець бачить ціну товару й доставки окремо.

Підсумок у демонстраційному магазині: товар 7,22 грн, доставка 255 грн, разом 262,22 грн.

Збережені адреси

Зареєстрований покупець може вибрати адресу зі своєї адресної книги. Модуль відновлює пов'язані дані Нової пошти, зокрема місто, відділення або вулицю. Якщо адресу неможливо однозначно визначити чи вона не підходить до вибраного способу доставки, checkout пропонує додати нову.

Приклади збережених адрес у локальному демонстраційному магазині. Телефони приховані.

Робота менеджера

Під час створення відправлення (shipment) модуль дозволяє створити ТТН Нової пошти, не залишаючи адмінпанель Magento 2. У формі Ship менеджер перевіряє дані отримувача, обирає відправника, контактну особу й адресу відправлення та надсилає параметри посилки до Нової пошти.

Візуалізація пакування

На сторінці замовлення в Admin є експериментальний візуалізатор результатів пакування. Натисніть Visualise Box #1, щоб відкрити 3D-схему коробки: вона показує розміщення товарів і їхні габарити за результатом розрахунку BoxPacker. Для кожної коробки доступне окреме посилання.

Приклад пакування з демонстраційного замовлення. Візуалізація відкривається на сайті BoxPacker.

Налаштування магазину

Після встановлення відкрийте Stores → Configuration → Perspective Studio → Nova Poshta Shipping. Це посилання веде до налаштувань перевізника в Sales → Delivery Methods (у деяких версіях Magento: Shipping Methods), блок Novaposhta Shipping with shipping price calculation and TTN creation.

API-ключ, контактна особа та адреса відправника приховані.

У Nova Poshta Catalog увімкніть модуль, введіть API-ключ і налаштуйте оновлення довідників. Дочекайтеся завантаження областей, міст, відділень, вулиць і пакування. Для розкладу потрібен cron Magento.
Перевірте Directory Map у Catalog: відповідності областей Нової пошти регіонам Magento використовуються під час вибору адреси.
У налаштуваннях Shipping увімкніть Enabled, введіть API-ключ і задайте назву доставки. Ключ задається окремо для Catalog і Shipping.
Налаштуйте Is Organization відповідно до типу відправника. Виберіть Main Sender, Contact Person of the Sender і Contact Person Address. Ці списки беруть дані з облікового запису Нової пошти.
У Cities with Warehouse виберіть міста, звідки відправляєте товари. Вони потрібні для розрахунку вартості; під час створення ТТН адресу відправника обирають у формі відправлення.
У Allowed Methods залиште потрібні способи, перевірте правила вартості й збережіть конфігурацію. Заповніть вагу та габарити товарів.

Способи доставки

У назвах Warehouse означає відділення, а Client означає адресу відправника або отримувача.

Спосіб у налаштуваннях	Маршрут	Що вказує покупець
Warehouse to Warehouse (`w2w`)	Відділення → відділення	Відділення отримання
Warehouse to Client (`w2c`)	Відділення → адреса	Вулицю, будинок і квартиру або приватний будинок
Client to Warehouse (`c2w`)	Адреса → відділення	Відділення отримання
Client to Client (`c2c`)	Адреса → адреса	Вулицю, будинок і квартиру або приватний будинок

Вартість і дані товарів

Налаштування	Для чого воно потрібне
Always use default cost	Застосовувати задану вартість замість отриманого тарифу. Підходить також для магазинів, які хочуть встановити фіксовану ціну доставки замість розрахунку за тарифами Нової пошти
Default Cost	Фіксована або резервна вартість, коли розрахунок недоступний
Lathing cost	Доплата за обрешетування в розрахунку вантажу та палет
Free shipping cost	Поріг суми товарів для правил обрешетування й безкоштовної доставки

Назва Free shipping cost не означає, що кожне замовлення понад поріг отримає безкоштовну доставку. Правило залежить від результату перевірки товарів зі Special Price. Перевірте його на своєму асортименті перед запуском; Always use default cost має пріоритет над розрахованою вартістю.

Для товарів потрібні стандартна Weight у кілограмах і додані модулем Width, Length, Height у міліметрах. BoxPacker використовує ці дані та довідник пакування для розрахунку місць. Для configurable-товарів заповніть вагу й габарити також у пов'язаних simple-варіацій. Від сумарної ваги 85 кг код розрахунку переходить до типу вантажу Pallet.

У двокроковому checkout тариф може уточнюватися після збереження адреси та переходу до оплати. Перед запуском перевірте підсумкову вартість у валюті магазину, зокрема якщо базова валюта й валюта вітрини відрізняються.

Керування коробками

Відкрийте Stores → Configuration → Perspective Studio → Nova Poshta Catalog → View Lists → View List Of Package Types. Набір пакування спільний для всіх магазинів. Колонка Enabled for BoxPacker визначає дозвіл використання коробки; Active показує доступність запису довідника. BoxPacker використовує доступні й увімкнені коробки без відбору за сумарною вагою замовлення та сам обирає пакування за габаритами й максимальною вагою.

Три стандартні палети й наявне API-пакування дозволені за замовчуванням. Їх можна дублювати, вимикати й повторно вмикати. Змінювати параметри або видаляти можна лише кастомні коробки. Синхронізація НП зберігає ручне вимкнення для BoxPacker та не змінює стандартні й кастомні записи.

Через New Box створіть коробку з нуля або виберіть Duplicate у діях рядка. Копія створюється після збереження форми й надалі незалежна від оригіналу. Габарити задаються в міліметрах, максимальна вага й вага тари — у кілограмах. Additional Parameters дозволяє вказати внутрішні габарити й вагу тари; без них використовуються зовнішні габарити та нульова вага тари. Максимальна вага включає вагу коробки та її вмісту.

Масові дії дозволяють вмикати й вимикати пакування. Масове видалення пропускає стандартні та API-записи й повідомляє кількість пропущених коробок. Для керування потрібен дозвіл Manage BoxPacker Boxes у ролі адміністратора. Тимчасові коробки за габаритами товарів залишаються частиною розрахунку.

Для розробника

Вимоги й сумісність

Для роботи потрібен API-ключ Нової пошти.

Встановлення

З кореня Magento у PHP-середовищі вашого проєкту:

composer require perspectiveteam/module-novaposhtashipping
php bin/magento module:enable Perspective_NovaposhtaCatalog Perspective_NovaposhtaShipping
php bin/magento setup:upgrade
php bin/magento cache:clean config layout block_html eav

Composer встановлює залежності разом із модулем. У production виконайте компіляцію DI й розгортання статичних файлів згідно з процесом вашого проєкту.

Для встановлення з вихідного коду розмістіть модуль у app/code/Perspective/NovaposhtaShipping, встановіть залежності з composer.json і виконайте ті самі кроки активації та оновлення Magento. Не встановлюйте одночасно копію в app/code і Composer-пакет Shipping.

Точки інтеграції

Структура модуля

Компонент	Призначення
Model/Carrier/	Перевізник `novaposhtashipping`, способи, запити тарифів і дат доставки
Helper/Boxpacker.php	Підбір пакування за вагою та габаритами
Model/Carrier/ShippingSales.php	Правила доплат, порога й фіксованої вартості
view/frontend/	Checkout, пошук адрес і відновлення стану
Model/CustomerAddress/DeliveryData.php	Відновлення даних Нової пошти зі збереженої адреси
Model/Shipment/	Створення інтернет-документа Нової пошти
etc/extension_attributes.xml	Дані Нової пошти в адресі quote
Test/	Наявні PHP unit-тести та JavaScript-тести checkout і Admin

REST та збереження адреси

etc/webapi.xml містить публічні POST-маршрути пошуку довідників під /V1/novaposhtashipping/. Основні маршрути:

Маршрут	Параметри
`area`	`term`
`city`	`term`, необов'язкові `areaRef`, `includeArea`
`filtered_warehouses`	`cityRef`, `term`, необов'язкові `pageSizes`, `currentPage`
`streets-formatted-for-select`	`cityRef`, `term`

Підготовлені репозиторії повертають JSON-рядок зі списком {id, text}. Врахуйте це при обробці відповіді REST. includeArea додає areaRef і areaLabel до результатів міст. Для нових виборів доступність записів визначає Catalog.

Checkout передає Ref і поля адреси в extension_attributes адреси quote з префіксом perspective_novaposhta_shipping_: area, city, warehouse, street, building, flat, is_private_house, method. Дані адресної книги зберігаються в атрибуті novaposhta_shipping_data. Для адрес без Ref відновлення допускає лише точний однозначний збіг; неоднозначні дані потребують нового вибору покупця.

Data patches додають габарити товарів, атрибут адресної книги та метадані трьох рядків Street Address. Тип кешу модуля: novaposhta_operations_cache. Після зміни даних, що впливають на тариф, перевірте актуальність цього кешу.

Ліцензія

MIT · Perspective Studio

perspectiveteam / module-novaposhtashipping

Package info

Security

Statistics