Інтернет-магазин, дистриб'ютор чи виробник, який відправляє Новою поштою, рано чи пізно впирається в одну дію: менеджер вручну заходить у кабінет перевізника, копіює адресу з CRM, створює накладну, копіює номер назад. На двадцяти замовленнях на день це кілька годин. На двохстах це окрема посада. Тому питання «як підключити Нову пошту до CRM» виникає майже в усіх.

Відповідь залежить від того, яка у вас CRM. Якщо це KeyCRM чи SalesDrive, Нова пошта там вже є як готовий модуль, і ви просто вмикаєте його (про сценарій з n8n навколо KeyCRM ми окремо писали в посібнику Нова пошта і KeyCRM через n8n). Ця сторінка про інше: що робити, коли CRM або ERP ваша власна, або коли готового модуля замало. Тоді Нова пошта підключається через API 2.0 як окремий модуль системи, і нижче описано, з чого він складається, які методи потрібні, де він ламається і скільки це коштує.

Одразу про межі наших перевірок. Офіційну документацію developers.novaposhta.ua наш автоматичний інструмент 2026-11-19 відкрити не зміг: сервер Нової пошти відповів 403 (захист від автоматичних запитів). Тому ми не цитуємо таблицю статусів чи повний перелік полів з документації, а описуємо те, що перевірили живими запитами до самого API і взяли з нашої практики. Де ми не впевнені, так і написано, і перед запуском кожен пункт варто звірити з актуальною сторінкою розробників Нової пошти.

Схема: від замовлення до звірки накладеного платежу

Інтеграція працює як ланцюжок з шести кроків, і кожен має власний шматок коду та власні тести.

  1. Замовлення в CRM отримує статус «до відправки». Менеджер вибрав місто й відділення з довідника, вказав вагу й кількість місць.
  2. CRM викликає API Нової пошти й створює ТТН. Відповідь повертає номер накладної та ідентифікатор документа, які CRM зберігає в замовленні.
  3. За розкладом (кожні 15-30 хвилин, а вночі рідше) планувальник вибирає всі відкриті ТТН і опитує їхні статуси пачками.
  4. Якщо статус змінився, CRM змінює стан замовлення («відправлено», «прибуло у відділення», «отримано», «повернення») і записує подію в історію.
  5. Клієнту йде повідомлення у вибраному каналі: SMS, Telegram, Viber, пошта. Текст залежить від статусу: номер накладної при відправці, нагадування про відділення, запит на відгук після отримання.
  6. Для накладеного платежу CRM зберігає очікувану суму й після виплати від перевізника звіряє її з реєстром. Розбіжності потрапляють менеджеру на окремий екран.

Такий розподіл важливий, бо кожен крок може впасти окремо. Якщо API Нової пошти тимчасово недоступне, замовлення не зникає: воно залишається зі статусом «очікує створення ТТН», і система повторить спробу. Якщо клієнтові не дійшло повідомлення, це не заважає оновленню статусу. Ми будуємо кожну інтеграцію за окремим інтерфейсом з тестовою реалізацією, тож весь процес можна прогнати на демо ще до підключення справжнього ключа. Так само ми працюємо і в інших проєктах: у CRM для квіткового сервісу в Києві виклик кур'єра Uklon Delivery і статуси від нього рухають замовлення за тією ж логікою.

Які методи API потрібні і як виглядає запит

API Нової пошти 2.0 має єдину точку входу: POST на https://api.novaposhta.ua/v2.0/json/. У тілі чотири поля: apiKey, modelName, calledMethod і methodProperties. Ключ створюють в особистому кабінеті Нової пошти в налаштуваннях API 2.0. Увесь модуль складається з викликів одного формату, відрізняються лише модель, метод і властивості. Це перевірено живими запитами 2026-11-19.

Для CRM знадобиться невеликий набір методів.

Довідники адрес: Address/getCities, Address/getWarehouses і пов'язані методи. Їх викликають для форми замовлення й для перевірки збережених адрес. Ми перевіряли Address/getWarehouses на відділенні №1 у Києві, він працює без ключа й повертає ідентифікатор міста (CityRef), потрібний для створення накладної.

Контрагенти: Counterparty/save створює отримувача й повертає ідентифікатори отримувача та його контактної особи. Цей метод ми описуємо за документацією, яку знаємо, але з бойовим ключем не запускали.

Створення накладної: InternetDocument/save. Метод вимагає посилання (Ref) на відправника, його адресу й контакт, а також на отримувача, його місто, відділення й контактну особу, плюс параметри посилки: вагу, кількість місць, тип вантажу, тип доставки, платника й спосіб оплати, опис. Для неоплаченого замовлення додають об'єкт зворотної доставки BackwardDeliveryData із сумою накладеного платежу. У відповіді приходить номер ТТН (IntDocNumber) і ідентифікатор (Ref). Склад полів ми звіряли з робочим інтеграційним тестом відкритої PHP-бібліотеки для API Нової пошти та власним досвідом, а не з офіційною сторінкою, яку не змогли відкрити.

Список документів: InternetDocument/getDocumentList повертає накладні за період. Його використовують для перевірки, чи не створено вже ТТН із таким номером замовлення, перш ніж повторювати запит після збою.

Статуси: TrackingDocument/getStatusDocuments. Метод приймає масив пар «номер ТТН і телефон отримувача» й повертає код статусу (StatusCode) та його текст (Status). Ліміт на один запит, який ми перевірили живим викликом 2026-11-19: 100 документів. На сто першому API відповідає помилкою про максимум 100 елементів.

Усі відповіді мають поле success. Якщо воно false, масив errors містить текст причини, і саме його CRM має показати менеджерові, а не ховати.

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

Типові помилки і як їх уникнути

Більшість проблем інтеграції Нової пошти не технічні. Вони виростають із даних і з повторів.

Помилки адрес. Менеджер вписав «Київ, відділення 5» текстом, а API чекає ідентифікатор міста й відділення. Рішення: не дозволяти вільний текст. У формі замовлення місто й відділення вибирають із довідника, а в базі зберігають їхні Ref. Тоді CRM ніколи не надсилає адресу, якої не існує. Окрема робота: довідник змінюється (відділення закриваються й перенумеровуються), тож збережені ідентифікатори у відкритих замовленнях перевіряють перед створенням ТТН.

Дублі накладних. Вебхук від сайту чи маркетплейсу прийшов двічі, або менеджер двічі натиснув кнопку, або перший запит дійшов, а відповідь загубилася. У всіх трьох випадках повторний InternetDocument/save створить другу накладну, за яку перевізник виставить рахунок. Захист складається з двох частин: CRM перед створенням дивиться, чи в замовленні вже є номер ТТН, і навіть після таймауту перевіряє список документів за номером замовлення, перш ніж повторювати.

Відхилений документ. Телефон не в тому форматі, не заповнене обов'язкове поле, вага нульова. API повертає success: false і текст помилок. Погана практика: нічого не робити й чекати, що хтось помітить. Хороша: замовлення отримує статус «помилка ТТН», а менеджер бачить текст причини на екрані й виправляє дані. Мовчазні збої гірші за гучні.

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

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

Статуси без нормалізації. Нова пошта повертає десятки кодів, а бізнесові потрібно п'ять-сім станів. У CRM коди зіставляють зі своїми станами в одному місці коду. Значення кодів ми з офіційної таблиці не звіряли, бо документація закрита, тому у вашому проєкті цю таблицю варто перевірити на тестових відправленнях: послати посилку, подивитися код на кожному етапі, записати. Нормалізація в одному масиві дозволяє змінити значення за хвилину.

Повернення. Посилка не забрана й повертається відправнику: це окремий стан замовлення з власною логікою (повернути на склад, скасувати оплату, надіслати клієнтові повідомлення чи пропозицію повторної доставки). Його варто закласти одразу, бо на старті їх мало, а через рік вони складають відчутну частину операційної роботи.

Готовий модуль чи власна інтеграція

Для типового інтернет-магазину готовий модуль зазвичай вигідніший. За даними постачальників, KeyCRM підтримує Нову пошту, Укрпошту, Meest Express, Rozetka Delivery та інші служби, SalesDrive працює з Новою поштою, Укрпоштою, Rozetka Delivery і Meest (перевірено 2026-11-19 на сторінках постачальників, дивіться порівняння цін і можливостей у посібнику CRM на замовлення чи готова CRM). Ви платите передбачувану щомісячну суму, нічого не пишете й отримуєте підтримку.

Власна інтеграція виправдана в чотирьох випадках.

Перший, сама CRM власна. Тоді модуль Нової пошти це частина системи, і він має бути зроблений правильно, з тестовою реалізацією й повторами.

Другий, складні правила створення ТТН. Кілька місць для одного замовлення з різною вагою, нестандартні послуги, прив'язка ТТН до виробничого завдання чи до партії складу, повернення з автоматичним рухом залишків. Готовий модуль зазвичай уміє стандартний шлях і потребує обхідних рішень для решти. Як це поєднується зі складом, описано в посібнику облік замовлень і складу.

Третій, великі обсяги. Коли відправок сотні на день, економія кількох хвилин на кожній і власні екрани для пакувальників окупають розробку.

Четвертий, кілька служб доставки в одному інтерфейсі, з єдиною моделлю статусів. Нова пошта, Укрпошта, власні кур'єри й Uklon Delivery в одній стрічці. Тоді кожна служба має власний модуль за спільним інтерфейсом, і додати наступну можна, не чіпаючи решти.

Проміжний варіант, якщо модуль у вашій CRM вже є, але бракує тільки сповіщень чи нестандартних дій: невеликий сценарій на n8n навколо готової CRM, як у посібнику Нова пошта і KeyCRM через n8n. Це дешевше за власну розробку, поки вимоги прості. А як сценарії обробки заявок із сайту поєднуються з CRM, показано в посібнику заявки з сайту в CRM і Telegram через n8n.

Що треба підготувати до початку

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

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

Ми будуємо такі інтеграції в CRM на Symfony і React; мінімальний проєкт у нас коштує від 10 000 USD, а повноцінна CRM/ERP 40 000-90 000 USD, і Нова пошта входить до них як модуль. Як формується ціна за модулями, розібрано в посібнику скільки коштує розробити CRM. Повна сторінка послуги: розробка CRM та ERP на замовлення.

Огляд підготував Антон Литвинов, засновник Lytvynov Production. Формат запиту й ліміт статусів перевірено живими запитами до API 2026-11-19; офіційну документацію developers.novaposhta.ua наш автоматичний інструмент відкрити не зміг (відповідь 403), тому деталі полів звіряйте з актуальною сторінкою.

Наступний крок

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

Наші гайди про ШІ та розробку вгорі вашого Google?

Додайте Lytvynov Production як бажане джерело, і Google показуватиме наші нові гайди про ШІ-агентів, вартість MVP і розробку на замовлення вище у видачі.

Кейси

Часті запитання

Для створення ТТН потрібен ключ API з особистого кабінету клієнта Нової пошти, тобто ви маєте бути її клієнтом з відповідним договором, який визначає тарифи, накладений платіж і умови. Це юридичний бік, і його ми не підміняємо: ключ і дані відправника належать вашій компанії, а в CRM лежать у захищених змінних середовища. Актуальні вимоги перевіряйте на сторінці розробників Нової пошти.

Метод TrackingDocument/getStatusDocuments приймає масив документів, і на момент нашої перевірки 2026-11-19 ліміт становив 100 відправлень за запит: на сто першому API повертав помилку про максимум 100 елементів. Тому CRM групує ТТН по сто й опитує їх за розкладом, а не по одному. Перед запуском перевірте ліміт ще раз, бо він може змінитися.

Під час створення ТТН для неоплаченого замовлення передають дані зворотної доставки з сумою накладеного платежу. Далі CRM зберігає цю суму як очікувану оплату, а коли Нова пошта виплачує кошти, звіряє їх з реєстром за номером ТТН. Розбіжності (клієнт відмовився, посилка повернулась, сума нижча) потрапляють у список для менеджера, а не губляться.

Не дозволяти вільний текст. У формі замовлення місто й відділення вибирають із довідника Нової пошти (методи Address), а в замовленні зберігають їхні ідентифікатори, а не рядок. Тоді типові помилки «відділення не знайдено» зникають, бо CRM ніколи не відправляє в API адресу, якої там немає. Для адресної доставки так само потрібні вулиця й будинок із довідника.

Якщо ви продаєте через сайт, Prom і Rozetka й відправляєте стандартними посилками, готовий модуль дешевший, і ми радимо брати його. Власна інтеграція виправдана, коли ТТН створюється зі складних правил (кілька місць, нестандартні послуги, повернення, прив'язка до виробництва), коли відправок багато й потрібен свій інтерфейс, або коли CRM у вас теж власна.

Як частина проєкту CRM чи ERP у Lytvynov Production вона входить у загальний бюджет: мінімальний проєкт коштує від 10 000 USD, повноцінна CRM/ERP 40 000-90 000 USD. Сама інтеграція Нової пошти (ТТН, статуси, накладений платіж, звірка) зазвичай є помітною, але не найбільшою частиною. Окрема оцінка можлива після огляду вашого процесу доставки.

Почнімо ваш проєкт
Записатися на дзвінок