Znuny REST API – Konfiguration, Endpoints & Beispiele

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

Verwandte Themen: Generic Interface erweitern · 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.

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.

Benötigen Sie einen Endpoint, den Znuny nicht bereitstellt?

Der Guide Znuny REST API mit eigenen Generic-Interface-Operationen erweitern zeigt den vollständigen Entwicklungsweg: Perl-Backend, SysConfig-Registrierung, REST-Routing, Paket-Lifecycle, Sicherheit und Tests.

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-SDK: otai-ts-connector

Der aktuelle Open-Source-Client ist otai-ts-connector (Apache-2.0) — einheitlich für Znuny, OTOBO, Zammad und KIX. Er ersetzt die früheren PyPI-Pakete znuny und otobo.

pip install git+https://github.com/Softoft-Orga/otai-ts-connector.git

import asyncio

from otai_ts_connector import (
    BuildTicketSystemParams,
    TicketSystemProvider,
    build_ticket_system,
)


async def main() -> None:
    service = build_ticket_system(
        BuildTicketSystemParams(
            kind=TicketSystemProvider.ZNUNY,
            base_url="https://znuny.example.com/znuny/nph-genericinterface.pl",
            username="open_ticket_ai",
            password="…",
            webservice_name="OpenTicketAI",
        ),
    )
    await service.test_connection()
    ticket = await service.get_ticket("12345")
    print(ticket.subject)


asyncio.run(main())

HTTP-Referenz und OpenAPI: Die OpenTicketAI-Routen (/ticket-create, /queue-list, …) sind für Znuny identisch — nur der Pfad lautet /znuny/nph-genericinterface.pl/…. Details, curl/HTTP-Beispiele und die OpenAPI-3.1-Spec: OTOBO REST API — OpenTicketAI-Webservice und /openapi-openticketai.yaml.

Provider-Doku im Repository: OTOBO / Znuny.

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 otai-ts-connector binden Sie Znuny sauber in Ihre IT-Landschaft und KI-Strategie ein.

Znuny Automatisierung & Schnittstellen

Integrieren Sie Znuny nahtlos in Ihre IT-Systeme: Wir realisieren Webservices, Prozess-Workflows und REST-Konnektoren nach Ihren Anforderungen.

Automatisierung besprechen

Häufig gestellte Fragen

Wie aktiviere und konfiguriere ich die Znuny REST API nach einer Neuinstallation?

Eine frische Znuny-Installation enthält standardmäßig keine vorkonfigurierten REST-Webservices. Um die REST API zu aktivieren, navigieren Sie zunächst in der SysConfig zu GenericInterface.Transport und wählen dort REST (HTTP) aus. Anschließend können Sie unter AdminGenericInterfaceTransportHTTPREST spezifische Einstellungen wie Timeouts oder Debug-Level anpassen. Im nächsten Schritt müssen Sie die gewünschten Operationen wie TicketCreate, TicketSearch oder TicketGet unter GenericInterface.Operation anlegen und aktivieren. Danach erstellen Sie den eigentlichen Webservice im Admin-Bereich unter Prozesse & Automation → Web Services über Add Web Service, definieren den Provider als REST mit den zuvor aktivierten Operationen und speichern den Dienst. Bei Problemen hilft der integrierte Debugger.

Quellen:

• Web Services — Znuny documentation
• GenericTicketConnectorREST - Znuny Documentation
• Znuny REST API – Konfiguration, Endpoints & Beispiele

Welche Authentifizierungsmethoden stehen für die Znuny REST API zur Verfügung und welche sollte ich wann nutzen?

Für die Authentifizierung an der Znuny REST API stehen Ihnen mehrere Optionen zur Verfügung. Die gängigsten sind die Verwendung einer Znuny-Session mittels SessionID oder die Kombination aus UserLogin und Password eines Agenten. Für Produktionsumgebungen wird dringend empfohlen, immer HTTPS zu verwenden, um die Übertragung der Anmeldeinformationen zu sichern. Darüber hinaus können Sie API-Keys oder Token konfigurieren, indem Sie die SysConfig und die Requester-Konfiguration entsprechend anpassen. Die Wahl der Methode hängt vom Anwendungsfall ab: SessionID ist nützlich für länger laufende Prozesse, während UserLogin und Password oft für einmalige oder kurzlebige Anfragen verwendet werden. API-Keys bieten eine robuste Lösung für die Integration mit externen Systemen.

Quellen:

• Web Services — Znuny documentation
• GenericTicketConnectorREST - Znuny Documentation
• Znuny REST API – Konfiguration, Endpoints & Beispiele

Wie erstelle ich ein neues Ticket über die Znuny REST API mit `TicketCreate`?

Um ein neues Ticket über die Znuny REST API zu erstellen, verwenden Sie die Operation TicketCreate mit der HTTP-Methode POST. Die URL folgt dem Muster /Webservice/<IhrServiceName>/TicketCreate. Im Body der Anfrage, der im JSON-Format übermittelt wird, müssen Sie Authentifizierungsinformationen (entweder SessionID oder UserLogin und Password) sowie die Ticket- und Artikeldetails angeben. Zu den Pflichtfeldern für das Ticket gehören Title, Queue, State, Priority und CustomerUser. Für den ersten Artikel sind Subject, Body und MimeType erforderlich.

Ein Beispiel-Request könnte so aussehen:

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

Die Antwort enthält typischerweise die generierten TicketID und ArticleID.

Quellen:

• GenericTicketConnectorREST - Znuny Documentation
• How to create e-mail tickets via REST API?
• Znuny REST API – Konfiguration, Endpoints & Beispiele

Wie suche ich nach Tickets mit der Znuny REST API und der Operation `TicketSearch`?

Die Operation TicketSearch ermöglicht es Ihnen, Tickets basierend auf verschiedenen Kriterien zu finden. Sie kann sowohl mit der HTTP-Methode GET als auch POST verwendet werden, abhängig von der Konfiguration Ihres Webservices. Die URL lautet /Webservice/<IhrServiceName>/TicketSearch. Bei einer GET-Anfrage werden die Parameter URL-kodiert in der URL übergeben, während bei POST ein JSON-Body verwendet wird.

Wichtige Parameter für die Suche sind Authentifizierungsinformationen (UserLogin + Password oder SessionID), sowie Filter wie Title (unterstützt Wildcards wie %Server%), QueueIDs (ein Array von Queue-IDs), States (z.B. new, open) und Limit zur Begrenzung der Trefferanzahl.

Ein Beispiel für eine GET-Anfrage:
GET /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketSearch?UserLogin=agent&Password=geheim&Title=%Server% HTTP/1.1

Die Antwort liefert ein Array von TicketIDs, die den Suchkriterien entsprechen.

Quellen:

• GenericTicketConnectorREST - Znuny Documentation
• Znuny REST API – Konfiguration, Endpoints & Beispiele

Welche weiteren wichtigen Operationen bietet die Znuny REST API für die Ticketverwaltung?

Neben dem Erstellen und Suchen von Tickets bietet die Znuny REST API eine Reihe weiterer essentieller Operationen zur umfassenden Ticketverwaltung:

• TicketGet (GET): Diese Operation ruft detaillierte Informationen zu einem oder mehreren Tickets ab. Sie können angeben, ob alle Artikel (AllArticles), Anhänge (Attachments) und dynamische Felder (DynamicFields) ebenfalls abgerufen werden sollen. Die URL ist /Webservice/<ServiceName>/TicketGet.
• TicketUpdate (PUT): Ermöglicht die Aktualisierung bestehender Ticket-Felder wie Ticket.State, Ticket.Queue oder das Hinzufügen eines neuen Artikels zum Ticket mit Article.Body. Die URL ist /Webservice/<ServiceName>/TicketUpdate.
• TicketDelete (DELETE): Dient zum endgültigen Löschen von Tickets. Sie übergeben die TicketID (als String oder Array) des zu löschenden Tickets. Die URL ist /Webservice/<ServiceName>/TicketDelete.
• TicketHistoryGet (GET): Ruft die vollständige Historie für eine oder mehrere TicketIDs ab, was nützlich ist, um den Verlauf von Änderungen und Aktionen nachzuvollziehen. Die URL ist /Webservice/<ServiceName>/TicketHistoryGet.
  Diese Operationen decken die meisten Anforderungen für die Integration und Automatisierung der Ticketverwaltung ab.

Quellen:

• GenericTicketConnectorREST - Znuny Documentation
• Znuny Documentation — Manuals, API & Developer Guides
• Znuny REST API – Konfiguration, Endpoints & Beispiele

Was ist die Basis-URL für Znuny REST API Aufrufe und worauf muss ich achten?

Die Basis-URL für Znuny REST API Aufrufe folgt einem standardisierten Muster:
https://IHR-SERVER/znuny/nph-genericinterface.pl/Webservice/<IhrServiceName>/

Es ist jedoch wichtig zu beachten, dass der Pfad nach dem Servernamen je nach Ihrer spezifischen Znuny-Installation variieren kann. Einige ältere oder migrierte Installationen verwenden möglicherweise /otrs/ anstelle von /znuny/ im Pfad. Um die korrekte Basis-URL für Ihre Umgebung zu ermitteln, sollten Sie die URL direkt in der Webservice-Konfiguration im Admin-Bereich von Znuny überprüfen. Dort wird der genaue Pfad angezeigt, den Ihr konfigurierter Webservice verwendet. Das korrekte Angeben dieser Basis-URL ist entscheidend für eine erfolgreiche Kommunikation mit der API.

Quellen:

• Web Services — Znuny documentation
• Znuny REST API – Konfiguration, Endpoints & Beispiele