Znuny Web Services – REST API

Znuny Web Services – REST API

In dieser detaillierten Anleitung erfahren Sie, wie Sie die Znuny REST API (Teil des Generic Interface) aktivieren, konfigurieren und in Ihre eigenen Anwendungen integrieren können.

1. Architektur & Grundprinzipien

Znuny stellt sein Generic Interface über REST- und SOAP-Webservices zur Verfügung. Die REST API kommuniziert über HTTP(S) mit JSON-Datenformat und ermöglicht:

• Ticket-Verwaltung: Erstellen, Abrufen, Ändern, Löschen
• Artikel-Verwaltung: Artikel hinzufügen, Anhänge verwalten
• Historie & Suche: Ticket-Verlauf einsehen und komplexe Suchabfragen durchführen

Wichtiger Hinweis: Eine Standardinstallation enthält keine vorkonfigurierten Webservices – diese müssen im Admin-Bereich unter „Prozesse & Automation → Web Services” manuell angelegt werden.

2. Konfiguration

2.1 Generic Interface aktivieren

1. Navigieren Sie im Admin-Bereich zu SysConfig → GenericInterface.Transport und wählen Sie REST (HTTP).
2. Unter AdminGenericInterfaceTransportHTTPREST konfigurieren Sie Timeouts, Host-Header und Debug-Level.
3. In GenericInterface.Operation legen Sie die gewünschten Operationen an (z. B. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) und aktivieren diese.

2.2 Basis-URL & Authentifizierung

• Basis-URL TicketCreate
• Authentifizierung
  • Znuny-Session-Cookies
  • API-Keys / Token (über SysConfig konfigurierbar)
  • Verwenden Sie immer HTTPS für sichere Übertragungen!

3. Endpunkte & HTTP-Methoden (Detailübersicht)

Für jeden Endpunkt finden Sie hier eine ausführliche Darstellung zu Parametern, möglichen Antworten und praxisnahen Beispielen.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate Methode: POST Beschreibung: Erstellt ein neues Ticket und legt gleichzeitig einen ersten Artikel an.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Session-ID oder UserLogin+Password
UserLogin	String	Ja²	Agenten-Login (in Kombination mit Password)
Password	String	Ja²	Passwort (in Kombination mit UserLogin)
Ticket.Title	String	Ja	Betreff des Tickets
Ticket.Queue	String	Ja	Warteschlangen-Name oder Ticket.QueueID
Ticket.State	String	Ja	Anfangsstatus (z. B. new)
Ticket.Priority	String	Ja	Priorität (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 des ersten Artikels
Article.MimeType	String	Ja	text/plain oder text/html
¹ Entweder SessionID ODER UserLogin+Password erforderlich.
² Wenn kein SessionID-Token vorliegt.
Beispiel Request:
TicketSearch
Beispiel Antwort:
TicketGet

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch Methode: GET Beschreibung: Durchsucht Tickets anhand verschiedenster Filterkriterien.

Parameter	Typ	Pflicht	Beschreibung
UserLogin, Password	String,String	Ja¹	Agenten-Credentials oder SessionID²
SessionID	Integer	Ja²	Token für authentifizierte Sitzungen
Title	String/String[]	Nein	Wildcard-Suche im Titel (%Bestellung%)
TicketNumber	String/String[]	Nein	Ticketnummer(n)
QueueIDs	Integer[]	Nein	Warteschlangen-IDs
States	String[]	Nein	Status (new, open, …)
StateType	String/String[]	Nein	Open/Closed-Kategorie
DynamicField_Name.Op	Mixed	Nein	Dynamische Felder mit Operator (Equals, Like, GreaterThan …)
¹ Entweder UserLogin+Password ODER SessionID.
² Wenn kein Login-Paar übergeben wird.
Beispiel Request:
TicketUpdate
Beispiel Antwort:
TicketDelete

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Methode: GET Beschreibung: Ruft detaillierte Ticket-Daten inklusive Artikel, Anhängen und dynamischen Feldern ab.

Parameter	Typ	Pflicht	Beschreibung
UserLogin, Password	String,String	Ja¹	Agenten-Credentials oder SessionID²
SessionID	Integer	Ja²	Token für authentifizierte Sitzungen
TicketID	String/String[]	Ja	Eine oder mehrere Ticket-IDs (komma-getrennt oder Array)
DynamicFields	Boolean (0/1)	Nein	1 = Dynamische Felder im Ergebnis, Standard = 0
Extended	Boolean	Nein	1 = Erweiterte Metadaten (z. B. FirstResponse)
AllArticles	Boolean	Nein	1 = Alle Artikel zurückliefern
ArticleLimit	Integer	Nein	Max. Anzahl der zurückgegebenen Artikel
Attachments	Boolean	Nein	1 = Anhänge in Base64 einbetten
GetAttachmentContents	Boolean	Nein	1 = Inhalte der Anhänge ebenfalls laden
HTMLBodyAsAttachment	Boolean	Nein	1 = HTML-Version des Artikels als Attachment anfügen
¹ Entweder UserLogin+Password ODER SessionID.
² Wenn kein Login-Paar übergeben wird.
Beispiel Request:
TicketHistoryGet
Beispiel Antwort (gekürzt):
/Webservice/<ServiceName>/TicketCreate

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Methode: PUT Beschreibung: Aktualisiert Felder eines bestehenden Tickets und kann optional einen neuen Artikel erstellen.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Token oder UserLogin+Password²
TicketID	Integer	Ja	ID des zu aktualisierenden Tickets
Ticket.Title	String	Nein	Neuer Titel
Ticket.State	String	Nein	Neuer Status
Ticket.Owner	String/ID	Nein	Neuer Besitzer
Ticket.PendingTime	Hash / Diff	Nein	Neue Pending-Zeit
Article.Subject	String	Nein	Erstellt einen neuen Artikel
Article.Body	String	Nein	Inhalt des neuen Artikels
DynamicField…	Array	Nein	Dynamische Felder aktualisieren
Attachment…	Array	Nein	Neue Anhänge hinzufügen
¹ Entweder SessionID ODER UserLogin+Password.
² Wenn kein SessionID-Token vorliegt.
Beispiel Request:
POST
Beispiel Antwort:
new

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete Methode: DELETE Beschreibung: Löscht ein oder mehrere Tickets endgültig.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Token oder UserLogin+Password²
TicketID	String/Array	Ja	Ein oder mehrere Ticket-IDs
Beispiel Request:
3 normal
Beispiel Antwort:
text/plain

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet Methode: GET Beschreibung: Ruft die Historie eines oder mehrerer Tickets ab.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Token oder UserLogin+Password²
TicketID	String/Array	Ja	Ein oder mehrere Ticket-IDs
Beispiel Request:
text/html

4. Erweiterung & Anpassung

4.1 WADL-Definition

Neue Ressourcen in der WADL-Datei definieren: /Webservice/<ServiceName>/TicketSearch

4.2 YAML-Import

Alternativ können Sie Operationen per YAML definieren: GET

5. Fehlerbehandlung & Logging

• Erfolgsindikator: Success: 0|1
• Fehlermeldung: ErrorMessage im JSON
• Debugging: Setzen Sie im Transport-Dialog Debug-Level auf Debug → Log-Einträge werden in der Datenbank sichtbar

---

6. Anwendungsfälle

Szenario	Beschreibung
Systemübergreifende Automatisierung	Tickets aus Monitoring-Tools (Nagios, Zabbix) erstellen
Datensynchronisation	Batch-Updates von Ticket-Feldern aus externem CRM
Self-Service-Portale	Kunden legen eigene Tickets via REST an
Mobile Apps	Native iOS/Android-Apps kommunizieren per REST

---

Fazit

Die Znuny REST API ist flexibel, performant und dank Generic Interface hochgradig erweiterbar. Ob einfache Ticket-Erstellung oder komplexe Workflow-Automatisierung – mit wenigen Schritten im Admin-Bereich und Standard-JSON-Requests realisieren Sie nahtlose Integrationen in jede IT-Landschaft.

---

7. Python-Client: pyznuny

Für Python-Entwickler steht das offizielle Paket pyznuny zur Verfügung, das die gesamte Znuny REST API in einer einfachen, typisierten Bibliothek kapselt. Sie müssen keine HTTP-Requests von Hand formulieren – pyznuny übernimmt Authentifizierung, Session-Management und die Serialisierung aller Parameter.

7.1 Installation

pip install pyznuny

7.2 Schnellstart

from pyznuny import ZnunyClient

client = ZnunyClient(
    url="https://znuny.example.com",
    username="admin",
    password="geheim"
)

# Ticket erstellen
ticket_id = client.ticket_create(
    title="Server nicht erreichbar",
    queue="Support",
    state="new",
    priority="3 normal",
    customer_user="kunde@example.com",
    article_subject="Initialer Bericht",
    article_body="Der Server antwortet seit 08:00 Uhr nicht mehr.",
    mime_type="text/plain"
)
print(f"Neues Ticket erstellt: #{ticket_id}")

# Ticket abrufen
ticket = client.ticket_get(ticket_id=ticket_id, all_articles=True)
print(ticket)

# Ticket aktualisieren
client.ticket_update(ticket_id=ticket_id, state="open", owner="max.muster")

7.3 Unterstützte Operationen

Methode	Beschreibung
ticket_create()	Neues Ticket mit erstem Artikel anlegen
ticket_get()	Ticket-Details inkl. Artikeln & Anhängen abrufen
ticket_search()	Tickets nach Filtern durchsuchen
ticket_update()	Felder, Status, Owner und Artikel aktualisieren
ticket_delete()	Ticket endgültig löschen
ticket_history_get()	Vollständige Historie eines Tickets laden

Hinweis: pyznuny ist auf PyPI verfügbar und wird aktiv von Softoft gepflegt.

---

8. OpenTicketAI Runtime & Znuny-Connector

Wer die Znuny REST API nicht nur nutzen, sondern intelligent automatisieren möchte, setzt auf die OpenTicketAI Runtime – eine On-Premise-KI-Plattform, die eingehende Tickets vollautomatisch klassifiziert, priorisiert und weiterleitet.

8.1 Systemarchitektur

                            ┌─────────────────────────┐
  Eingehende E-Mails  ────► │   Znuny (Generic Interface / REST API)  │
                            └────────────┬────────────┘
                                         │  Webhook / Polling
                                         ▼
                            ┌─────────────────────────┐
                            │  OpenTicketAI Runtime   │
                            │  (Docker, On-Premise)   │
                            │  ┌───────────────────┐  │
                            │  │  KI-Modell (NLP)  │  │
                            │  └───────────────────┘  │
                            └────────────┬────────────┘
                                         │  otai-znuny-znuny Connector
                                         ▼
                            ┌─────────────────────────┐
                            │  Znuny REST API          │
                            │  TicketUpdate / Routing  │
                            └─────────────────────────┘

Die Runtime läuft vollständig lokal in Ihrem Rechenzentrum – keine Ticketdaten verlassen Ihre Infrastruktur.

8.2 Installation des Znuny-Connectors

Installieren Sie die OpenTicketAI-Kernbibliothek zusammen mit dem Znuny-spezifischen Connector-Paket otai-znuny-znuny:

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

Paket	Funktion
open-ticket-ai	OpenTicketAI-Kern: Orchestrierung, Pipelines, Config
otai-hf-local	Lokale KI-Modelle via Hugging Face (On-Premise)
otai-znuny-znuny	Connector: liest & schreibt Tickets via Znuny REST

8.3 Konfiguration

Legen Sie eine config.yaml an und verbinden Sie die Runtime mit Ihrer Znuny-Instanz:

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"
    - category: "Abrechnung"
      queue: "Buchhaltung"
      priority: "3 normal"

8.4 Ablauf einer automatischen Ticket-Verarbeitung

1. Ticket eingeht in Znuny (via E-Mail oder REST TicketCreate)
2. Connector pollt per TicketSearch nach neuen Tickets im konfigurierten Intervall
3. KI-Modell analysiert Betreff und Artikeltext mit Natural Language Processing
4. Klassifizierungsergebnis (Kategorie, Priorität, vorgeschlagene Queue) wird bestimmt
5. TicketUpdate via REST setzt Queue, Priorität und optionalen internen Artikel
6. Ticket landet vollautomatisch beim richtigen Team – ohne manuelle Triage

8.5 Vorteile gegenüber manueller REST-Integration

Merkmal	Manuelle REST-Integration	OpenTicketAI + Connector
Klassifizierung	❌ Manuell	✅ Vollautomatisch (KI)
Datenschutz	✅ Lokal	✅ 100 % On-Premise
Regelbasiertes Routing	✅ Möglich	✅ Inklusive
Lernfähigkeit	❌ Starre Regeln	✅ Modell trainierbar
Einrichtungsaufwand	Hoch	Gering (YAML-Config)

Mehr erfahren: Besuchen Sie openticketai.com/de/solutions/znuny/ oder kontaktieren Sie Softoft für eine individuelle Demo.