OTOBO Workflows & Schnittstellen nach Maß
Wir entwickeln robuste Webservices, Prozessmanagement-Abläufe und Drittsystem-Anbindungen passend zu Ihrer IT-Landschaft.

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:
Hinweis: Eine Standard‑Installation enthält keine vorkonfigurierten Webservices – Sie legen diese selbst im Admin‑Modul „Prozesse & Automation → Web Services“ an.
TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) anlegen und aktivieren.
Basis‑URL
https://IHR-SERVER/otobo/nph-genericinterface.pl/Webservice/<IhrServiceName>/Authentifizierung
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.
| 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.1Host: demo.otobo.orgContent-Type: application/jsonX-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.
| 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.1Host: demo.otobo.orgBeispiel 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.
| 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.1Host: demo.otobo.orgBeispiel 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.
| 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.1Host: demo.otobo.orgContent-Type: application/jsonX-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.
| 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.1Host: demo.otobo.orgBeispiel Antwort:
{ "Success":1, "ErrorMessage":"", "Data":{} }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:
GET /Webservice/MyConnectorREST/TicketHistoryGet?SessionID=42&TicketID=12345 HTTP/1.1Host: demo.otobo.orgBeispiel 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::ModuleTransport: Config:RouteOperationMapping: MyTest: RequestMethod: [ GET ] Route: /MyTestSuccess: 0|1ErrorMessage im JSONDebug-Level auf Debug → Log‑Einträge in DB sichtbar| Scenario | 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 |
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).
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.
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.
| Route | HTTP | Zweck |
|---|---|---|
/ticket-create | POST | Ticket anlegen |
/ticket-get | POST | Ticket abrufen |
/ticket-search | POST | Ticket‑IDs suchen |
/ticket-update | PUT | Ticket ändern |
/queue-list | POST | Queues auflisten |
/state-list | POST | Status auflisten |
/priority-list | POST | Prioritäten auflisten |
/service-list | POST | Services auflisten |
/type-list | POST | Typen auflisten |
/dynamic-field-list | POST | Dynamische Felder auflisten |
/dynamic-field-values | POST | Dropdown‑Werte (Parameter Name) |
/faq-search | POST | FAQ durchsuchen (Parameter What) |
POST /otobo/nph-genericinterface.pl/Webservice/OpenTicketAI/ticket-create HTTP/1.1Host: otobo.example.comContent-Type: application/jsonAccept: 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.1Host: otobo.example.comContent-Type: application/json
{ "UserLogin": "otai-webservice", "Password": "geheim", "TicketID": 12345, "AllArticles": 1}POST /otobo/nph-genericinterface.pl/Webservice/OpenTicketAI/queue-list HTTP/1.1Host: otobo.example.comContent-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:
/openapi-openticketai.yamlDie 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.
otai-ts-connectorDie 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.
| Funktion | Port‑Methode |
|---|---|
| Verbindung prüfen | test_connection() |
| Ticket lesen / schreiben | get_ticket, create_ticket, update_ticket, add_note |
| FAQ | faq.get, faq.update, faq.list_ids |
| Katalog / Attribute | attributes.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):
pip install git+https://github.com/Softoft-Orga/otai-ts-connector.gitimport 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.
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.
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.
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.
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.
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.