Публічний API

Хелпдеск надає один публічний API: GraphQL-ендпоінт. Кожна операція схеми доступна поза браузером за допомогою персонального токена доступу (Personal Access Token, PAT).

Ця сторінка — контракт: що є стабільним, як автентифікуватися, що надають права доступу та який вигляд мають помилки. CLI hdmx побудований на його основі, а версіонування API описує, як розвивається ця поверхня.

Ендпоінт

POST https://<your-host>/backend/<subdomain>/api/<version>/graphql

<subdomain> ідентифікує ваш обліковий запис (той самий ідентифікатор, з яким ви входите в систему).
<version> — датована версія API, наприклад 2026-07; див. версіонування API. Ви також можете пропустити сегмент версії та звертатися до …/backend/<subdomain>/graphql; тоді запит обслуговує найстаріша з версій, що підтримуються, а кожна відповідь повідомляє, яка саме версія на неї відповіла.

Автентифікація

Надсилайте персональний токен доступу як облікові дані Bearer:

Authorization: Bearer hdmx_<random>

PAT є довгоживучим (з обов'язковим терміном дії), обмеженим правами доступу, прив'язаним до IP та відкличним. Він прив'язаний до одного облікового запису: пред'явлення токена до субдомену іншого облікового запису відхиляється з HTTP 401.

Створення токена

Створюйте токени та керуйте ними самостійно в застосунку агента, у розділі Settings → API tokens:

Натисніть New token.
Дайте йому назву, за якою ви впізнаєте його згодом.
Виберіть термін дії (до 365 днів — варіанта «ніколи» немає).
Налаштуйте політику доступу — увімкніть саме ті ресурси, які потрібні цьому токену, у режимі читання або читання й запису. За замовчуванням доступу немає ні до чого.
Додайте щонайменше одну IP-адресу або CIDR до списку дозволених (обов'язково — див. Список дозволених IP). Форма може додати вашу поточну IP-адресу за вас.
Перевірте та створіть. Повний токен показується рівно один раз — скопіюйте його одразу. Зберігається лише хеш, тому показати токен повторно неможливо; якщо ви його втратили, виконайте ротацію токена, щоб отримати новий.

Згодом ви можете змінити політику доступу та список дозволених IP токена, виконати його ротацію (видати новий секрет, тоді як старий ще певний пільговий період працює, щоб ви могли перейти без простою) та відкликати його. Для кожного токена показано, коли й звідки його востаннє використовували, а також журнал останньої активності.

Права доступу (scopes)

Доступ є грубозернистим і згрупованим за родинами ресурсів. Токен несе фіксований набір прав доступу; кожна операція верхнього рівня перевіряє одне з них.

Право доступу	Що надає
`tickets:read`	Читання тікетів, повідомлень, чернеток, історії, вкладень, звітів
`tickets:write`	Створення / оновлення / видалення тікетів, публікація повідомлень, завантаження вкладень. Включає `tickets:read`
`chat:read`	Читання чатів, розмов, повідомлень, сесій
`chat:write`	Надсилання повідомлень агента, приєднання / вихід / закриття / повторне відкриття розмов. Включає `chat:read`
`customers:read`	Читання записів клієнтів
`customers:write`	Створення / оновлення / об'єднання записів клієнтів. Включає `customers:read`
`settings:read`	Читання налаштувань облікового запису (відділи, статуси, пріоритети, поштові скриньки — без секретів)

Поля облікових даних поштових скриньок (імена користувачів, паролі та хости IMAP/SMTP) ніколи не повертаються токену, незалежно від прав доступу — ці секрети належать вашому поштовому провайдеру й залишаються поза досяжністю публічного API.

Класифікація помилок

Відповіді GraphQL використовують errors[].extensions.code:

Код	Значення	HTTP
`SCOPE_DENIED`	Токену бракує потрібного права доступу. `extensions.valid_values` перелічує права, яких вистачило б для операції	200
`RATE_LIMITED`	Вичерпано ліміт запитів для токена. `extensions.retryAfter` — кількість секунд до скидання ліміту, а заголовок `Retry-After` містить те саме число	429
`INVALID_API_TOKEN`	Токен не знайдено, він має неправильний формат або є непридатним з іншої причини	200

Відкликані токени, токени з вичерпаним терміном дії, невідповідність облікового запису та відмови за списком дозволених IP відхиляються ще до виконання запиту й повертаються як HTTP 401 без тіла GraphQL. Сприймайте 401 у запиті з токеном як «цей токен більше не дійсний для цього запиту — перевірте його термін дії, права доступу та список дозволених IP».

Обмеження частоти запитів

Кожен запит із токеном отримує заголовки:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1715692800

Ліміт за замовчуванням — 120 запитів на хвилину на токен. Кожен запит коштує 1, незалежно від того, читає він чи записує. Перевищення повертає HTTP 429 із заголовком Retry-After та extensions.code = "RATE_LIMITED"; коректний клієнт чекає до моменту скидання ліміту.

Список дозволених IP

Кожен самостійно створений токен обов'язково повинен містити щонайменше одну IP-адресу або CIDR — токенів «з будь-якої IP» не існує. IP-адреса джерела кожного запиту звіряється зі списком токена; невідповідність відхиляється з HTTP 401 та extensions.sub_code = "ip_not_allowed".

Приймаються IPv4, IPv6 та діапазони CIDR. Для одного хоста використовуйте /32 (IPv4) або /128 (IPv6).
Діапазони перевіряються та нормалізуються під час збереження.
Список дозволених IP можна редагувати після створення — редагування не змінює секрет.

Використовуйте токен зі стабільної точки виходу в мережу: раннера CI, запланованого завдання, фіксованого офісного NAT або власних серверів у відомому діапазоні IP. Викрадений токен марний з будь-якого місця поза його списком дозволених IP.

Активність токена

Кожен автентифікований запит, який робить токен, записується: час, назва операції, IP-адреса джерела, результат (успіх, помилка, перевищення ліміту, відмова за правами доступу, відкликано або вичерпано термін дії) та час відповіді. Це той слід, який варто перевірити, якщо токен поводиться несподівано.

Версіонування та застарілі елементи

API версіонується датованими версіями YYYY-MM. Закріпіть версію в URL — і вона залишатиметься стабільною щонайменше 12 місяців; про застарілі елементи повідомляється безпосередньо у відповідях ще до того, як щось із того, що ви використовуєте, зникне. Повну політику див. у розділі Версіонування API.

Дослідження схеми

Схема самоописова: використовуйте стандартну інтроспекцію GraphQL до версійованого ендпоінта, щоб згенерувати типи та дослідити поверхню API. Інтерактивний GraphQL Playground доступний за адресою …/backend/<subdomain>/playground.

Швидкий старт із curl

У прикладах припускається хост helpdesk.example.com, субдомен acme, версія 2026-07 і токен у змінній $TOKEN.

Отримати поточного користувача (будь-яке право доступу)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { id email firstname lastname } }"}'

Отримати список останніх тікетів (`tickets:read`)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($first: Int!) {
      ticketList(first: $first) {
        edges { node { code subject status { name } updatedAt } }
      }
    }",
    "variables": { "first": 10 }
  }'

Опублікувати публічну відповідь (`tickets:write`)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($input: SaveTicketInput!) {
      saveTicket(input: $input) {
        ticket { code }
        error { code message }
      }
    }",
    "variables": {
      "input": {
        "id": "TICKET-UUID-HERE",
        "message": "Thanks — fixing this now.",
        "messageType": "PUBLIC"
      }
    }
  }'

Для повсякденної роботи CLI hdmx огортає всю цю поверхню в зручні команди.

Публічний API

Ендпоінт​

Автентифікація​

Створення токена​

Права доступу (scopes)​

Класифікація помилок​

Обмеження частоти запитів​

Список дозволених IP​

Активність токена​

Версіонування та застарілі елементи​

Дослідження схеми​

Швидкий старт із curl​

Отримати поточного користувача (будь-яке право доступу)​

Отримати список останніх тікетів (tickets:read)​

Опублікувати публічну відповідь (tickets:write)​