> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/gotovi-integraciyi/popular_integration/populyarni-integraciyi/magento.md). # Magento [**\[До інтеграції\]**](https://commercemarketplace.adobe.com/novapost-nova-post-shipping.html) Модуль **Nova Post Shipping для Magento 2 / Adobe Commerce** — це офіційне професійне рішення для автоматизації міжнародної та локальної доставки у понад 16 країн Європи та в Україну. Модуль інтегрує інтерактивний віджет карти в checkout Magento, дозволяє автоматично або вручну генерувати експрес-накладні (ЕН), розраховувати тарифи у реальному часі чи за фіксованою ставкою, роздруковувати повний комплект супровідних та митних документів безпосередньо з списку замовлень (Order Grid) або картки замовлення (Order View). #### [Основні можливості модуля та доступна географія доставки](https://docs.google.com/document/d/1av3aDiN5LRVbQOnuxLE4G1b2MW2fBXYFSoHZvFX2Fhw/edit?tab=t.f2peaq2ttwwe) ### Що потрібно для коректної роботи з модулем * **Договір на надання послуг з Nova Post**. Для коректної роботи з плагіном необхідний договір бізнес-клієнта з Nova Post. Щоб підписати договір, напишіть [на пошту відділу продажів у вашій країні](https://api-portal.novapost.com/help-center). * **API-ключ**. Зареєструйтесь у бізнес-кабінеті My Nova Post та згенеруйте ключ: [детальна інструкція](https://api-portal.novapost.com/uk/api-nova-post/start/api-keys). За потреби провести тестування, згенеруйте тестовий API-ключ [за посиланням](https://api-portal-stage.novapost.com/en/test-api-keys/). {% hint style="info" %} Під час налаштування модулю вам необхідно буде вказати: * Номер договору на логістичні послуги * API-ключ Номери договорів не відображаються у бізнес-кабінеті. Якщо вам необхідно дізнатись номер договору, напишіть [на пошту відділу продажів у вашій країні](https://api-portal.novapost.com/help-center). {% endhint %} ### Встановлення модуля Nova Post у Magento [Завантажити з Adobe Commerce Marketplace](https://commercemarketplace.adobe.com/novapost-nova-post-shipping.html) {% hint style="warning" %} **Важливо!** Використовуйте лише офіційний модуль Nova Post з Adobe Commerce Marketplace або встановлюйте його через Composer для гарантії стабільної роботи, безпеки даних та своєчасних оновлень. {% endhint %} Модуль можна встановити двома офіційними способами: 1. **Завантаження з Adobe Commerce Marketplace**: Перейдіть на[ сторінку модуля Nova Post](https://commercemarketplace.adobe.com/novapost-nova-post-shipping.html), додайте його до свого акаунту та встановіть через Web Setup Wizard або компонентний менеджер. 2. **Встановлення через Composer (рекомендовано)**: Виконайте командні стрічки у терміналі вашого сервера в кореневій директорії Magento: ``` composer require novapost/module-shipping php bin/magento module:enable NovaPost_Shipping php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento cache:clean ``` ### Налаштування модуля #### Налаштування у розділі Nova Post Base Перейдіть: **Stores** → **Configuration** → **Nova Post** → **Nova Post Base** **Departure Countries**: Виберіть країни, з яких ви здійснюватимете відправку замовлень (країни реєстрації вашого бізнесу/складів). Обрані країни надалі відображатимуться у списку доступних краін-відправників у базових налаштуваннях: **Nova Post Settings** → **Shipment Departure Method** → **Country**. ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FmZKe7VfVePIdq2y8zxSh%2Funknown.png?alt=media\&token=1dc9498b-f75d-4174-b703-56bb4b358654) #### Налаштування у розділі Nova Post Settings Перейдіть: **Stores** → **Configuration** → **Nova Post** → **Nova Post Settings** **Розділ API Configuration** * Налаштування робочого середовища. Вставте робочий API-ключ, який [згенерували у бізнес-кабінеті](https://api-portal.novapost.com/uk/api-nova-post/start/api-keys). * Налаштування тестового середовища. Поставте Yes у полі Testing API, якщо проводите тестування. [Вставте тестовий API-ключ](https://api-portal-stage.novapost.com/en/test-api-keys/) у поле Stage API Key. Це дозволить перевірити створення відправлень без створення реальних накладних та нарахування оплати за послуги.
Приклад заповнення розділу API Configuration ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2F2ENwFEoq62V0JcudYZ3Z%2Funknown.png?alt=media\&token=2c7f8873-03b4-4019-9171-cc96199d83a7)
**Розділ Contract Numbers** * **Domestic Contract Number**: Вкажіть номер договору для доставки по країні. * **International Contract Number**: Вкажіть номер договору для міжнародної доставки. Для доставки в інші країни.
Приклад заповнення розділу Contract Numbers ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FzDscVG6AUzYFEOXtBTCm%2Funknown.png?alt=media\&token=04d10a8f-23e3-4e91-9a1c-9f3173230a64)
**Розділ Sender Data** Заповніть поля: * **First Name / Last Name**: Ім'я та прізвище відправника. * **Email / Phone**: Контактна електронна пошта та номер телефону. * **Company TIN**: Податковий номер компанії (ЄДРПОУ / ІПН / NIP / VAT ID). * **Company Name**: Офіційна назва компанії. {% hint style="warning" %} **Важливо!** Дані компанії мають співпадати з інформацією, вказаній у вашому договорі з Nova Post. {% endhint %} * **EORI Code**: Код EORI (Economic Operators Registration and Identification). Обов'язково для міжнародних відправлень, які проходять митне оформлення (між ЄС та країнами поза ЄС). * **IOSS**: Номер Import One-Stop Shop. Використовується для спрощеної сплати ПДВ при продажу товарів вартістю до €150 покупцям у ЄС з-за меж ЄС.
Приклад заповнення розділу Sender Data ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FmczlHbCiuAA7R0IXnZ8E%2Funknown.png?alt=media\&token=c8d012af-a41c-4763-a4e4-501aa4f4b4d3)
**Розділ Shipment Departure Method** Налаштуйте спосіб передачі посилок перевізнику: * **Division** : Ви самостійно приноситимете посилки у вибране відділення, пункт або поштомат Nova Post. * **Address (Адреса)**: Виклик кур'єра Nova Post на ваш склад або в офіс. {% hint style="info" %} **Правило заповнення поля «City»**: Вказуйте лише назву міста або населеного пункту (наприклад, `Riga`, `Warsaw`), без вказування області, району чи ком. Зверніть увагу, що `Riga` та `Rīga` сприймаються системою як два різні записи. {% endhint %}
Приклад заповнення розділу Departure Method ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FGGZ8rIxRhW3L48a9DMzO%2Funknown.png?alt=media\&token=97e90e46-696e-422c-a0cd-7cacd330f01c)
**Розділ Product Information** Дані за замовчуванням використовуються для розрахунку вартості доставки, якщо в картці товару не заповнено індивідуальні параметри: * **Default Product Weight (kg)**: Вага товару за замовчуванням. * **Length / Width / Height (cm)**: Габарити товару за замовчуванням. * **Default HS Code**: Універсальний код для класифікації товарів на митниці за замовчуванням.
Приклад заповнення розділу Product Information ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FNQ4oHC4xl4KcB7k9uYNM%2Funknown.png?alt=media\&token=58194ad8-94b9-4042-93c3-39904f694ef6)
**Розділ Shipment Automation** Automatic Shipment Creation визначає спосіб створення відправлень: * Yes = автоматично після оформлення замовлення покупцем. Покупець одразу отримає лист з номером посилки для відстеження. * No = відправлення створює менеджер через адмін-панель. **Розділ Carrier Shipping Calculation** Налаштуйте розрахунок вартості доставки для кожного з типів доставки: Nova Post to Division (у відділення/поштомат) та Nova Post to Address (кур'єром на адресу). Для кожного типу вкажіть Calculation Mode: * **Carrier Calculation**: Розрахунок у реальному часі через API Nova Post залежно від ваги, габаритів, оголошеної або фактурної цінності та місця доставки. * **Flat Rate**: Фіксована вартість доставки, вказана продавцем. * **Free Delivery (Опціонально)**: Увімкніть опцію та вкажіть поріг суми замовлення: **Free Delivery Threshold**. При досягненні цієї суми у кошику доставка для покупця стає безплатною.
Приклад заповнення розділу Carrier Shipping Calculation ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FaOFvTAKCNjenaFAo5ZBg%2Funknown.png?alt=media\&token=521f9eb3-5ad7-4a2c-97ce-87fba0141f39)
#### Налаштування способів доставки Перейдіть: **Stores** → **Configuration** → **Sales** → **Delivery Methods** → **Nova Post** У цьому розділі активуються служби доставки, які бачитиме покупець на сторінці **Checkout**, для цього у полі **Enabled for Checkout** встановіть **Yes**. **Carrier Title, Method Title for Division, Method Title for Adress**: поля визначають назву перевізника та способу доставки. Заповненюється автоматично. **Show Method If Not Applicable**: вкажіть, чи потрібно показувати покупцеві спосіб доставки, якщо він не доступний для його регіону. **Sort Order**: **Розділи Nova Post to Division та Nova Post to Address** **Applicable countries** визначає, в які країни доступна доставка. Налаштуйте доступність кожного способу доставки окремо. * **All Allowed Countries** – всі дозволені країни. * **Sell to specific countries** – виберіть країни, для яких буде доступна доставка Nova Post. Вказуйте тільки ті, у яких оперує Nova Post. **Перелік країн, куди можлива доставка Nova Post**: Україна, Молдова, Польща, Литва, Чехія, Румунія, Німеччина, Словаччина, Естонія, Латвія, Угорщина, Італія, Велика Британія, Іспанія, Франція, Австрія, Нідерланди, США.
Приклад заповнення розділу Delivery Methods ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FyjcPgsPKn963ZqBOalac%2Funknown.png?alt=media\&token=d7d821bc-b36b-45eb-b4ee-e5ec8a52fc8d)
#### Налаштування валюти Перейдіть: **Stores** → **Configuration** → **General** → **Currency Setup** **Base Currency**: вкажіть валюту розрахунку з Nova Post здійснює внутрішні розрахунки у **Базовій валюті магазину (Base Currency)**, яка повинна відповідати валюті вашого договору з Nova Post. Наприклад, якщо відправки здійснюються з території Польщі, у Base Currency слід казати PLN, якщо з Румунії — RON. **Default Display Currency**: валюта, яка відображається покупцю. **Allowed Currencies**: Якщо ви також використовуєте валюту відображення, яка відрізняється від базової, Magento конвертує вартість доставки за курсом вашого магазину (Stores → Currency Rates). Це стандартна поведінка Magento для всіх способів доставки. {% hint style="info" %} Рекомендація: зберігайте Базову валюту та Валюту відображення однаковими або своєчасно оновлюйте курси в розділі Магазини (Stores) → Курси валют (Currency Rates). {% endhint %}
Приклад заповнення розділу Currency Options ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FoFm5yflhIYCvDejgChUq%2Funknown.png?alt=media\&token=7be05fff-7916-412e-a2d7-84207ef81e0e)
#### Налаштування товарів Модуль додає спеціальний блок **Nova Post Product Settings** у кожну картку товару: **Catalog** → **Products** → **редагування товару**. Оскільки стандартно Magento підтримує лише вагу, модуль додає відсутні поля, необхідні для точного розрахунку тарифів та митного оформлення: * **Length (cm) / Width (cm) / Height (cm)**: Індивідуальні габарити товару. Якщо залишити порожніми, будуть використані базові значення з налаштувань модуля. * **Product Title in English**: Назва товару англійською мовою (обов'язково для міжнародних декларацій та інвойсів). Якщо поле порожнє, система використовує стандартну назву товару з Magento. * **HS Code**: Код класифікації товару. {% hint style="warning" %} **Вимоги до HS Code**: * Код має складатися з **8–10 цифр**. * Якщо код коротший за 8 цифр — доповніть його нулями в кінці (наприклад, `6109100000`). * Якщо код довший за 10 цифр — видаліть зайві символи в кінці. * Для відправлень у **Молдову**, **США та Канаду** HS Code обов'язково повинен містити **рівно 10 цифр**. {% endhint %} Зверніть увагу: Доставка Nova Post доступна тільки для фізичних товарів (`Simple Products`). Якщо у кошику знаходяться лише віртуальні товари, крок вибору доставки в Magento пропускається. Для налаштування товарів (`Configurable Products`) переконайтеся, що всі дочірні `Simple Products` мають вказану вагу та габарити.
Приклад заповнення розділу Nova Post Product Settings ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FwrlLZ5g4gJldInxWmjpE%2Funknown.png?alt=media\&token=9827c896-5c17-4984-ade3-23750b03554b)
### Управління замовленнями та створення накладних #### Як створити експрес-накладну Доступно у двох режимах: **Order View** або **Order Grid**.
Order View – створення відправлення з картки замовленняOrder Grid – створення відправлення із переліку замовлень

  1. Перейдіть у Sales → Orders та відкрийте потрібне замовлення.
  2. У блоці Nova Post натисніть кнопку Create Shipment.

  3. У модальному вікні Create Shipment - Preview перевірте дані:

    • Sender: Дані відправника (з налаштувань модуля).
    • Recipient: Контакти та адреса/відділення отримувача.
    • Parcels & Items: Габарити, вага, склад посилки, HS-коди та вартість товарів.
    • Note: Додаткова примітка до відправлення (за потреби).
  4. Натисніть Create Shipment у кутку модального вікна.
  1. Перейдіть у розділ Sales → Orders.
  2. У колонці Nova Post Shipment у рядку відповідного замовлення натисніть Create Shipment.
  3. Перевірте дані у вікні попереднього перегляду та підтвердіть створення.


Після успішної генерації накладної в колонці **Nova Post Shipment** з'явиться її номер у вигляді активного гіперпосилання для швидкого відстеження. #### Як згенерувати супровідні документи Залежно від напрямку доставки модуль автоматично генерує необхідний пакет документів: * **Доставка в межах однієї країни або в межах ЄС**: стандартна наліпка з маркуванням та штрих-кодом у форматі 100x100 мм. * **Доставка за напрямками**: non-EU → EU та EU → non-EU: * **Label**: Стандартна маркувальна наліпка 100x100 мм. * **International Label**: Міжнародна транспортна накладна з розширеними даними. * **Invoice**: Комерційний інвойс (рахунок-фактура) для митниці. #### Як роздрукувати супровідні документи
Order ViewOrder Grid


Натисніть іконку потрібного документа безпосередньо у колонці Nova Post Shipment.


У блоці Nova Post або через меню Actions у верхній панелі натисніть іконку відповідного документа. У модальному вікні відкриється PDF-попередній перегляд із кнопками для завантаження чи друку.
#### Як дізнатись номер відправлення та відстежити посилку | **Order View** | **Order Grid** | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | Номер відправлення – це активне посилання. Клікніть на нього, щоб перейти на сторінку відстеження Nova Post із деталізацією маршруту. Мова сторінки відстеження визначається автоматично відповідно до налаштувань мови поточного подання магазину. #### Як змінити дані у експрес-накладній Якщо в замовленні потрібно змінити вагу, адресу чи склад товарів після створення ЕН, потрібно видалити поточну ЕН та згенерувати нову з потрібними даними: 1. У колонці Nova Post Shipment у переліку замовлень або у блоці Nova Post у самому замовленні натисніть іконку Смітника (Trash Can). 2. Підтвердіть дію у вікні запиту ("Are you sure you want to delete shipment..."). 3. Після видалення попереднього трек-номера система знову відобразить кнопку Create Shipment, дозволяючи згенерувати нову накладну з оновленими параметрами. #### Як надати доступ менеджеру Модуль інтегрований у рольову модель безпеки Magento. У розділі **System** → **Permissions** → **User Roles** ви можете гнучко розмежувати права для різних менеджерів: * **Create Shipment** — дозвіл на створення накладних. * **Delete Shipment** — дозвіл на видалення/скасування ЕН. * **Print Documents** — дозвіл на завантаження та друк супровідних документів. ### API Logs Усі запити та відповіді API при взаємодії з Nova Post записуються в окремий лог-файл, відокремлений від загальних логів Magento. Логи містять: * **Успішні операції** — ID замовлення, статус відповіді, номер експрес-накладної. * **Помилкові операції** — ID замовлення, деталі помилки. * Мережеві збої та перевищення часу очікування (таймаути). Модуль записує логи Nova Post у окремі файли: 1. `var/log/novapost/debug.log` 2. `var/log/novapost/error.log` Токени авторизації та конфіденційні дані автоматично видаляються з усіх записів у логах. ### Шлях покупця у Checkout Під час оформлення замовлення з доставкою Nova Post покупцю необхідно: 1. **Вказати контактні дані**: Email, ім'я, прізвище, номер телефону, країну, місто, вулицю, будинок та поштовий індекс. 2. **Вибрати спосіб доставки Nova Post**: * **Доставка у відділення / Поштомат**: Покупець натискає на інтерактивний віджет карти, вибирає зручну точку на карті або через пошук за адресою, обирає тип (відділення чи поштомат) та підтверджує вибір. * **Доставка кур'єром**: Доставка здійснюється за адресою, вказаною у контактних даних. 3. **Вказати спосіб оплати**: Онлайн-оплата або післяплата (COD). 4. **Підтвердити замовлення**.
Приклад оформлення замовлення покупцем

Крок 1

Крок 2

Крок 3

Крок 4

Після генерації накладної покупцю автоматично надсилається брендований e-mail із деталями замовлення, номером ЕН та прямим посиланням на сторінку відстеження посилки.
Приклад листа-підтвердження ![](https://4254720631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLX4zPmabmEVO7QnYqI7L%2Fuploads%2FEhm1M5yn5NUmcU3GuJtX%2Funknown.png?alt=media\&token=a41257d3-1e55-4eea-b3c3-cf90b2d65fc9)

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api-portal.novapost.com/gotovi-integraciyi/popular_integration/populyarni-integraciyi/magento.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.