sevDesk и n8n: триггер опроса, ограничения API

sevDesk можно подключить к n8n только через узел HTTP Request, поскольку в ядре n8n нет собственного узла sevDesk и, соответственно, нет веб-хук-триггера, который автоматически сообщал бы об изменениях в sevDesk рабочему процессу. Тот, кто хочет обрабатывать в n8n данные sevDesk, такие как новые счета, контакты или документы, поэтому создаёт триггер опроса (polling): узел Schedule Trigger через определённые промежутки времени запрашивает API sevDesk посредством HTTP Request и передаёт ответ остальной части рабочего процесса. Сам API sevDesk ограничивает размер страницы на один запрос максимум 1000 записями за вызов и с апреля 2025 года требует аутентификации через заголовок Authorization вместо параметра URL. Состояние на: июль 2026.

Почему веб-хук-триггер невозможен

n8n различает встроенные в ядро собственные узлы и узлы сообщества, которые устанавливаются отдельно. Для sevDesk не существует собственного узла, а значит, и готового узла-триггера, реагирующего на события в sevDesk. В официальной документации API sevDesk нигде не описан механизм веб-хуков, посредством которого sevDesk активно отправлял бы данные во внешнюю систему. На практике это означает: рабочий процесс сам по себе не узнаёт о том, что в sevDesk создан новый счёт или проведён документ. Он должен активно запрашивать, и именно это делает триггер опроса.

Структура: Schedule Trigger плюс HTTP Request

Узел Schedule Trigger Node запускает рабочий процесс через фиксированный интервал, на выбор в секундах, минутах, часах, днях или с помощью собственного cron-выражения. Сразу после этого следует HTTP Request Node, который выполняет непосредственный запрос к API sevDesk, например к эндпоинту вроде Invoice или Contact. Для этого узел HTTP Request поддерживает универсальные методы аутентификации, такие как Header Auth, а также встроенные опции пагинации, с помощью которых параметры вроде limit и offset автоматически увеличиваются при каждом вызове. Ответ поступает в рабочий процесс в формате JSON и затем может быть отфильтрован, преобразован и передан в целевые системы.

Аутентификация с помощью API-токена sevDesk

Каждый администратор sevDesk имеет API-токен, шестнадцатеричную строку из 32 символов, которую можно найти в настройках учётной записи. Согласно документации API sevDesk по аутентификации срок действия токена неограничен, и его нужно передавать в узле HTTP Request как значение заголовка Authorization. Важно для старых рабочих процессов: до апреля 2025 года токен можно было передавать и как параметр URL, однако sevDesk удалил этот способ по соображениям безопасности. Тот, кто всё ещё использует старую интеграцию с токеном в URL, должен перевести её на заголовок Authorization, иначе аутентификация завершится ошибкой.

Пагинация и документированные ограничения API

sevDesk выполняет постраничную разбивку списковых запросов с помощью параметров limit и offset. В примерах официальной документации запрос без дополнительных указаний по умолчанию возвращает до 100 записей. Согласно объявлению sevDesk о новых ограничениях пагинации sevDesk с 30 мая 2025 года дополнительно устанавливает фиксированный верхний предел: параметр limit должен быть целым числом от 1 до 1000, иначе API отвечает HTTP 400 с указанием, что допустимы только значения в этом диапазоне. Ранее можно было передавать значительно большие или даже произвольные значения. Для рабочего процесса опроса это означает: при больших объёмах данных требуется несколько запросов с увеличивающимся offset, что можно реализовать в узле HTTP Request через настройку пагинации «Update a Parameter in Each Request». Конкретных данных о количестве запросов в минуту или час документация sevDesk в этом месте не приводит, однако базовое ограничение частоты запросов существует и должно учитываться при выборе интервала опроса.

Выбор интервала и планирование затрат на обслуживание

Без веб-хука нет уведомлений в реальном времени, каждая задержка между двумя запусками по расписанию является реальной задержкой в обработке. Более короткий интервал даёт более актуальные данные, но увеличивает число вызовов API и тем самым риск достичь публично не указанных лимитов. Кроме того, сам рабочий процесс должен следить за тем, чтобы уже обработанные записи не обрабатывались повторно, например, сохраняя время последнего успешного запуска и используя его как фильтр при следующем запросе. При использовании собственного узла эту логику часто берёт на себя сам узел, а при решении на основе чистого HTTP Request её нужно встраивать в рабочий процесс и поддерживать при изменениях API, таких как два breaking changes 2025 года. Тот, кто не хочет брать на себя эти затраты, может найти поддержку в создании подобных интеграций, например, в автоматизации n8n от NordFlux или в целом в разделе автоматизация.

Часто задаваемые вопросы о sevDesk и n8n

Существует ли официальный узел sevDesk для n8n?

Нет, sevDesk не является собственным узлом в ядре n8n. Подключение выполняется через универсальный узел HTTP Request к REST API sevDesk.

Как часто Schedule Trigger должен опрашивать API sevDesk?

Это зависит от сценария использования. Для бухгалтерских процессов часто достаточно интервала от 15 до 60 минут, для критичных по времени сценариев интервал должен быть короче. Поскольку sevDesk не публикует данные о количестве запросов в минуту, рекомендуется умеренный интервал с обработкой ошибок вместо очень короткого такта.

Сколько записей возвращает API sevDesk за один запрос?

С мая 2025 года параметр limit допускает только целые значения от 1 до 1000, всё, что выходит за эти пределы, приводит к ошибке HTTP 400. Для больших объёмов данных требуется несколько запросов с увеличивающимся offset.

Работает ли ещё старая аутентификация через параметр URL?

Нет. sevDesk отключил этот механизм с 29 апреля 2025 года. С тех пор API-токен должен передаваться в заголовке Authorization каждого запроса.