OTOBO / Znuny Web Services – REST API

In dieser ausführlichen Anleitung erfahren Sie, wie Sie die OTOBO REST API (Teil des Generischen Interface) aktivieren, konfigurieren und in eigene Anwendungen integrieren.

1. Architektur & Grundlagen

OTOBO stellt sein Generisches Interface über REST- und SOAP‑Webservices bereit. Die REST API kommuniziert via HTTP(S)/JSON und ermöglicht:

• Ticket‑Operationen: Anlegen, Abrufen, Ändern, Löschen
• Artikel‑Operationen: Posten, Anhänge verwalten
• Historie & Suche: Ticket‑Verlauf und komplexe Suchanfragen

Hinweis: Eine Standard‑Installation enthält keine vorkonfigurierten Webservices – Sie legen diese selbst im Admin‑Modul „Prozesse & Automation → Web Services“ an.

2. Konfiguration

2.1 Generic Interface aktivieren

1. Im Admin‑Bereich → SysConfig → GenericInterface.Transport auf REST (HTTP) umstellen.
2. Unter AdminGenericInterfaceTransportHTTPREST Timeouts, Host‑Header und Debug‑Level einstellen.
3. In GenericInterface.Operation gewünschte Operationen (z. B. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) anlegen und aktivieren.

2.2 Basis‑URL & Authentifizierung

• Basis‑URL

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

• Authentifizierung

  • OTOBO‑Session‑Cookies
  • API‑Keys / Token (über SysConfig anlegen)
  • Immer HTTPS verwenden!

3. Endpunkte & HTTP‑Methoden (Detail)

Für jeden Endpunkt finden Sie hier eine detaillierte Übersicht zu Parametern, möglichen Antworten und Praxis‑Beispielen.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreateMethode: POST

Beschreibung: Legt ein neues Ticket an und erstellt gleich einen Artikel.

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	Queue-Name oder Ticket.QueueID
Ticket.State	String	Ja	Anfangszustand (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.otobo.org
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: Sucht Tickets anhand vielfältiger 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	Queue-IDs
States	String[]	Nein	Zustände (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.otobo.org

Beispiel Antwort:

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

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGetMethode: GET

Beschreibung: Gibt detaillierte Ticket-Daten inklusive Artikel, Anhängen und dynamischen Feldern zurück.

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, Default = 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.otobo.org

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 existierenden Tickets und optional einen neuen Artikel erstellt.

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.otobo.org
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.otobo.org

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,

5. Erweiterung & Anpassung

5.1 WADL‑Definition

Neue Ressourcen in GenericTicketConnectorREST.wadl:

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

5.2 YAML‑Import

Alternativ per YAML in development/webservices/GenericTicketConnectorREST.yml:

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

---

6. Fehlerbehandlung & Logging

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

---

7. Anwendungsfälle

Scenario	Beschreibung
Systemübergreifende Automatisierung	Tickets aus Monitoring‑Tools (Nagios, Zabbix) erstellen
Daten­synchronisation	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

---

8. Weitere UI‑Elemente & Integration

Web Service Klonen

Error Handling Modul

Fazit

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