REST API¶

Helpdesk Pro добавляет свои маршруты в плагин API Grav под /api/v1/helpdesk-pro/. Рабочая область сотрудников полностью построена на этих маршрутах, поэтому всё, что она делает, может делать и скрипт, и ИИ-клиент (см. MCP). Пути ниже опускают префикс /api/v1.

Аутентификация¶

Используйте любые учётные данные, которые принимает плагин API:

• Ключ API, отправляемый как X-API-Key. Создайте его в Admin Next (ваша учётная запись, затем API Keys) или на сервере через bin/plugin api keys:generate --user=<username>. Ключ, созданный со списком областей доступа, ограничен ими: выдайте ему helpdesk-pro.desk и любые другие нужные действия helpdesk-pro.*. Ключ без области рабочей области не дойдёт ни до одного маршрута Helpdesk Pro, даже если его владелец администратор.
• JWT из POST /auth/token, отправляемый как X-API-Token (так делает Admin Next).

Заявки, созданные и ответы, написанные с ключом API, записывают канал api; то же самое из Admin Next записывает staff.

curl -k "https://example.test/api/v1/helpdesk-pro/tickets?assignee=me" \
  -H "X-API-Key: $KEY"

Кто что может вызывать¶

Каждому маршруту нужен api.access плюс право из его строки (Проекты и права). api.super считается обладателем всех прав Helpdesk Pro.

Маршруты заявок, помеченные client, также отвечают учётной записи, у которой есть api.access, но нет прав Helpdesk Pro. Такая учётная запись — клиент и получает ровно то, что показал бы портал: заявки, которые он отправил или в копии которых был (и общие заявки проектов, в которых состоит), только публичные ответы и публичную активность, без заметок, меток и адресов электронной почты. Он может отвечать, отключать уведомления, отмечать своё обращение решённым и открывать его снова. Заявка, которую он не может читать, отвечает 404, как несуществующая.

Сотрудники видят заметки и внутреннюю активность заявки только в проектах, где работают. Заявка вне этих проектов для них тоже 404.

Соглашения¶

• Ответы оборачивают полезную нагрузку в data. Списки листаются через page и per_page (не более 100) и несут meta.pagination и links.
• Ошибки — problem details (application/problem+json) с status, title и detail. Ошибки проверки (422) добавляют errors: [{field, message}].
• Время — секунды epoch.
• Люди появляются как {id, name, kind}, плюс email, когда вызывающий — сотрудник по этой заявке.
• Записи отправляют заголовок X-Invalidates (helpdesk-pro:tickets, helpdesk-pro:ticket:<id>, helpdesk-pro:projects, …), чтобы Admin Next перезапрашивал изменённое.
• GET /helpdesk-pro/tickets/{id} отправляет ETag редактируемых полей заявки. Верните его как If-Match в PATCH, чтобы получить 409, когда кто-то тем временем изменил одно из этих полей. Новые ответы и заметки его не меняют. Люди и организации работают так же.

Заявка¶

Строки списка и деталь используют одну форму:

{
  "id": 1042, "subject": "Can't reset my password", "kind": "support",
  "project": {"id": 1, "slug": "support", "name": "Support"},
  "status": {"id": 2, "name": "Open", "category": "open", "color": "#22c55e"},
  "priority": 1, "visibility_scope": "requester", "channel": "email", "triage_state": "accepted",
  "requester": {"id": 55, "name": "Ada Lovelace", "kind": "client", "email": "ada@example.com"},
  "assignee": {"id": 3, "name": "Anna", "kind": "staff"},
  "labels": [{"id": 4, "name": "billing", "color": "#f59e0b"}],
  "first_message_id": 7001, "last_public_message_id": 7010,
  "counts": {"public": 3, "attachments": 2, "notes": 1},
  "times": {"created_at": 0, "last_public_at": 0, "resolved_at": null, "closed_at": null,
            "updated_at": 0, "last_activity_at": 0, "last_requester_at": 0, "last_staff_reply_at": 0,
            "first_response_at": 0, "status_changed_at": 0, "waiting_since": null},
  "me": {"watching": true, "muted": false, "unread": true},
  "duplicate_of_id": null, "merged_into_id": null, "reopen_count": 0, "deleted": false,
  "extra": {}
}

triage_state, labels, counts.notes, времена сотрудников, duplicate_of_id, merged_into_id, reopen_count и deleted есть только у сотрудников, работающих с проектом заявки. Деталь добавляет participants и etag, а timeline — когда его запросили.

extra несёт то, что прикрепляют функции и дополнения:

Хронология¶

GET /helpdesk-pro/tickets/{id}/timeline возвращает сообщения и активность вперемешку, начиная со старого:

[
  {"type": "message", "id": 7001, "ticket_id": 1042, "visibility": "public",
   "author": {"id": 55, "name": "Ada Lovelace", "kind": "client"}, "source": "email",
   "body_html": "<p>…</p>", "body_md": "…", "stripped": false, "has_original": true,
   "edited_at": null, "created_at": 0, "attachments": []},
  {"type": "activity", "id": 301, "action": "status", "actor": {"id": 3, "name": "Anna", "kind": "staff"},
   "before": {"status_id": 1, "category": "new", "name": "New"},
   "after": {"status_id": 2, "category": "open", "name": "Open"},
   "visibility": "public", "created_at": 0}
]

visibility — public для ответов и internal для заметок. body_md и has_original только для сотрудников. attachments перечисляет файлы сообщения; клиент получает только публичные файлы публичных сообщений, без api_path.

action активности — одно из created, status, priority, kind, subject, assignee, labels, project, visibility_scope, triage, merged, merged_from, participant, message_edited, message_deleted, deleted, restored, erased или fields. Клиенты видят только публичную активность: решение, закрытие, повторное открытие, отклонение и объединение.

Защита от конфликтов¶

Когда рабочая область отправляет ответ, она передаёт based_on_message_id — новейшее показанное публичное сообщение. Если существует более новое публичное сообщение (клиент написал тем временем), POST /helpdesk-pro/tickets/{id}/messages отвечает 409 и ничего не публикует:

{"status": 409, "title": "Conflict", "detail": "The conversation has new messages since you started writing",
 "code": "thread_changed", "messages": [{"type": "message", "id": 7011, "visibility": "public", "…": "…"}]}

messages содержит новые публичные сообщения в форме хронологии. Отправьте снова с force: true, чтобы всё равно опубликовать.

Маршруты¶

Рабочая область¶

Счётчики: triage — заявки, ждущие в сортировке (ноль, если у вас нет helpdesk-pro.triage); mine_needing_reply — принятые заявки, назначенные вам, в new, open или waiting_us, чьё последнее публичное сообщение пришло от клиента; unassigned — принятые заявки в этих категориях без исполнителя; by_category — живые заявки по категориям статусов.

Заявки¶

Фильтры списка, каждое значение одно или несколько через запятую:

Сортировка: updated (по умолчанию), created, priority, waiting, id или (сотрудники, при SLA) due; order — desc (по умолчанию) или asc. meta.facets считает весь отфильтрованный набор по category, assignee, project, priority, kind, label и sla; каждый фасет игнорирует собственный фильтр.

curl -k "https://example.test/api/v1/helpdesk-pro/tickets?category=new,open&assignee=me&per_page=50" -H "X-API-Key: $KEY"

Сообщения¶

visibility: public (по умолчанию) — ответ: заявитель и клиенты в копии читают его и получают по почте. visibility: internal — заметка: только сотрудники. Клиенты могут только отвечать.

curl -k -X POST https://example.test/api/v1/helpdesk-pro/tickets/1042/messages \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body": "Fixed in 2.1.3, please update.", "status_after_id": 5}'

curl -k -X POST https://example.test/api/v1/helpdesk-pro/tickets/1042/messages \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body": "Customer is on the legacy plan.", "visibility": "internal"}'

Участники¶

Люди¶

Объединение, удаление, юридические удержания и связи учётных записей — в разделе Люди и конфиденциальность.

Проекты¶

Пользовательские поля¶

Маршруты на других страницах¶

Быстрая проверка через curl¶

KEY=...   # API-ключ учётной записи сотрудника
BASE=https://example.test/api/v1/helpdesk-pro

curl -k "$BASE/bootstrap" -H "X-API-Key: $KEY"

curl -k -X POST "$BASE/tickets" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"project_id": 1, "subject": "Printer on fire", "body": "It is hot.", "requester": {"email": "ada@example.com"}}'

curl -k -X PATCH "$BASE/tickets/1" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"status_id": 2, "priority": 3}'

Связанные разделы¶

• MCP
• Расширение
• Проекты и права