Znuny REST API – Konfiguration, Endpoints & Beispiele

Znuny Web Services – REST API

In diesem Guide: Znuny REST API (Generic Interface) aktivieren, authentifizieren und in eigene Anwendungen oder KI-Automatisierung einbinden.

Verwandte Themen: Web Services · Znuny Docker · Add-ons & Plugins · OpenTicketAI für Znuny

Die Znuny REST API ist Teil des Generic Interface und die zentrale Schnittstelle für Automatisierung, Monitoring-Anbindungen, Self-Service-Portale und KI-Lösungen wie OpenTicketAI. Kommunikation läuft über HTTP(S) mit JSON.

:::tip KI-Automatisierung statt manueller REST-Integration? Wer Tickets nicht nur per API anlegen, sondern automatisch klassifizieren und routen möchte, nutzt die OpenTicketAI Runtime — On-Premise per Docker, Anbindung über dieselbe REST API. Abschnitt 8 unten. :::

1. Architektur & Grundprinzipien

Znuny stellt das Generic Interface über REST- und SOAP-Webservices bereit. Die REST API ermöglicht:

• Ticket-Verwaltung — Erstellen, Abrufen, Ändern, Löschen
• Artikel-Verwaltung — Artikel und Anhänge
• Historie & Suche — Ticket-Verlauf und Filter-Suche

Wichtig: Eine Standardinstallation enthält keine vorkonfigurierten Webservices. Legen Sie diese im Admin-Bereich unter Prozesse & Automation → Web Services an.

2. Konfiguration

2.1 Generic Interface aktivieren

1. SysConfig → GenericInterface.Transport → REST (HTTP) auswählen.
2. Unter AdminGenericInterfaceTransportHTTPREST Timeouts, Host-Header und Debug-Level setzen.
3. In GenericInterface.Operation Operationen anlegen (z. B. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) und aktivieren.

2.2 Basis-URL & Authentifizierung

• Basis-URL (Pfad je nach Installation anpassen):

  https://IHR-SERVER/znuny/nph-genericinterface.pl/Webservice/<IhrServiceName>/

  Manche Installationen nutzen /otrs/ statt /znuny/ — prüfen Sie die URL in der Webservice-Konfiguration.

• Authentifizierung

  • Znuny-Session (SessionID) oder UserLogin + Password
  • API-Keys / Token (über SysConfig und Requester-Konfiguration)
  • Immer HTTPS in Produktion

2.3 Webservice anlegen (Kurzablauf)

1. Admin → Web Services → Add Web Service
2. Provider REST mit gewünschten Operationen definieren
3. Requester für ausgehende Aufrufe optional konfigurieren
4. Service speichern und Debugger bei Problemen nutzen

Details zum Generic Interface: Web Services.

3. Endpunkte & HTTP-Methoden

Alle URLs folgen dem Muster /Webservice/<ServiceName>/<OperationName>. Parameter und Antworten liegen typisch im JSON-Feld Data.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate · Methode: POST

Legt ein Ticket an und erstellt den ersten Artikel.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Session-ID oder UserLogin+Password
UserLogin	String	Ja²	Agenten-Login
Password	String	Ja²	Passwort
Ticket.Title	String	Ja	Betreff
Ticket.Queue	String	Ja	Queue-Name oder QueueID
Ticket.State	String	Ja	z. B. new
Ticket.Priority	String	Ja	z. B. 3 normal
Ticket.CustomerUser	String	Ja	Kunden-E-Mail oder Login
Article.Subject	String	Ja	Betreff des ersten Artikels
Article.Body	String	Ja	Inhalt
Article.MimeType	String	Ja	text/plain oder text/html

¹ SessionID oder UserLogin+Password. ² Wenn keine SessionID.

Beispiel Request:

POST /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketCreate HTTP/1.1
Host: znuny.example.com
Content-Type: application/json

{
  "UserLogin": "agent",
  "Password": "geheim",
  "Ticket": {
    "Title": "Server nicht erreichbar",
    "Queue": "Support",
    "State": "new",
    "Priority": "3 normal",
    "CustomerUser": "kunde@example.com"
  },
  "Article": {
    "Subject": "Initialer Bericht",
    "Body": "Der Server antwortet seit 08:00 nicht.",
    "MimeType": "text/plain"
  }
}

Beispiel Antwort:

{
  "TicketID": "12345",
  "ArticleID": "67890",
  "Error": {
    "ErrorCode": "",
    "ErrorMessage": ""
  }
}

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch · Methode: GET oder POST (je nach Mapping)

Parameter	Typ	Pflicht	Beschreibung
UserLogin	String	Ja¹	Mit Password oder SessionID
Password	String	Ja¹
SessionID	Integer	Ja¹
Title	String	Nein	Wildcard, z. B. %Server%
QueueIDs	Integer[]	Nein	Queue-IDs
States	String[]	Nein	new, open, …
Limit	Integer	Nein	Max. Treffer

Beispiel Request (GET, Parameter URL-encoded):

GET /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketSearch?UserLogin=agent&Password=geheim&Title=%Server% HTTP/1.1
Host: znuny.example.com

Beispiel Antwort:

{
  "TicketID": ["12345", "12346"],
  "Error": {
    "ErrorCode": "",
    "ErrorMessage": ""
  }
}

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet

Ruft Ticket-Details inkl. Artikel und optional Dynamische Felder ab. Wichtige Parameter: TicketID, AllArticles, Attachments, DynamicFields.

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate

Aktualisiert Ticket-Felder und kann einen neuen Artikel anlegen. Parameter: TicketID, Ticket.State, Ticket.Queue, Article.Body, Dynamische Felder.

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete

Löscht Ticket(s) endgültig. Parameter: TicketID (String oder Array).

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet

Historie für eine oder mehrere TicketIDs.

4. Fehlerbehandlung & Debugging

• Antworten enthalten oft Error.ErrorCode und Error.ErrorMessage
• Im Webservice-Debugger Debug-Level auf Debug setzen für detaillierte Logs in der Datenbank
• Bei 401/403: Credentials, Requester-Mapping und HTTPS prüfen

5. Anwendungsfälle

Szenario	Beschreibung
Monitoring	Tickets aus Nagios, Zabbix, Prometheus
CRM-Sync	Felder und Status aus externem CRM
Self-Service	Kundenportal legt Tickets per REST an
KI-Routing	OpenTicketAI liest und schreibt per REST

6. Python-Client: OpenTicketAI znuny

Für Python-Entwickler: typisierter Client znuny mit Modellen für TicketCreate, Search, Update. Vollständige Anleitung: OpenTicketAI Znuny Python SDK.

pip install znuny

from znuny import BasicAuth, ClientConfig, TicketOperation, ZnunyClient
from znuny import Article, Ticket, TicketCreate

client = ZnunyClient(
    ClientConfig(
        base_url="https://znuny.example.com",
        webservice_name="MyWebservice",
        operation_url_map={
            TicketOperation.CREATE: "ticket-create",
            TicketOperation.GET: "ticket-get",
            TicketOperation.SEARCH: "ticket-search",
            TicketOperation.UPDATE: "ticket-update",
        },
    )
)
client.login(BasicAuth(user_login="agent", password="geheim"))

response = client.create_ticket(
    TicketCreate(
        Ticket=Ticket(
            Title="Server nicht erreichbar",
            Queue="Support",
            State="new",
            Priority="3 normal",
            CustomerUser="kunde@example.com",
        ),
        Article=Article(
            Subject="Initialer Bericht",
            Body="Der Server antwortet seit 08:00 nicht.",
            MimeType="text/plain",
        ),
    )
)
print(response.TicketID)

Weitere Pakete auf OpenITSMHub: Python REST API Client, pyznuny.

7. OpenTicketAI Runtime & Znuny-Connector

Wer die Znuny REST API intelligent automatisieren möchte, nutzt die OpenTicketAI Runtime — On-Premise-KI, die Tickets klassifiziert, priorisiert und weiterleitet.

  Eingehende E-Mails / REST  ──►  Znuny (Generic Interface)
                                        │
                                        ▼
                              OpenTicketAI Runtime (Docker)
                                        │
                                        ▼
                              TicketUpdate / Routing per REST

Installation:

pip install open-ticket-ai otai-hf-local otai-znuny-znuny

Paket	Funktion
open-ticket-ai	Orchestrierung, Pipelines
otai-hf-local	Lokale KI-Modelle
otai-znuny-znuny	Znuny REST Connector

Beispiel config.yaml:

connector:
  type: znuny
  url: https://znuny.example.com
  username: otai-bot
  password: "${ZNUNY_PASSWORD}"

model:
  provider: hf-local
  model_name: softoft/ticket-classifier-de

routing:
  default_queue: "Unclassified"
  rules:
    - category: "Netzwerk"
      queue: "IT-Infrastruktur"
      priority: "4 high"

Merkmal	Manuelle REST-Integration	OpenTicketAI + Connector
Klassifizierung	Manuell	Vollautomatisch (KI)
Datenschutz	Lokal	100 % On-Premise
Einrichtung	Hoch	YAML-Config

Mehr erfahren: openticketai.com/de/solutions/znuny/ · OpenTicketAI-Dokumentation · Softoft Demo

Fazit

Die Znuny REST API ist flexibel und über das Generic Interface erweiterbar. Mit korrekt konfigurierten Webservices, HTTPS und — bei Bedarf — OpenTicketAI oder dem Python-SDK binden Sie Znuny sauber in Ihre IT-Landschaft und KI-Strategie ein.