Інтернет-магазин, дистриб'ютор чи виробник, який відправляє Новою поштою, рано чи пізно впирається в одну дію: менеджер вручну заходить у кабінет перевізника, копіює адресу з CRM, створює накладну, копіює номер назад. На двадцяти замовленнях на день це кілька годин. На двохстах це окрема посада. Тому питання «як підключити Нову пошту до CRM» виникає майже в усіх.
Відповідь залежить від того, яка у вас CRM. Якщо це KeyCRM чи SalesDrive, Нова пошта там вже є як готовий модуль, і ви просто вмикаєте його (про сценарій з n8n навколо KeyCRM ми окремо писали в посібнику Нова пошта і KeyCRM через n8n). Ця сторінка про інше: що робити, коли CRM або ERP ваша власна, або коли готового модуля замало. Тоді Нова пошта підключається через API 2.0 як окремий модуль системи, і нижче описано, з чого він складається, які методи потрібні, де він ламається і скільки це коштує.
Одразу про межі наших перевірок. Офіційну документацію developers.novaposhta.ua наш автоматичний інструмент 2026-11-19 відкрити не зміг: сервер Нової пошти відповів 403 (захист від автоматичних запитів). Тому ми не цитуємо таблицю статусів чи повний перелік полів з документації, а описуємо те, що перевірили живими запитами до самого API і взяли з нашої практики. Де ми не впевнені, так і написано, і перед запуском кожен пункт варто звірити з актуальною сторінкою розробників Нової пошти.
Схема: від замовлення до звірки накладеного платежу
Інтеграція працює як ланцюжок з шести кроків, і кожен має власний шматок коду та власні тести.
- Замовлення в CRM отримує статус «до відправки». Менеджер вибрав місто й відділення з довідника, вказав вагу й кількість місць.
- CRM викликає API Нової пошти й створює ТТН. Відповідь повертає номер накладної та ідентифікатор документа, які CRM зберігає в замовленні.
- За розкладом (кожні 15-30 хвилин, а вночі рідше) планувальник вибирає всі відкриті ТТН і опитує їхні статуси пачками.
- Якщо статус змінився, CRM змінює стан замовлення («відправлено», «прибуло у відділення», «отримано», «повернення») і записує подію в історію.
- Клієнту йде повідомлення у вибраному каналі: SMS, Telegram, Viber, пошта. Текст залежить від статусу: номер накладної при відправці, нагадування про відділення, запит на відгук після отримання.
- Для накладеного платежу 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 чи таблиці. Ми скажемо, чи вистачить готового модуля, чи потрібна власна інтеграція, і назвемо діапазон ціни. Записатися на консультацію.