Veřejné API

Helpdesk nabízí jediné veřejné API: koncový bod GraphQL. Každá operace ve schématu je dosažitelná i mimo prohlížeč pomocí osobního přístupového tokenu (Personal Access Token, PAT).

Tato stránka je smlouva — co je stabilní, jak se ověřit, co udělují oprávnění a jakou podobu mají chyby. CLI hdmx je postavené nad ním a verzování API popisuje, jak se toto rozhraní vyvíjí.

Koncový bod

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

<subdomain> identifikuje váš účet (stejný identifikátor, s nímž se přihlašujete).
<version> je datovaná verze API, například 2026-07 — viz verzování API. Segment s verzí můžete také vynechat a volat …/backend/<subdomain>/graphql; požadavek pak obslouží nejstarší podporovaná verze a každá odpověď vám sdělí, která verze odpověděla.

Ověřování

Osobní přístupový token pošlete jako přihlašovací údaj typu Bearer:

Authorization: Bearer hdmx_<random>

PAT má dlouhou životnost (s povinnou platností do určitého data), nese oprávnění, je omezený na IP adresy a lze jej zneplatnit. Je vázaný na jeden účet: předložení tokenu na subdoméně jiného účtu je odmítnuto s HTTP 401.

Vytvoření tokenu

Tokeny si vytvářejte a spravujte sami v aplikaci pro agenty v sekci Settings → API tokens:

Klikněte na New token.
Dejte mu název, podle kterého ho později poznáte.
Zvolte platnost (nejvýše 365 dní — možnost „nikdy" neexistuje).
Nastavte zásady přístupu — zapněte přesně ty zdroje, které tento token potřebuje, pro čtení nebo pro čtení i zápis. Ve výchozím stavu není povolen žádný přístup.
Přidejte na seznam povolených alespoň jednu IP adresu nebo CIDR (povinné — viz Seznam povolených IP). Formulář za vás může doplnit vaši aktuální IP adresu.
Zkontrolujte a vytvořte. Celý token se zobrazí právě jednou — zkopírujte si ho ihned. Ukládá se pouze otisk, takže ho nelze znovu zobrazit; pokud ho ztratíte, proveďte rotaci tokenu a získejte nový.

Později můžete u tokenu upravit zásady přístupu i seznam povolených IP, provést jeho rotaci (vydat nový tajný klíč, zatímco starý ještě krátkou dobu funguje, abyste přešli bez výpadku) a zneplatnit ho. U každého tokenu vidíte, kdy a odkud byl naposledy použit, a k tomu záznam nedávné aktivity.

Oprávnění

Přístup je hrubozrnný a členěný podle rodin zdrojů. Token nese pevnou sadu oprávnění; každá operace nejvyšší úrovně jedno z nich kontroluje.

Oprávnění	Uděluje
`tickets:read`	Čtení tiketů, zpráv, konceptů, historie, příloh a reportů
`tickets:write`	Vytváření / úprava / mazání tiketů, publikování zpráv, nahrávání příloh. Zahrnuje `tickets:read`
`chat:read`	Čtení chatů, konverzací, zpráv a relací
`chat:write`	Odesílání zpráv agenta, připojení / opuštění / uzavření / znovuotevření konverzací. Zahrnuje `chat:read`
`customers:read`	Čtení záznamů zákazníků
`customers:write`	Vytváření / úprava / slučování záznamů zákazníků. Zahrnuje `customers:read`
`settings:read`	Čtení nastavení účtu (oddělení, stavy, priority, schránky — bez tajných údajů)

Pole s přihlašovacími údaji schránek (uživatelská jména, hesla a servery IMAP/SMTP) se tokenu nikdy nevracejí, bez ohledu na oprávnění — tyto tajné údaje patří vašemu poskytovateli e-mailu a zůstávají mimo dosah veřejného API.

Klasifikace chyb

Odpovědi GraphQL používají errors[].extensions.code:

Kód	Význam	HTTP
`SCOPE_DENIED`	Tokenu chybí potřebné oprávnění. `extensions.valid_values` vypisuje oprávnění, která by operaci umožnila	200
`RATE_LIMITED`	Limit požadavků pro token je vyčerpán. `extensions.retryAfter` je počet sekund do obnovení a hlavička `Retry-After` nese totéž číslo	429
`INVALID_API_TOKEN`	Token nebyl nalezen, má chybný formát nebo je z jiného důvodu nepoužitelný	200

Zneplatněné tokeny, tokeny s prošlou platností, nesoulad účtů a odmítnutí podle seznamu povolených IP jsou odmítnuty ještě před spuštěním dotazu a projeví se jako HTTP 401 bez těla GraphQL. Kód 401 u požadavku s tokenem berte jako „tento token už pro tento požadavek není platný — zkontrolujte jeho platnost, oprávnění a seznam povolených IP".

Limity požadavků

Každý požadavek s tokenem nese hlavičky:

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

Výchozí limit je 120 požadavků za minutu na token. Každý požadavek stojí 1, ať už čte, nebo zapisuje. Překročení vrátí HTTP 429 s hlavičkou Retry-After a extensions.code = "RATE_LIMITED"; slušně se chovající klient počká do okamžiku obnovení.

Seznam povolených IP

Každý svépomocí vytvořený token musí nést alespoň jednu IP adresu nebo CIDR — tokeny „z libovolné IP" neexistují. Zdrojová IP každého požadavku se porovnává se seznamem tokenu; neshoda je odmítnuta s HTTP 401 a extensions.sub_code = "ip_not_allowed".

Přijímají se IPv4, IPv6 i rozsahy CIDR. Pro jediného hostitele použijte /32 (IPv4) nebo /128 (IPv6).
Rozsahy se při uložení ověřují a normalizují.
Seznam povolených lze po vytvoření upravovat — úprava nemění tajný klíč.

Token používejte ze stabilního výstupního bodu: běhového prostředí CI, naplánované úlohy, pevného kancelářského NAT nebo vlastních serverů ve známém rozsahu IP. Uniklý token je odkudkoli mimo svůj seznam povolených k ničemu.

Aktivita tokenu

Každý ověřený požadavek, který token provede, se zaznamenává: čas, název operace, zdrojová IP, výsledek (úspěch, chyba, překročení limitu, odepřené oprávnění, zneplatnění nebo prošlá platnost) a doba odezvy. To je stopa, kterou je třeba prověřit, pokud se token chová nečekaně.

Verzování a ukončování podpory

API je verzováno datovanými verzemi YYYY-MM. Zafixujte si jednu v URL a zůstane stabilní nejméně 12 měsíců; ukončení podpory se ohlašuje přímo v komunikaci dříve, než cokoli, co používáte, zmizí. Úplné zásady najdete v části Verzování API.

Průzkum schématu

Schéma se popisuje samo: použijte standardní introspekci GraphQL proti verzovanému koncovému bodu a vygenerujte si typy nebo si rozhraní prohlédněte. Interaktivní GraphQL Playground je dostupné na …/backend/<subdomain>/playground.

Rychlý start s curl

Příklady předpokládají hostitele helpdesk.example.com, subdoménu acme, verzi 2026-07 a token v proměnné $TOKEN.

Načtení aktuálního uživatele (libovolné oprávnění)

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 } }"}'

Výpis nedávných tiketů (`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 }
  }'

Publikování veřejné odpovědi (`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"
      }
    }
  }'

Pro každodenní práci obaluje celé toto rozhraní CLI hdmx do pohodlných příkazů.

Veřejné API

Koncový bod​

Ověřování​

Vytvoření tokenu​

Oprávnění​

Klasifikace chyb​

Limity požadavků​

Seznam povolených IP​

Aktivita tokenu​

Verzování a ukončování podpory​

Průzkum schématu​

Rychlý start s curl​

Načtení aktuálního uživatele (libovolné oprávnění)​

Výpis nedávných tiketů (tickets:read)​

Publikování veřejné odpovědi (tickets:write)​