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

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

• 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>/TicketCreateMethode: 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:

POST /Webservice/MyConnectorREST/TicketCreate HTTP/1.1
Host: demo.znuny.com
Content-Type: application/json
X-API-Key: abc123

{
  "Data": {
    "SessionID":  42,
    "Ticket": {
      "Title":        "Neue Bestellung",
      "Queue":        "Sales",
      "State":        "new",
      "Priority":     "3 normal",
      "CustomerUser": "max.mustermann@example.com"
    },
    "Article": {
      "Subject":  "Kaufanfrage – Produkt XY",
      "Body":     "Bitte um Preisangebot…",
      "MimeType": "text/plain"
    }
  }
}

Beispiel Antwort:

{
  "Success":      1,
  "ErrorMessage": "",
  "Data": {
    "TicketID":     "12345",
    "ArticleID":    "67890"
  }
}

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearchMethode: 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:

GET /Webservice/MyConnectorREST/TicketSearch?UserLogin=agent1&Password=geheim&Title=%25Bestellung%25 HTTP/1.1
Host: demo.znuny.com

Beispiel Antwort:

{
  "Success": 1,
  "Data": {
    "TicketID": [1001,1005,1012]
  }
}

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGetMethode: 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:

GET /Webservice/MyConnectorREST/TicketGet?SessionID=42&TicketID=12345&AllArticles=1&DynamicFields=1 HTTP/1.1
Host: demo.znuny.com

Beispiel Antwort (gekürzt):

{
  "Success":1,
  "Data":{
    "Ticket":[{  
      "TicketID":12345,
      "TicketNumber":"202501230001",
      "Title":"Neue Bestellung",
      "State":"open",
      "DynamicField":[{"Name":"Urgency","Value":"high"}],
      "Article":[{  
        "ArticleID":67890,
        "Subject":"Kaufanfrage…",
        "Body":"Bitte um Preisangebot…",
        "Attachment":[{"Filename":"Angebot.pdf","Content":"JVBERi0x…="}]
      }]
    }]
  }
}

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdateMethode: 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:

PUT /Webservice/MyConnectorREST/TicketUpdate HTTP/1.1
Host: demo.znuny.com
Content-Type: application/json
X-API-Key: abc123

{
  "Data":{
    "SessionID":42,
    "TicketID":12345,
    "Ticket":{ "State":"pending reminder","PendingTime":{"Diff":1440} },
    "Article":{ "Subject":"Reminder gesetzt","Body":"Ticket wird bearbeitet." }
  }
}

Beispiel Antwort:

{ "Success":1, "ErrorMessage":"", "Data":{ "TicketID":12345, "ArticleID":67891 } }

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDeleteMethode: 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:

DELETE /Webservice/MyConnectorREST/TicketDelete?SessionID=42&TicketID=12345 HTTP/1.1
Host: demo.znuny.com

Beispiel Antwort:

{ "Success":1, "ErrorMessage":"", "Data":{} }

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGetMethode: 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:

GET /Webservice/MyConnectorREST/TicketHistoryGet?SessionID=42&TicketID=12345 HTTP/1.1
Host: demo.znuny.com

4. Erweiterung & Anpassung

4.1 WADL-Definition

Neue Ressourcen in der WADL-Datei definieren:

<resource path="MyTest" id="MyTest">
    <method name="GET" id="GET_MyTest">
        <response status="200">
            <representation mediaType="application/json"/>
        </response>
    </method>
</resource>

4.2 YAML-Import

Alternativ können Sie Operationen per YAML definieren:

Provider:
  Operation:
    MyTest:
      Description: "Testoperation"
      MappingInbound: { }
      MappingOutbound: { }
      Type: Test::Module
Transport:
  Config:
RouteOperationMapping:
  MyTest:
    RequestMethod: [ GET ]
    Route: /MyTest

---

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.