nks-osticket-plugin

Kdo chce s helpdeskem na osTicketu propojit jiný systém, zjistí rychle, že vestavěné API umí tikety přijímat, ale ne číst, hledat ani na ně odpovídat. Integrace se pak píšou přímo nad databází, což obchází logiku osTicketu, nebo se upravují soubory jádra, což se rozbije s další aktualizací. nks-osticket-plugin přidá do osTicketu jeden koncový bod s rozhraním JSON, přes který integrace i AI agenti pracují s tikety pod běžnými API klíči osTicketu, bez zásahu do jádra.

Proč nestačí, co osTicket má

Klíč v základní instalaci osTicketu má jen dvě oprávnění: zakládat tikety a spouštět cron. Doplněk k nim přidá oprávnění pro čtení, hledání, úpravy, odpovědi, mazání, statistiky a práci s podřízenými tikety a nabídne akce, které je využijí. Zápisy přitom jdou přes zdokumentované API třídy Ticket, takže vlákna, upozornění a záznamy do logu dál fungují jako při práci v administraci. Na rozdíl od přímého zápisu do databáze se tak nic neobejde a na rozdíl od úpravy jádra zůstanou soubory jádra osTicketu netknuté. Mimo vlastní adresář doplněk přidá jen vstupní soubor do api/ a výjimku do api/.htaccess. Instalační skript výjimku zapíše, jen když v souboru chybí, takže ho jde po aktualizaci osTicketu pustit znovu.

Co doplněk umí

Jedno místo pro všechny akce

Všechno jde přes POST /api/nks-osticket.php s klíčem v hlavičce X-Api-Key a tělem ve tvaru {"action": …, "params": …}. Akce pokrývají výpis, hledání, detail, založení, úpravu, odpověď a smazání tiketu, statistiky, seznam stavů, nadřazené a podřízené tikety a stažení přílohy. Akce, které jen čtou, přijmou i GET s parametry v adrese, takže jdou vyzkoušet z prohlížeče nebo z curl. Odpověď má vždy stejnou obálku: {"ok": true, "data": …}, nebo {"ok": false, "error": {"code", "message"}}.

Výpisy, které zvládnou velkou databázi

osTicket 1.18 při načítání celých objektů tiketů přes automaticky spojovaný QuerySet spouští desítky tisíc dotazů na strukturu databáze na každý řádek. Výpisy a hledání proto berou jen potřebné sloupce projekcí ORM ->values() a celé objekty nesestavují. Seznam tiketů tak zůstane použitelný i v helpdesku s dlouhou historií.

Odpovídá skutečný agent a zákazník e-mail dostane

Odpovědi a interní poznámky se zapisují jménem konkrétního agenta osTicketu (staffId, výchozí 1), takže osTicket doplní jméno, podpis, odesílatele e-mailu i automatické přidělení tiketu. Odpověď se zákazníkovi opravdu odešle, adresáty určí replyTo: všichni, jen zadavatel, nebo jen další účastníci. Od verze 1.3.0 může odpověď nést přílohy v base64; uloží se k položce vlákna a odejdou s e-mailem, pokud má osTicket přílohy v e-mailech zapnuté. Soubor nad limit velikosti z nastavení osTicketu vrátí kód 413.

Přílohy, které jde najít

Detail tiketu vrací u každé položky vlákna seznam příloh s identifikátorem, názvem, typem, velikostí, příznakem vloženého obrázku a cid, který odpovídá značkám cid: v textu zprávy. Identifikátor pak přijme akce attachments.download. Bez toho se k přílohám přes API dostat nedalo.

Podřízené tikety bez dalšího doplňku

Vazby mezi tikety využívají sloupec ticket_pid, který osTicket sám má. Doplněk umí tikety propojit, vazbu zrušit, vypsat podřízené a najít nadřazený, a nepotřebuje k tomu žádný další doplněk třetí strany.

Bezpečnost a oprávnění

Doplněk nemá vlastní přihlašování, používá API klíče z administrace osTicketu (Admin Panel, Manage, API Keys). Každý klíč je vázaný na zdrojovou IP adresu a každá akce vyžaduje svoje oprávnění. Klíč, který má jen číst statistiky, nic nezmění. Při nesouhlasu IP adresy API vrátí adresu, kterou vidělo, takže správce ví, na jakou klíč navázat.

Chybějící sloupce oprávnění doplněk přidá do tabulky ost_api_key při prvním ověřeném požadavku, všechny nastavené na 0. Administrace osTicketu je nezobrazuje, povolují se v databázi:

UPDATE ost_api_key
SET can_read_tickets = 1, can_search_tickets = 1, can_read_stats = 1
WHERE id = 2;  -- the key id, also returned by meta.ping as keyId

Odpověď 403 jmenuje chybějící oprávnění a v error.hint nese přesně ten příkaz UPDATE, který ho povolí. Když databázový uživatel nesmí tabulku měnit, vrátí API kód 500 s příkazem ALTER TABLE pro ruční spuštění.

Kde se hodí

• AI agent nad helpdeskem: doplněk je podkladem pro nks-osticket-mcp, MCP server, přes který Claude a další agenti čtou tikety a odpovídají na ně.
• Propojení s vlastním systémem: CRM nebo fakturace si dotáhne tikety zákazníka a jejich stav jedním požadavkem.
• Přehledy a hlídání: skript v cronu se ptá na zpožděné tikety přes tickets.stats a upozorní, když jich přibude.

Stav projektu

Verze 1.0.0 vyšla 5. července 2026, 1.1.0 o dva dny později přidala přílohy ve vláknu. Verze 1.2.0 z 18. srpna opravila odpovědi, které se do té doby ukládaly do vlákna, ale e-mailem neodcházely, a přidala zápis jménem agenta. Verze 1.2.1 z 23. října opravila stav, kdy na neupraveném osTicketu vracely všechny akce kromě meta.ping chybu 403, protože sloupce oprávnění neexistovaly. Poslední 1.3.0 z 28. října 2026 přidala přílohy k odpovědím. Vyvíjí se proti osTicketu 1.18, starší verze vyzkoušené nejsou. Automatické testy repozitář nemá, změny se ověřují nasazením na testovací osTicket.

Jak začít

git clone https://github.com/nks-hub/nks-osticket-plugin.git
cd nks-osticket-plugin
OSTICKET_WEB=/path/to/osticket/upload ./deploy.sh
curl -H "X-Api-Key: <your osTicket API key>" \
  "https://support.example.com/api/nks-osticket.php?action=meta.ping"

Skript deploy.sh zkopíruje kód doplňku do include/plugins/nks-osticket-api/, vstupní soubor do api/nks-osticket.php a doplní výjimku do api/.htaccess, aby požadavek nezachytil dispečer osTicketu. Soubory pak stačí předat uživateli webového serveru. Aktivace v administraci je volitelná, API funguje hned po nakopírování. Potřeba je PHP 8.0 nebo novější, přístup k webovému kořeni osTicketu a bash.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nks-osticket-plugin pod licencí MIT, napsaný v PHP. Na Packagistu balíček není, doplněk se instaluje z repozitáře. Popis změn je v CHANGELOG.md a ve vydáních na GitHubu.