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