Zum Inhalt springen

OTOBO REST API – Konfiguration, Endpoints & Beispiele

OTOBO REST API

In diesem Guide: REST API (Generisches Interface) aktivieren, konfigurieren und in eigene Anwendungen integrieren.

Verwandte Themen: Web Services Übersicht · OpenID Connect · Performance-Optimierung · Softoft Services

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

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.

  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.

Web Service Hinzufügen Web Service Provider

  • Basis‑URL

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

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

REST Requester einrichten

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

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

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

ParameterTypPflichtBeschreibung
SessionIDIntegerJa¹Session-ID oder UserLogin+Password
UserLoginStringJa²Agenten-Login (in Kombination mit Password)
PasswordStringJa²Passwort (in Kombination mit UserLogin)
Ticket.TitleStringJaBetreff des Tickets
Ticket.QueueStringJaQueue-Name oder Ticket.QueueID
Ticket.StateStringJaAnfangszustand (z. B. new)
Ticket.PriorityStringJaPriorität (z. B. 3 normal)
Ticket.CustomerUserStringJaKunden-E-Mail oder Login
Article.SubjectStringJaBetreff des ersten Artikels
Article.BodyStringJaInhalt des ersten Artikels
Article.MimeTypeStringJatext/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"
}
}

URL: /Webservice/<ServiceName>/TicketSearch Methode: GET

Beschreibung: Sucht Tickets anhand vielfältiger Filterkriterien.

ParameterTypPflichtBeschreibung
UserLogin, PasswordString,StringJa¹Agenten-Credentials oder SessionID²
SessionIDIntegerJa²Token für authentifizierte Sitzungen
TitleString/String[]NeinWildcard-Suche im Titel (%Bestellung%)
TicketNumberString/String[]NeinTicketnummer(n)
QueueIDsInteger[]NeinQueue-IDs
StatesString[]NeinZustände (new, open, …)
StateTypeString/String[]NeinOpen/Closed-Kategorie
DynamicField_Name.OpMixedNeinDynamische 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]
}
}

URL: /Webservice/<ServiceName>/TicketGet Methode: GET

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

ParameterTypPflichtBeschreibung
UserLogin, PasswordString,StringJa¹Agenten-Credentials oder SessionID²
SessionIDIntegerJa²Token für authentifizierte Sitzungen
TicketIDString/String[]JaEine oder mehrere Ticket-IDs (komma-getrennt oder Array)
DynamicFieldsBoolean (0/1)Nein1 = Dynamische Felder im Ergebnis, Default = 0
ExtendedBooleanNein1 = Erweiterte Metadaten (z. B. FirstResponse)
AllArticlesBooleanNein1 = Alle Artikel zurückliefern
ArticleLimitIntegerNeinMax. Anzahl der zurückgegebenen Artikel
AttachmentsBooleanNein1 = Anhänge in Base64 einbetten
GetAttachmentContentsBooleanNein1 = Inhalte der Anhänge ebenfalls laden
HTMLBodyAsAttachmentBooleanNein1 = 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…="}]
}]
}]
}
}

URL: /Webservice/<ServiceName>/TicketUpdate Methode: PUT

Beschreibung: Aktualisiert Felder eines existierenden Tickets und optional einen neuen Artikel erstellt.

ParameterTypPflichtBeschreibung
SessionIDIntegerJa¹Token oder UserLogin+Password²
TicketIDIntegerJaID des zu aktualisierenden Tickets
Ticket.TitleStringNeinNeuer Titel
Ticket.StateStringNeinNeuer Status
Ticket.OwnerString/IDNeinNeuer Besitzer
Ticket.PendingTimeHash / DiffNeinNeue Pending-Zeit
Article.SubjectStringNeinErstellt einen neuen Artikel
Article.BodyStringNeinInhalt des neuen Artikels
DynamicField…ArrayNeinDynamische Felder aktualisieren
Attachment…ArrayNeinNeue 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 } }

URL: /Webservice/<ServiceName>/TicketDelete Methode: DELETE

Beschreibung: Löscht ein oder mehrere Tickets endgültig.

ParameterTypPflichtBeschreibung
SessionIDIntegerJa¹Token oder UserLogin+Password²
TicketIDString/ArrayJaEin 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":{} }

URL: /Webservice/<ServiceName>/TicketHistoryGet Methode: GET

Beschreibung: Ruft die Historie eines oder mehrerer Tickets ab.

ParameterTypPflichtBeschreibung
SessionIDIntegerJa¹Token oder UserLogin+Password²
TicketIDString/ArrayJaEin oder mehrere Ticket-IDs

Beispiel Request:

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

Beispiel Antwort (gekürzt):

{
"Success": 1,
"ErrorMessage": "",
"Data": {
"TicketID": 12345,
"History": [
{ "HistoryType": "NewTicket", "Name": "Neues Ticket erstellt", "CreateTime": "2025-01-23 09:15:00" },
{ "HistoryType": "StateUpdate", "Name": "Status auf open geändert", "CreateTime": "2025-01-23 10:02:11" }
]
}
}

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>

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

SOAP Provider hinzufügen


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

Webservice‑Debugger


ScenarioBeschreibung
Systemübergreifende AutomatisierungTickets aus Monitoring‑Tools (Nagios, Zabbix) erstellen
Daten­synchronisationBatch‑Updates von Ticket‑Feldern aus externem CRM
Self‑Service‑PortaleKunden legen eigene Tickets via REST an
Mobile AppsNative iOS/Android‑Apps kommunizieren per REST

Webservice klonen Error Handling Modul

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.

Nein. Eine Standard‑Installation enthält keine vorkonfigurierten Webservices. Sie legen diese selbst unter Prozesse & Automation → Web Services an (oder importieren eine YAML‑Definition wie oben gezeigt).

Wie authentifiziere ich mich an der OTOBO REST API?

Abschnitt betitelt „Wie authentifiziere ich mich an der OTOBO REST API?“

Entweder über eine SessionID (per SessionCreate-Operation erzeugt) oder durch Übergabe von UserLogin + Password bei jedem Request. Verwenden Sie immer HTTPS, damit Zugangsdaten und Token nie im Klartext übertragen werden.

https://IHR-SERVER/otobo/nph-genericinterface.pl/Webservice/<IhrServiceName>/. Jede Operation (z. B. TicketCreate) wird anschließend auf eine Route abgebildet, die Sie in der Transport‑Konfiguration festlegen.

Standardmäßig konfigurierbar sind TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete und TicketHistoryGet. Über das GenericInterface lassen sich eigene Operationen ergänzen.

Gibt es einen Python‑Client für die OTOBO REST API?

Abschnitt betitelt „Gibt es einen Python‑Client für die OTOBO REST API?“

Ja — die Open‑Source‑Bibliothek otai-ts-connector (Apache‑2.0) ist der aktuelle Python‑Client für OTOBO, Znuny, Zammad und KIX. Siehe den Quickstart und die HTTP‑Referenz weiter unten.

Wenn Sie das Open Ticket AI Connector‑Paket installiert haben, steht ein vorkonfigurierter REST‑Webservice OpenTicketAI bereit. Die Routen sind kebab‑case; Authentifizierung erfolgt über UserLogin und Password im JSON‑Body (Generic Interface — nicht als Authorization‑Header).

Basis‑URL:

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

Standard‑API‑Benutzer nach Connector‑Installation: otai-webservice.

RouteHTTPZweck
/ticket-createPOSTTicket anlegen
/ticket-getPOSTTicket abrufen
/ticket-searchPOSTTicket‑IDs suchen
/ticket-updatePUTTicket ändern
/queue-listPOSTQueues auflisten
/state-listPOSTStatus auflisten
/priority-listPOSTPrioritäten auflisten
/service-listPOSTServices auflisten
/type-listPOSTTypen auflisten
/dynamic-field-listPOSTDynamische Felder auflisten
/dynamic-field-valuesPOSTDropdown‑Werte (Parameter Name)
/faq-searchPOSTFAQ durchsuchen (Parameter What)
POST /otobo/nph-genericinterface.pl/Webservice/OpenTicketAI/ticket-create HTTP/1.1
Host: otobo.example.com
Content-Type: application/json
Accept: application/json
{
"UserLogin": "otai-webservice",
"Password": "geheim",
"Ticket": {
"Title": "Neue Bestellung",
"Queue": "Sales",
"State": "new",
"Priority": "3 normal",
"CustomerUser": "kunde@example.com"
},
"Article": {
"Subject": "Produktanfrage",
"Body": "Bitte um Preisangebot…",
"ContentType": "text/plain"
}
}

Antwort (vereinfacht):

{
"TicketID": 12345,
"TicketNumber": "202601010001",
"ArticleID": 67890
}
POST /otobo/nph-genericinterface.pl/Webservice/OpenTicketAI/ticket-get HTTP/1.1
Host: otobo.example.com
Content-Type: application/json
{
"UserLogin": "otai-webservice",
"Password": "geheim",
"TicketID": 12345,
"AllArticles": 1
}
POST /otobo/nph-genericinterface.pl/Webservice/OpenTicketAI/queue-list HTTP/1.1
Host: otobo.example.com
Content-Type: application/json
{
"UserLogin": "otai-webservice",
"Password": "geheim"
}

Antwort (vereinfacht):

{
"Item": [
{ "ID": 2, "Name": "Sales", "ValidID": 1 }
]
}

OTOBO liefert kein OpenAPI‑Schema mit — das Generic Interface dokumentiert sich historisch über WADL (siehe Abschnitt 4.1). Auch die offizielle OTOBO‑Dokumentation enthält keine ReDoc‑ oder Swagger‑UI‑Oberfläche.

Für den OpenTicketAI‑Webservice stellen wir eine Community‑OpenAPI‑3.1‑Spezifikation bereit:

Die Spec deckt Ticket‑ und Katalog‑Routen des Connector‑Webservices ab. Standard‑Generic‑Interface‑Webservices mit eigenen Routen sind davon nicht abgedeckt — dort gelten Ihre YAML‑Transport‑Mappings.

Die Bibliothek otai-ts-connector ist der einheitliche Python‑Client für OTOBO, Znuny, Zammad und KIX (Apache‑2.0, Python 3.14+). Sie ersetzt die früheren separaten PyPI‑Pakete otobo und znuny.

FunktionPort‑Methode
Verbindung prüfentest_connection()
Ticket lesen / schreibenget_ticket, create_ticket, update_ticket, add_note
FAQfaq.get, faq.update, faq.list_ids
Katalog / Attributeattributes.list, get_definition, dynamic_field_rows

Es gibt kein find_tickets oder faq.search auf den Produkt‑Ports — Suche läuft typischerweise über einen Indexer (z. B. Meilisearch), nicht über dieses SDK.

Weitere Dokumentation im Repository: OTOBO / Znuny Provider.

Aktuell über Git (PyPI kann folgen):

Terminal-Fenster
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.OTOBO,
base_url="https://otobo.example.com/otobo/nph-genericinterface.pl",
username="otai-webservice",
password="…",
webservice_name="OpenTicketAI",
),
)
await service.test_connection()
ticket = await service.get_ticket("12345")
print(ticket.subject)
asyncio.run(main())

Unter der Haube sendet der Client dieselben HTTP‑Requests wie in der HTTP‑Referenz — z. B. POST …/ticket-get mit UserLogin, Password und TicketID im JSON‑Body.

Apache‑2.0 © Softoft / Open Ticket AI

OTOBO Workflows & Schnittstellen nach Maß

Wir entwickeln robuste Webservices, Prozessmanagement-Abläufe und Drittsystem-Anbindungen passend zu Ihrer IT-Landschaft.

Häufig gestellte Fragen

Wie aktiviere und konfiguriere ich die OTOBO REST API (Generisches Interface)?

Die Aktivierung und Konfiguration der OTOBO REST API erfolgt in mehreren Schritten über die SysConfig. Zuerst müssen Sie im Admin-Bereich unter SysConfig den Parameter GenericInterface.Transport auf REST (HTTP) umstellen. Nach dem Speichern und Neuladen des Bildschirms können Sie unter AdminGenericInterfaceTransportHTTPREST spezifische Einstellungen wie Timeouts, Host-Header und den Debug-Level anpassen. Anschließend legen Sie unter GenericInterface.Operation die gewünschten Operationen an und aktivieren diese, beispielsweise TicketCreate, TicketSearch, TicketGet, TicketUpdate oder TicketDelete. Eine Standard-Installation enthält keine vorkonfigurierten Webservices, daher müssen diese manuell im Admin-Modul „Prozesse & Automation → Web Services“ erstellt werden. Es ist wichtig, alle relevanten Operationen zu aktivieren, die Ihre Anwendung über die API nutzen soll.

Welche Hauptfunktionen bietet die OTOBO REST API für die Ticketverwaltung?

Die OTOBO REST API, als Teil des Generischen Interface, bietet umfassende Funktionen zur Verwaltung von Tickets und Artikeln. Sie ermöglicht grundlegende Ticket-Operationen wie das Anlegen (TicketCreate), Abrufen (TicketGet), Ändern (TicketUpdate) und Löschen (TicketDelete) von Tickets. Darüber hinaus können Sie Artikel-Operationen durchführen, um Artikel zu Tickets hinzuzufügen oder Anhänge zu verwalten. Die API unterstützt auch komplexe Suchanfragen (TicketSearch) zur Filterung von Tickets anhand verschiedener Kriterien sowie das Abrufen des Ticket-Verlaufs (TicketHistoryGet). Diese Flexibilität macht die REST API zu einem mächtigen Werkzeug für die Integration von OTOBO in externe Anwendungen und die Automatisierung von Workflows.

Wie funktioniert die Authentifizierung bei der OTOBO REST API und welche Sicherheitsaspekte sind zu beachten?

Die OTOBO REST API unterstützt verschiedene Authentifizierungsmethoden, um den Zugriff zu sichern. Sie können sich entweder über OTOBO-Session-Cookies authentifizieren, was typischerweise für interaktive Agenten-Sitzungen verwendet wird, oder über API-Keys / Token, die über die SysConfig generiert und verwaltet werden können. Eine weitere gängige Methode ist die Übergabe von UserLogin und Password direkt im Request-Body oder als Query-Parameter, insbesondere bei Operationen wie TicketCreate oder TicketSearch, wenn kein Session-ID-Token vorliegt. Ein entscheidender Sicherheitsaspekt ist die ausschließliche Verwendung von HTTPS für alle API-Kommunikationen, um die Vertraulichkeit und Integrität der übertragenen Daten zu gewährleisten und Man-in-the-Middle-Angriffe zu verhindern.

Wie erstelle ich ein neues Ticket über die OTOBO REST API mit der Operation TicketCreate?

Um ein neues Ticket über die OTOBO REST API zu erstellen, verwenden Sie die TicketCreate-Operation mit der HTTP-Methode POST. Die URL für diese Operation lautet /Webservice/<IhrServiceName>/TicketCreate. Im Request-Body müssen Sie ein JSON-Objekt mit den erforderlichen Daten übergeben. Dazu gehören Authentifizierungsinformationen (entweder SessionID oder UserLogin und Password), sowie die Ticket-Details wie Ticket.Title, Ticket.Queue, Ticket.State, Ticket.Priority und Ticket.CustomerUser. Zusätzlich müssen Sie auch die Details für den ersten Artikel des Tickets angeben, wie Article.Subject, Article.Body und Article.MimeType. Ein erfolgreicher Request gibt eine JSON-Antwort mit der TicketID und ArticleID des neu erstellten Tickets zurück.

Wie suche ich Tickets mit der OTOBO REST API und der Operation TicketSearch?

Die TicketSearch-Operation der OTOBO REST API ermöglicht es Ihnen, Tickets basierend auf verschiedenen Filterkriterien zu finden. Sie verwenden hierfür die HTTP-Methode GET und die URL /Webservice/<IhrServiceName>/TicketSearch. Die Suchparameter werden als Query-Parameter in der URL übergeben. Obligatorisch sind Authentifizierungsinformationen, entweder UserLogin und Password oder eine SessionID. Optional können Sie Parameter wie Title (mit Wildcards wie %Bestellung%), TicketNumber, QueueIDs, States (z.B. new, open), StateType (Open/Closed-Kategorie) oder sogar dynamische Felder mit Operatoren (DynamicField_Name.Op) verwenden. Die Antwort ist ein JSON-Objekt, das eine Liste der gefundenen TicketIDs enthält, die den Suchkriterien entsprechen.