Интернет-магазин, дистрибьютор или производитель, который отправляет Новой почтой, рано или поздно упирается в одно действие: менеджер вручную заходит в кабинет перевозчика, копирует адрес из 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. Сама интеграция Нова пошта (ТТН, статусы, наложенный платёж, сверка) обычно заметная, но не самая большая часть. Отдельная оценка возможна после просмотра вашего процесса доставки.

Давайте начнем ваш проект
Записаться на звонок