Service Desk API: как связать заявки с другими системами

Кратко

API helpdesk (service desk API) — это способ для внешней программы читать, создавать и обновлять заявки без участия человека в интерфейсе. Практических путей связать систему заявок с другими сервисами обычно три: забирать и менять заявки через REST-запросы (для CRM, ботов, аналитики), принимать заявки из внешней системы через входящий вебхук (для мониторинга, форм, других сервисов) и оповещать внешние системы о событиях через исходящий вебхук (для своей аналитики, шины интеграций, чат-ботов). Ниже — какой способ выбрать под конкретную задачу.

Актуально на 23 сентября 2026 года.

Что вообще делает API service desk

У любой полноценной системы заявок API решает три разные по направлению задачи, и их легко перепутать при выборе способа интеграции:

Путаница чаще всего в том, что для «связать заявки с CRM» люди ищут один универсальный метод, а на деле это обычно комбинация: заявка создаётся входящим вебхуком с привязкой к компании из CRM, дальше её читают и обновляют через REST, а изменение статуса разлетается наружу исходящим вебхуком. Если целевая CRM — Битрикс24 и заявки уже ведутся у него на смарт-процессе, часть этой связки можно закрыть без единой строчки кода — см. Заявки техподдержки на смарт-процессе Битрикс24.

Как выбрать способ: три сценария

Сценарий 1 — читать и менять заявки из своей системы (REST)

Подходит, если у вас есть бэкенд (бот, скрипт, внутренняя CRM), который должен получать список заявок, создавать новые или отвечать в переписке по расписанию либо по событию у себя.

Типовой запрос — POST с JSON-телом и полем action, ключ передаётся в заголовке:

POST /api/admin.php
X-Api-Key: {ваш ключ}
Content-Type: application/json

{ "action": "list_tickets", "status": "new", "limit": 20 }

Ключу нужны только те права (scope), которые реально используются: отдельно чтение, отдельно запись, отдельно доступ к клиентам. Выдавать все права разом — плохая практика: если ключ утечёт, злоумышленник получит ровно то, что вы ему разрешили, не больше. Если задача — не читать заявки кодом, а просто настроить правило по событию, часто проще обойтись готовым конструктором автоматизации — см. Автоматизация поддержки клиентов.

Сценарий 2 — заявки создаёт внешняя система (входящий вебхук)

Подходит для систем мониторинга, форм на сайте, CI/CD-пайплайнов и любых сервисов, которые сами не умеют работать с REST API, но умеют отправить один POST-запрос при своём событии.

POST /api/webhook-in.php
X-Api-Key: {ключ вебхука}
Content-Type: application/json

{
  "subject": "Сервер недоступен",
  "description": "Мониторинг не получает ответ 5 минут",
  "priority": "urgent",
  "external_ref": "alert-58213"
}

Поле идемпотентности (external_ref или его аналог у вашей системы) — обязательная деталь, которую часто забывают: без него повторная отправка того же события создаёт вторую заявку-дубликат вместо обновления первой.

Сценарий 3 — оповестить другую систему о событии заявки (исходящий вебхук)

Подходит, если решение принимается не у вас в helpdesk, а в другой системе, которой нужно узнать о смене статуса, новом сообщении или новой заявке в реальном времени, не опрашивая API по расписанию.

Отличие от входящего вебхука по направлению прямо противоположное: helpdesk сам шлёт JSON на ваш HTTPS-адрес при выбранном событии, а ваша сторона обязана быстро ответить 2xx и не задерживать обработку — тяжёлую работу нужно ставить в свою очередь, а не делать синхронно внутри ответа.

Таблица: что выбрать по задаче

Как проверить, что интеграция реально работает

1. Проверьте на одном тестовом событии, а не на всём потоке сразу: создайте одну заявку через входящий вебхук и убедитесь, что она появилась именно с ожидаемыми полями (тема, приоритет, привязка к компании).
2. Повторите тот же запрос ещё раз. Если у вас настроена идемпотентность — должна вернуться та же заявка, а не создаться вторая. Если создалась вторая — вы не передаёте ключ идемпотентности.
3. Проверьте права ключа отдельно от логики. Ошибка вида «доступ запрещён» на действии, которое раньше работало, почти всегда означает не баг, а нехватку scope у ключа для конкретного действия.
4. Для исходящего вебхука посмотрите журнал доставок, а не только код ответа: сохранённые попытки с кодом и телом ответа быстрее покажут, где расходится формат данных с тем, что ожидает принимающая сторона.
5. Проверьте лимиты запросов отдельно: система, шлющая заявки массово без пауз, может упереться в ограничение частоты запросов и получить не ошибку логики, а просто отказ по лимиту.

Частые ошибки при связывании заявок с другими системами

• Пытаются одним запросом и создать заявку, и привязать компанию, используя эндпоинт, который вообще не принимает поля компании. Не любой способ создания заявки одинаков: одни идентифицируют только человека, другие — умеют находить или заводить компанию по стабильному ID. Если компания не привязывается — чаще всего дело именно в выбранном эндпоинте, а не в самих переданных данных.
• Не передают идемпотентный ключ и получают дубли заявок при повторных попытках отправки (типично при сетевых сбоях, когда клиент повторяет запрос, не убедившись, дошёл ли первый).
• Хранят ключ доступа на стороне браузера или в клиентском коде. Ключ — серверный секрет; вызовы с ним должны идти сервер-сервер, а не из JavaScript в браузере пользователя.
• Ожидают повторных попыток доставки от исходящего вебхука, хотя движок делает только одну синхронную попытку — если принимающая сторона не ответила вовремя, нужно самостоятельно инициировать повтор события, а не ждать автоматики.
• Выдают ключу все права сразу «на всякий случай» вместо минимально необходимых для конкретной интеграции.

Как это устроено в TehProf.kz Support

TehProf.kz Support даёт все три направления как отдельные независимые механизмы, без обязательного программирования на стороне интегратора:

Доступность и лимиты у каждого механизма разные по тарифу: например, исходящие вебхуки недоступны на младших тарифах и ограничены по числу на тарифе Business. Подробный формат запросов и полный список действий — в статье про серверную интеграцию (Серверная API-интеграция) и в справочнике API-ключей.

Частые вопросы

В чём разница между REST API и вебхуком для заявок?

REST-запрос инициируете вы сами, когда вам нужно прочитать или изменить данные. Вебхук работает в обратную сторону: либо внешняя система сама создаёт заявку одним запросом (входящий), либо helpdesk сам уведомляет вас о событии без вашего опроса (исходящий).

Как привязать заявку из другой системы к нужной компании?

Передавайте стабильный внешний идентификатор компании (например, company_external_id) вместе с данными заявки через входящий вебхук — компания находится или создаётся по этому ключу автоматически, без ручной сверки.

Что делать, если при повторной отправке создаётся вторая заявка вместо одной?

Добавьте в запрос ключ идемпотентности (стабильный номер вашей заявки/события). Повторный запрос с тем же ключом должен вернуть уже существующую заявку, а не создать дубликат.

Нужно ли писать сервер, чтобы связать заявки с CRM через API?

Для REST-запросов и вебхуков — да, нужен серверный код, который держит ключ доступа в секрете и не передаёт его в браузер. Без разработки можно ограничиться готовыми интеграциями конкретных систем, если они существуют.

Как проверить, что исходящий вебхук реально дошёл до моей системы?

Посмотрите журнал доставок на стороне helpdesk: там сохраняется код ответа, ошибка (если была) и время каждой попытки. Совпадение кода 2xx с реальным приёмом события на вашей стороне подтверждает, что интеграция работает.

Связанные статьи

• Серверная API-интеграция
• Автоматизация поддержки клиентов: что автоматизировать
• Подключение MCP для AI-клиентов
• API и ключи интеграций
• Входящие вебхуки
• Исходящие вебхуки