В любом виде интеграции настоятельно рекомендуется настроить ее так, чтобы одна система была ведущей, а вторая ведомой. Это нужно для того, чтобы избежать конфликтных ситуаций между системами и возможных неконсистенций.
Интеграция с внешними системами может быть реализована посредством вебхуков на определенные API ендпоинты.
Для корректной обе системы должны хранить метаданные сущностей внешней системы. Например, ID заявки во внешней системе. Ниже будет представлен пример интеграции Swarmica со сторонним Helpdesk.
Схема взаимодействия:
Конечный пользователь → внешний Helpdesk → API → Swarmica
Конечный пользователь работает только во внешнем Helpdesk и может вообще не знать о существовании Swarmica.
Для подобного взаимодействия необходимо настроить во внешнем Helpdesk вебхуки, которые будут посылать API запросы в Swarmica в зависимости от событий происходящих во внешнем Helpdesk.
Для всех API запросов в Swarmica используются Headers в зависимости от вида токена.
для Bearer токена:
{
"Content-Type": "application/json",
"Authorization": "Bearer BEARER_TOKEN"
}
для API token:
{
"Content-Type": "application/json",
"Authorization": "Token API_TOKEN"
}
Сценарии взаимодействия
Сценарий 1: Создание тикета в Swarmica
На стороне внешнего Helpdesk должен быть настроен вебхук, который при определенных условиях(например создание заявки во внешнем Helpdesk) шлет в Swarmica API запрос на создание заявки.
Параметры API запроса в Swarmica:
Endpoint: /api/tickets/
Method: POST
Payload:
{
"subject": "test API ticket 11111", # тема заявки
"comment": "Comment 1", # Описание проблемы
"ext_id": 12345, # ID заявки во внешнем Helpdesk
"requester_email": "jdoe@example.tld", # email заявителя
"idempotency_key": "12345678" # ключ идемпотентности
}
При успешном запросе возвращается подобный ответ(response):
response_text='{"id":56,"subject":"test API ticket 11111","ext_id":12345,"requester":"j9m7sRnuAHFcWD9Q","assignee":null,"group":null,"status":"OPEN","until":null,"priority":"normal","replies":1,"reopens":0,"created_at":"2026-08-20T08:10:00.432419Z","resolved_at":null,"updated_at":"2026-08-20T08:10:00.547359Z","is_fcr":false,"satisfaction_score":"UNOFFERED","custom_fields":[{"uid":"1KZHEyoEPQhaD0Ii","name":{"en":"Can grant access to environment","ru":"Могу дать доступ, если надо"},"mandatory_for":[],"value":null},{"uid":"ouVl3K0SUvirO-LR","name":{"en":"link","ru":"ссылка"},"mandatory_for":[],"value":null},{"uid":"UJB6rUrOwq0Oarjt","name":{"en":"text 1","ru":"текст 1"},"mandatory_for":[],"value":null},{"uid":"Kd6ln4rmOpbVcmxd","name":{"en":"text 2","ru":"текст 2"},"mandatory_for":[],"value":null}],"platform":null,"product":null,"version":null,"edition":null,"ticketsla":{"ticket":56,"policy":"kjmiYksE1_KY0G-2","schedule":"H51qT1YSgKkq5T48","first_response_time":{"target":"08:00:00.000000","diff":"07:59:59.920475","value":"00:00:00.079525","is_running":true,"out_of_schedule":false,"breach_idx":2.761284722208046e-06},"full_resolution_time":null,"next_response_time":null,"agent_update_time":null,"support_resolution_time":null,"customer_wait_time":null,"sla_breach_idx":2.761284722208046e-06},"comment":null,"license":null,"organization":null,"ticket_session":null,"forked_from":null,"tz_offset_minutes":0,"locked":false,"time_spent":null,"time_estimate":null,"article_not_needed":false,"article_links":0,"channels":[{"uid":"4tzzvd-_6OBOggZB","channel":"jEcHl-ZdUbBhSLnD","channel_type":"EMAIL","name":"main mail channel","identity":"AftZP8cnT2IZmnxM","ext_id":"angry_dm@bk.ru","muted":false}],"source":"jEcHl-ZdUbBhSLnD","last_reply_by":"7Cf0WL7sanTeMRIF","last_reply_at":"2026-08-20T08:10:00.536283Z","issue_count":0,"last_comment_by":"7Cf0WL7sanTeMRIF","last_comment_at":"2026-08-20T08:10:00.536283Z","cc":[],"issues":[],"is_external":false,"parent_ticket":null,"locale":"ru"}'
Из этого ответа надо взять id заявки в целевой системе(Swarmica) и сохранить для дальнейших взаимодействий.
Сценарий 2: Обновление существующего тикета через API
По аналогии с предыдущим сценарием необходимо настроить вебхуки, которые будут обновлять тикет в Swarmica в зависимости от событий в исходном тикете. Для примера мы возьмем следующие события:
Добавление комментария в заявке на стороне внешнего Helpdesk
Параметры API запроса в Swarmica:
Endpoint: /api/tickets/{ID}/comments
здесь вместо ID надо вставить ID заявки в Swarmica, полученный при создании заявки(Сценарий 1)
Method: POST
Payload:
{
"body": "added comment",
"public": true
}
пример ответа(response):
{"id":205,"ext_id":null,"ticket":56,"author":"7Cf0WL7sanTeMRIF","is_staff":true,"created_at":"2026-08-20T08:59:28.262866Z","public":true,"pinned":false,"body":"added comment","sensitive_data":null,"attachments":[],"mentioned_users":[],"mentioned_groups":[],"is_system":false,"is_autocomment":false,"timelog_date":null,"time_spent":null,"sync_statuses":[],"quoted_comment":null,"deleted":false,"is_ai_generated":false,"ai_agent_links":[]}
Обновление тикета(статус, приоритет)
Endpoint: /api/tickets/{ID}/
здесь вместо ID надо вставить ID заявки в Swarmica, полученный при создании заявки(Сценарий 1)
Method: PATCH
Payload:
{
"priority": "high",
"status": "PENDING"
}
пример ответа(response):
{"id":56,"subject":"test API ticket 11111","ext_id":1,"requester":"j9m7sRnuAHFcWD9Q","assignee":null,"group":null,"status":"PENDING","until":null,"priority":"high","replies":4,"reopens":0,"created_at":"2026-08-20T08:10:00.432419Z","resolved_at":null,"updated_at":"2026-08-20T10:13:11.495034Z","is_fcr":false,"satisfaction_score":"UNOFFERED","custom_fields":[{"uid":"1KZHEyoEPQhaD0Ii","name":{"en":"Can grant access to environment","ru":"Могу дать доступ, если надо"},"mandatory_for":[],"value":null},{"uid":"ouVl3K0SUvirO-LR","name":{"en":"link","ru":"ссылка"},"mandatory_for":[],"value":null},{"uid":"UJB6rUrOwq0Oarjt","name":{"en":"text 1","ru":"текст 1"},"mandatory_for":[],"value":null},{"uid":"Kd6ln4rmOpbVcmxd","name":{"en":"text 2","ru":"текст 2"},"mandatory_for":[],"value":null},{"uid":"VJ8qi-vdMKR0Z7qc","name":{"en":"external ID","ru":"Внешний ID"},"mandatory_for":["ticket"],"value":null}],"platform":null,"product":null,"version":null,"edition":null,"ticketsla":{"ticket":56,"policy":"kjmiYksE1_KY0G-2","schedule":"H51qT1YSgKkq5T48","first_response_time":{"target":"02:00:00.000000","diff":"07:59:59.888136","value":"00:00:00.111864","is_running":false,"out_of_schedule":false,"breach_idx":0.0},"full_resolution_time":{"target":"7 00:00:00.000000","diff":null,"value":null,"is_running":false,"out_of_schedule":false,"breach_idx":0.0},"next_response_time":null,"agent_update_time":null,"support_resolution_time":null,"customer_wait_time":null,"sla_breach_idx":0.0},"comment":null,"license":null,"organization":null,"ticket_session":null,"forked_from":null,"tz_offset_minutes":0,"locked":false,"time_spent":null,"time_estimate":null,"article_not_needed":false,"article_links":0,"channels":[{"uid":"4tzzvd-_6OBOggZB","channel":"jEcHl-ZdUbBhSLnD","channel_type":"EMAIL","name":"main mail channel","identity":"AftZP8cnT2IZmnxM","ext_id":"angry_dm@bk.ru","muted":false}],"source":"jEcHl-ZdUbBhSLnD","last_reply_by":"7Cf0WL7sanTeMRIF","last_reply_at":"2026-08-20T10:06:45.406992Z","issue_count":0,"last_comment_by":"7Cf0WL7sanTeMRIF","last_comment_at":"2026-08-20T10:06:45.406992Z","cc":[],"issues":[],"is_external":false,"parent_ticket":null,"locale":"ru"}
Сценарий 3: Исходящий API запрос из Swarmica во внешнем Helpdesk при появлении комментария или изменении в
Здесь мы зависим от ендпоинта на внесение изменений для конкретной заявки внешнего Helpdesk. Такой ендпоинт для изменения конкретной заявки может:
1 - (Чаще всего) содержать ID заявки в самом ендпоинте. Например, как в Swarmica - /api/tickets/{ID}
2 - (Очень редко) не содержать ID заявки в самом ендпоинте. И ID заявки передается в payload'е API запроса.
В случае 1, в Swarmica необходимо создать действие по событию(Скрипт). В скрипте должен формироваться нужный URL ендпоинта, используя ext_id. Далее посылается соответствующий API запрос с необходимыми headers и payload.
В случае 2, мы используем действие по событию(Вебхук). В настройках вебхука в payload формируем нужные данные с помощью jinja2
