Нова Пошта API — це офіційний програмний інтерфейс перевізника, через який інтернет-магазин автоматизує те, що інакше робиться руками в кабінеті: підтягує довідник міст і відділень, рахує тариф, створює електронну накладну (ТТН) із замовлення, відстежує статус посилки й оформлює накладений платіж. Розберемо, що саме дає API, де взяти ключ, і два шляхи підключення — власна інтеграція чи готовий модуль.
Головне, заради чого варто дочитати: більшість статей переказують документацію. Тут — місця, де інтеграція ламається вже після того, як «усе працює»: неправильна оголошена вартість, подвійне стягнення за доставку й накладений платіж на вже оплаченому замовленні. Кожен приклад — із реальної реалізації модуля для CommerCentr, і кожен коштував окремого виправлення.
Що вміє Нова Пошта API: пʼять задач магазину
| Задача | Метод API | Що отримує магазин |
|---|---|---|
| Довідник | Address/getCities,getWarehouses | Області, міста, відділення й поштомати з Ref-ідентифікаторами |
| Тариф | InternetDocument/getDocumentPrice | Вартість доставки за вагою й обʼємом до конкретного міста |
| Накладна | InternetDocument/save | ТТН просто із замовлення, без ручного заповнення в кабінеті |
| Трекінг | TrackingDocument/getStatusDocuments | Поточний статус посилки за номером |
| Накладений платіж | BackwardDeliveryDataу складі накладної | Гроші за товар при отриманні, переказ на рахунок відправника |
Повний перелік моделей і методів — в офіційній документації: developers.novaposhta.ua.
Де взяти ключ Нова Пошта API
Ключ видається безкоштовно в кабінеті НП — сторінка Налаштування → Безпека → Розробникам (відкриється у вашому кабінеті; потрібен вхід). Два практичні моменти, які часто пропускають:
- Ключ привʼязаний до контрагента. Накладні, створені через API, зʼявляться саме в цьому кабінеті й тарифікуються за вашим договором. Телефон відправника в запиті теж має належати цьому кабінету — чужий номер API відхилить.
- Ключ — секрет рівня пароля. Він не має світитися у фронтенді чи в URL. У модулі CommerCentr ключ зберігається зашифрованим і не повертається у HTML навіть адміністратору.
Чотири пастки, про які документація не попереджає
Документація описує поля. Вона не описує, що станеться, коли поля заповнені правильно, а модель магазину — ні. Ось найдорожчі випадки.
1. Оголошена вартість — це вартість товару, а не сума замовлення
Costу накладній — база для страхування. Спокуса підставити тудиtotalзамовлення велика: число під рукою, воно «правильне». Алеtotalмістить і доставку — і магазин починає платити перевізнику за страхування його ж власного тарифу.
Правильно: **Cost= сума товарів без доставки**. Якщо товарів на 1000 ₴, а доставки на 100 ₴, страхується 1000, а не 1100. Зворотний бік теж вартий уваги: занижена оголошена вартість робить доставку дешевшою, але при втраті НП відшкодує рівно те, що оголошено.
2. Накладений платіж — це борг клієнта магазину, і він інший
Накладений платіж передається не прапорцем, а вкладеним обʼєктомBackwardDeliveryDataзCargoType: Moneyі сумою вRedeliveryString. І сума тут — інша, ніж оголошена вартість: клієнт винен магазину повний підсумок замовлення так, як він його бачив, разом із податком і нарахованою доставкою.
| Поле | Що це | Сума для прикладу вище |
|---|---|---|
Cost | що страхуємо | 1000 ₴ (товари) |
RedeliveryString | що клієнт віддає при отриманні | 1100 ₴ (підсумок замовлення) |
Плутанина цих двох сум непомітна доти, доки посилка не загубиться або клієнт не почне рахувати.
3. Накладений платіж не має потрапляти на оплачене замовлення
Найдорожча помилка з усіх. Якщо накладений платіж вмикається лише прапорцем у налаштуваннях, він накладеться на всі накладні — включно з тими, за які вже заплатили карткою. Покупець платить двічі, і повертати це складніше, ніж не брати.
Правило, до якого доводиться дійти: прапорець лише дозволяє накладений платіж, а вмикає його стан замовлення. Дозволений стан один — «не оплачено». Не «будь-який, крім оплаченого»: інакше замовлення зі статусом «повернуто» отримає накладений платіж на повну суму, і магазин стягне гроші за те, що щойно повернув.
4. «Спосіб оплати» в накладній — не той, що обирає покупець
PaymentMethod(Cash/NonCash) у накладній означає, як відправник розраховується з перевізником за саму послугу: готівкою на відділенні чи списанням із договірного рахунку. До того, як покупець платить за товар, це поле не має стосунку. Магазин може матиNonCashза договором і водночас клієнта з оплатою при отриманні — суперечності немає.
Сусідня пастка —PayerType. Якщо там «Отримувач», а метод доставки на сайті має ненульову ціну, покупець заплатить за доставку двічі: вам на сайті й перевізнику на відділенні. Це не помилка API, це неузгодженість двох налаштувань, і зловити її можна лише свідомо.
Шлях 1: власна інтеграція, коли є розробник
API працює просто: POST-запит із JSON наapi.novaposhta.ua/v2.0/json/з полямиapiKey,modelName,calledMethod,methodProperties. Але робоча інтеграція — це не «зробити запит», а обробити реальність навколо нього. Чесна причина, чому це коштує днів, а не годин:
- Довідник не можна тягнути з API на кожен запит. У Києві сотні відділень; якщо оформлення чекає на відповідь API, покупець чекає разом із ним, а коли API недоступне — вибір відділення просто зникає. Робоче рішення: локальна копія довідника з фоновим оновленням (у модулі — щоденний крон з upsert за Ref і «гасінням» зниклих відділень).
- Помилки мають доходити до людини словами.
InternetDocument/saveвідмовляє змістовно: «Sender phone is not valid», «Не вистачає коштів». Якщо інтеграція перетворює це на «щось пішло не так», причину доведеться шукати в кабінеті НП. - Захист від подвійної накладної. Створення ТТН — незворотний зовнішній ефект: документ зʼявляється в кабінеті й тарифікується, а скасовується вручну. Подвійний клік або два менеджери в сусідніх вкладках без захисту створять дві накладні на одне замовлення.
- Перелічені значення треба звіряти.
PayerType,CargoType,ServiceTypeприймають рівно визначений набір рядків. Одруківка в конфігу не має доходити до API окремим класом помилки — значення поза переліком безпечніше відкотити на замовчуване. - Узгодженість із рештою магазину. Які пари «доставка × оплата» взагалі можливі, вирішує оформлення замовлення, а не модуль доставки. Другий перемикач про те саме дасть два джерела правди — і колись вони розійдуться.
Шлях 2: готовий модуль
Для магазинів на CommerCentr перелічене вже вирішено в модулі Нова Пошта — доставка й відділення. Межа між безкоштовним і платним тут проведена за принципом «table-stakes проти операційної економії», і назвати її варто прямо.
Безкоштовно (base):
- локальний довідник областей, міст, відділень і поштоматів із фоновим оновленням;
- вибір відділення чи поштомата на оформленні — працює навіть коли API перевізника недоступне, бо читається власна база магазину;
- живий тариф доставки в кошику.
Нова Пошта Pro:
- створення електронної накладної із замовлення й трекінг статусу посилки;
- друк наліпок 100×100 пачкою: обираєте замовлення з ТТН — отримуєте один PDF на всі, замість друку по одній у кабінеті;
- тариф з урахуванням габаритів: перевізник рахує більше з двох — фактичну вагу чи обʼємну (за чинним коефіцієнтом 250 кг/м³). Без габаритів обʼємний товар (подушки, великі коробки) на оформленні виглядає дешевшим, ніж вийде за рахунком, і різницю доплачує магазин.
Назвемо заперечення прямо: накладна й трекінг були в безкоштовній частині раніше, і в оновленні переїхали в Pro. Причина не в тому, що «стало платно» заднім числом — базовий модуль і далі закриває те, без чого магазин не може продавати: показати відділення й порахувати доставку. Платить той, у кого потік відправлень достатній, щоб автоматизація накладних і наліпок економила робочі години. Якщо у вас пʼять посилок на тиждень, накладну швидше виписати в кабінеті НП, і чесно про це сказати краще, ніж продати вам розширення.
Налаштування модуля — 21 поле у пʼяти блоках: доступ і відправник, параметри накладної, накладений платіж, вітрина, Pro. Кожне значення, що йде в API, береться з налаштувань, а не зашите в код: тип вантажу, платник доставки, спосіб розрахунку з перевізником, опис відправлення, мінімальна вага, дата відправлення. Роздрібний продавець і договірний відправник мають різні відповіді на ці питання, і правити їх оновленням модуля неправильно.
Якщо ваш магазин на OpenCart
Модулі «opencart нова пошта» існують, і питання зазвичай не в них самих, а в тому, що при оновленні ядра модулі різних авторів починають конфліктувати. Якщо ви плануєте міграцію, у CommerCentr модуль доставки — від команди платформи й оновлюється разом із нею; сам перенос магазину — окрема послуга з поетапним прийманням (розробка й міграція під ключ).
Накладений платіж і РРО: ризик-карта, не порада
Гроші за накладеним платежем приходять через перевізника, і чи потрібен у цей момент фіскальний чек — питання, де позиція податкової та судова практика розходяться. Ця стаття не є юридичною консультацією: звіряйте свій випадок із tax.gov.ua та рішеннями щодо вашої форми розрахунків; технічно фіскалізацію в CommerCentr закриває окремий модуль Checkbox.
Підсумок
Нова Пошта API закриває довідник, тариф, накладну, трекінг і накладений платіж. Власна інтеграція дає контроль, але разом із ним — відповідальність за кеш довідника, зрозумілі помилки, дублі ТТН, чесний тариф і за те, щоб оголошена вартість, накладений платіж і спосіб оплати не суперечили одне одному. Модуль Нової Пошти знімає базову частину безкоштовно, а Pro додає накладні, трекінг, друк наліпок пачкою й габаритний тариф.
Подивіться також, як влаштована доставка Укрпоштою і налаштування доставки в адмінці — щоб покупець мав вибір перевізника, а не одного.