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"
}
}
}
Vollständige Antwort anzeigen
{
"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
Vollständige Antwort anzeigen
{
"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
Vollständige Antwort anzeigen (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." }
}
}
Vollständige Antwort anzeigen
{
"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
Vollständige Antwort anzeigen
{ "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
Vollständige Antwort anzeigen (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 ein eigenständiger Python‑Client für OTOBO, Znuny, Zammad und KIX. Sie können ihn ohne Open Ticket AI nutzen. Open Ticket AI verwendet denselben Ticketsystem‑Connector. Siehe Quickstart und HTTP‑Referenz.

Der vorkonfigurierte REST‑Webservice OpenTicketAI kommt mit dem Ticketsystem‑Connector‑Paket (siehe Open Ticket AI für OTOBO). Die Routen sind kebab‑case; Authentifizierung erfolgt über UserLogin und Password im JSON‑Body (Generic Interface — nicht als Authorization‑Header). Den Connector und diesen Webservice können Sie allein einsetzen. Open Ticket AI nutzt dieselbe Schnittstelle.

Basis‑URL:

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

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

Lese‑Routen mit GET, POST nehmen denselben JSON‑Body bei POST entgegen, oder dieselben Felder als Query‑String bei GET.

RouteHTTPZweck
/ticket-createPOSTTicket und ersten Artikel anlegen
/ticket-getPOSTEin Ticket lesen
/ticket-searchPOSTTicket‑IDs suchen
/ticket-updatePUTTicketfelder ändern
/agent-countGET, POSTGültige Agenten zählen
/queue-listGET, POSTQueues auflisten
/state-listGET, POSTStatus auflisten
/priority-listGET, POSTPrioritäten auflisten
/service-listGET, POSTServices auflisten
/type-listGET, POSTTypen auflisten
/dynamic-field-listGET, POSTDynamische Ticketfelder auflisten
/dynamic-field-valuesGET, POSTDropdown‑Werte eines Feldes
/dynamic-field-createPOSTDropdown‑Feld anlegen oder aktualisieren
/faq-searchGET, POSTFAQ‑Artikel suchen
/faq-getGET, POSTEinen FAQ‑Artikel lesen
/auth/customerPOSTKunden‑Portal‑Session öffnen
/auth/agentPOSTAgenten‑Portal‑Session öffnen
/portal/ticket-searchPOSTTickets der Portal‑Session
/portal/ticket-getPOSTEin Ticket der Portal‑Session
/portal/ticket-createPOSTTicket als Portal‑Session anlegen
/portal/ticket-articlePOSTArtikel als Portal‑Session hinzufügen
/portal/ticket-statePOSTStatus setzen (nur Agenten‑Session)
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"
}
}
Vollständige Antwort anzeigen (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"
}
Vollständige Antwort anzeigen
{
"Success": 1,
"Data": {
"Item": [{ "ID": 2, "Name": "Sales", "Comment": "", "Valid": 1 }]
}
}

/state-list, /priority-list, /service-list und /type-list nutzen denselben Request und dieselben Item‑Attribute.

AttributTypBeschreibung
IDIntegerKatalog‑ID
NameStringAnzeigename
CommentStringOptionaler Kommentar, kann leer sein
ValidInteger1, wenn der Eintrag gültig ist, sonst 0

GET oder POST /agent-count. Der Body enthält nur den API‑Benutzer. Die Zählung lässt die Logins otai-webservice und open_ticket_ai aus.

AttributTypPflichtBeschreibung
UserLoginStringJaAPI‑Agent des Connectors
PasswordStringJaPasswort dieses Agenten
CountInteger—Antwortfeld unter Data
Vollständige Antwort anzeigen
{
"Success": 1,
"Data": { "Count": 12 }
}

/dynamic-field-list liefert jedes dynamische Ticketfeld.

AttributTypBeschreibung
NameStringFeldname
LabelStringBezeichnung in der Agentenoberfläche
FieldTypeStringOTOBO‑Feldtyp, zum Beispiel Dropdown
ValidInteger1, wenn das Feld gültig ist
IsDropdownInteger1, wenn die Werte als Liste gelesen oder geschrieben werden
CommentStringOptionaler Kommentar

/dynamic-field-values braucht Name (Alias DynamicFieldName) und akzeptiert nur Dropdown‑Felder.

AttributTypPflichtBeschreibung
NameStringJaName des dynamischen Feldes
KeyString—Gespeicherter Wert, je Item
ValueString—Bezeichnung zu diesem Key
CommentString—Optionaler Kommentar zum Wert

POST /dynamic-field-create legt ein Ticket‑Dropdown an oder aktualisiert PossibleValues, wenn dieses Dropdown schon existiert. Ein Feld, das kein Ticket‑Dropdown ist, wird nicht überschrieben.

AttributTypPflichtBeschreibung
NameStringJaFeldname
LabelStringNeinStandard ist Name
PossibleValuesObjekt oder ListeJaHash aus Key → Bezeichnung, oder eine Liste von { "Key", "Value" }
ScreensString[]NeinSysConfig‑Einstellungen. Standard: Agent Zoom, Phone, Email, Freitext, Notiz
Vollständige Antwort anzeigen
{
"Success": 1,
"Data": {
"Name": "Department",
"Label": "Department",
"FieldID": 18,
"Created": 1,
"FieldType": "Dropdown",
"Item": [{ "Key": "sales", "Value": "Sales" }],
"EnabledScreens": ["Ticket::Frontend::AgentTicketZoom###DynamicField"]
}
}

/faq-search und /faq-get liefern Status: faq_unavailable, wenn das FAQ‑Paket nicht installiert ist. Ein fehlender Artikel liefert Status: not_found und eine leere Item‑Liste. Beides bleibt Success: 1.

AttributTypPflichtBeschreibung
WhatStringJa¹Suchtext. Alias: Query. Nur /faq-search
LimitIntegerNeinNur /faq-search. Standard 5, höchstens 20
VisibilityString[]Neinpublic, external oder internal. Alias: StateTypes
ItemIDIntegerJa²FAQ‑ID für /faq-get. Aliase: ID, Id

¹ Pflicht bei /faq-search. ² Pflicht bei /faq-get.

Suchtreffer nutzen ID, Number, Title, Snippet, URL, Path und State. /faq-get ergänzt CategoryID, CategoryName, Language, Keywords sowie Field1–Field6 mit passendem FieldNCaption.

Portal‑Routen behalten den API‑Benutzer des Connectors (UserLogin / Password) und ergänzen die Person, die sich anmeldet. Spätere Ticket‑Aufrufe senden die SessionID aus dieser Antwort zusammen mit dem API‑Benutzer.

AttributTypPflichtBeschreibung
UserLoginStringJaAPI‑Agent des Connectors
PasswordStringJaPasswort dieses Agenten
PersonLoginStringJaKunden‑ oder Agenten‑Login
PersonPasswordStringJaPasswort dieser Person
SessionIDString—Portal‑Session. Bei späteren Portal‑Aufrufen mitsenden
UserIDString—OTOBO‑Benutzer‑ID der angemeldeten Person
CustomerIDString—Nur bei /auth/customer
RoleString—customer oder agent
Vollständige Antwort anzeigen
{
"Success": 1,
"Data": {
"SessionID": "abc123session",
"UserID": "42",
"UserLogin": "kunde@example.com",
"CustomerID": "ACME",
"Role": "customer"
}
}

Jede Portal‑Ticket‑Route braucht UserLogin, Password und SessionID. Eine Kunden‑Session sieht nur Tickets dieses Kunden. Eine Agenten‑Session sieht nur Tickets, die dieser Agent lesen darf. Kunden können /portal/ticket-state nicht aufrufen.

AttributTypPflichtBeschreibung
SessionIDStringJaAus /auth/customer oder /auth/agent
LimitIntegerNein/portal/ticket-search. Standard 50, höchstens 200
TicketIDIntegerJa¹Pflicht bei Abruf, Artikel und Status
Ticket.TitleStringJa²Oder Article.Subject. Queue standardmäßig Raw, Status new, Priorität 3 normal
Ticket.CustomerUserStringJa³Bei einer Kunden‑Session ignoriert; dort gilt der angemeldete Login
Article.BodyStringJa⁴Pflicht bei /portal/ticket-article. Beim Anlegen optional
Article.SubjectStringNeinStandard ist der Tickettitel oder Portal
StateStringJa⁵Neuer Statusname. Nur Agenten‑Session

¹ /portal/ticket-get, /portal/ticket-article, /portal/ticket-state. ² /portal/ticket-create. ³ Agenten‑Session beim Anlegen. ⁴ /portal/ticket-article. ⁵ /portal/ticket-state.

Jedes Ticket in Data.Ticket (ein Objekt, bei der Suche eine Liste) hat TicketID, TicketNumber, Title, State, Queue, Priority, Type, Service, CustomerUser, Owner, Created, Changed und Article. Kunden‑Sessions lassen Artikel weg, die für den Kunden nicht sichtbar sind. Ein Artikel hat ArticleID, Subject, Body, From, SenderType, Created und IsVisibleForCustomer. /portal/ticket-article liefert zusätzlich ArticleID neben Ticket.

Vollständige Antwort anzeigen
{
"Success": 1,
"Data": {
"Ticket": {
"TicketID": "12345",
"TicketNumber": "202601010001",
"Title": "Neue Bestellung",
"State": "new",
"Queue": "Raw",
"Priority": "3 normal",
"Type": "",
"Service": "",
"CustomerUser": "kunde@example.com",
"Owner": "kunde@example.com",
"Created": "2026-01-01 10:00:00",
"Changed": "2026-01-01 10:00:00",
"Article": [
{
"ArticleID": "67890",
"Subject": "Neue Bestellung",
"Body": "Bitte um ein Preisangebot.",
"From": "kunde@example.com",
"SenderType": "customer",
"Created": "2026-01-01 10:00:00",
"IsVisibleForCustomer": 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 den Connector‑Webservice ab: Tickets, Katalog, FAQ, dynamische Felder und die Portal‑Session‑Routen. Standard‑Generic‑Interface‑Webservices mit eigenen Routen sind davon nicht abgedeckt — dort gelten Ihre YAML‑Transport‑Mappings. Beispielantworten auf dieser Seite sind zugeklappt; öffnen Sie Vollständige Antwort anzeigen, wenn Sie das JSON brauchen.

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 PyPI‑Pakete otobo und znuny. Der Client ist standalone: eigene Skripte und Integrationen brauchen kein Open Ticket AI. Open Ticket AI spricht OTOBO über denselben Connector.

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.