OTOBO

OTOBO / Znuny Web Services – REST API ​

OTOBO 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.

Web Service HinzufügenWeb Service Provider

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!

REST Requester einrichten

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.

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:

http
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:

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

3.2 TicketSearch (GET) ​

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

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

Beispiel Antwort:

json
{
  "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.

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:

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

Beispiel Antwort (gekürzt):

json
{
  "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.

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:

http
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:

json
{ "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.

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

Beispiel Request:

http
DELETE /Webservice/MyConnectorREST/TicketDelete?SessionID=42&TicketID=12345 HTTP/1.1
Host: demo.otobo.org

Beispiel Antwort:

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

3.6 TicketHistoryGet (GET) ​

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

Beschreibung: Ruft die Historie eines oder mehrerer Tickets ab.

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

Beispiel Request:

http
GET /Webservice/MyConnectorREST/TicketHistoryGet?SessionID=42&TicketID=12345,

5. Erweiterung & Anpassung ​

5.1 WADL‑Definition ​

Neue Ressourcen in GenericTicketConnectorREST.wadl:

xml
<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:

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

SOAP Provider hinzufügen

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

Webservice‑Debugger

7. Anwendungsfälle ​

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

8. Weitere UI‑Elemente & Integration ​

Web Service Klonen ​

Webservice klonen

Error Handling Modul ​

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.

Python OTOBO Client Library ​

An asynchronous Python client for interacting with the OTOBO REST API. Built with httpx and pydantic for type safety and ease of use.

Features ​

  • Asynchronous HTTP requests using httpx.AsyncClient

  • Pydantic models for request and response data validation

  • Full CRUD operations for tickets:

    • TicketCreate
    • TicketSearch
    • TicketGet
    • TicketUpdate
    • TicketHistoryGet

  • Error handling via OTOBOError for API errors

  • Utility method search_and_get to combine search results with detailed retrieval

Installation ​

Install from PyPI:

bash
pip install otobo

Quickstart ​

Setup OTOBO Webservices: ​

Create a new web service in OTOBO with the following configuration:

yaml
---
Debugger:
  DebugThreshold: debug
  TestMode: '0'
Description: ''
FrameworkVersion: 11.0.5
Provider:
  Operation:
    session-create:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Session::SessionCreate
    ticket-create:
      Description: ''
      IncludeTicketData: '1'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketCreate
    ticket-get:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Config:
          KeyMapDefault:
            MapTo: ''
            MapType: Keep
          ValueMapDefault:
            MapTo: ''
            MapType: Keep
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketGet
    ticket-history-get:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketHistoryGet
    ticket-search:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketSearch
    ticket-update:
      Description: ''
      IncludeTicketData: '1'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketUpdate
  Transport:
    Config:
      AdditionalHeaders: ~
      KeepAlive: '1'
      MaxLength: '16000'
      RouteOperationMapping:
        session-create:
          RequestMethod:
            - HEAD
            - OPTIONS
            - PATCH
            - POST
            - PUT
          Route: /session
        ticket-create:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket
        ticket-get:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket/get
        ticket-history-get:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket/history
        ticket-search:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket/search
        ticket-update:
          RequestMethod:
            - HEAD
            - OPTIONS
            - PATCH
            - PUT
          Route: /ticket
    Type: HTTP::REST
RemoteSystem: ''
Requester:
  Transport:
    Type: HTTP::REST

Create a new Agent ​

Create a new Otobo Agent with a secure password and give it the permissions needed for the thing you want to accomplish.

1. Configure the client ​

python
from otobo import TicketOperation, OTOBOClientConfig
from otobo import AuthData

config = OTOBOClientConfig(
    base_url="https://your-otobo-server/nph-genericinterface.pl",
    service="OTOBO",
    auth=AuthData(UserLogin="user1", Password="SecurePassword"),
    operations={
        TicketOperation.CREATE.value: "ticket",
        TicketOperation.SEARCH.value: "ticket/search",
        TicketOperation.GET.value: "ticket/get",
        TicketOperation.UPDATE.value: "ticket",
        TicketOperation.HISTORY_GET.value: "ticket/history",
    }
)

2. Initialize the client ​

python
import logging
from otobo import OTOBOClient

logging.basicConfig(level=logging.INFO)


client = OTOBOClient(config)

3. Create a ticket ​

python
from otobo import (TicketOperation, OTOBOClientConfig, AuthData, TicketSearchParams, TicketCreateParams,
                   TicketHistoryParams, TicketUpdateParams, \
                   TicketGetParams, OTOBOClient, OTOBOTicketCreateResponse)

payload = TicketCreateParams(
    Ticket={
        "Title": "New Order",
        "Queue": "Sales",
        "State": "new",
        "Priority": "3 normal",
        "CustomerUser": "customer@example.com"
    },
    Article={
        "Subject": "Product Inquiry",
        "Body": "Please send pricing details...",
        "MimeType": "text/plain"
    }
)

response: OTOBOTicketCreateResponse = await client.create_ticket(payload)
print(response.TicketID, response.TicketNumber)

4. Search and retrieve tickets ​

python
from otobo import TicketSearchParams, TicketGetParams

search_params = TicketSearchParams(Title="%Order%")
search_res = await client.search_tickets(search_params)
ids = search_res.TicketID

for ticket_id in ids:
    get_params = TicketGetParams(TicketID=ticket_id, AllArticles=1)
    details = await client.get_ticket(get_params)
    print(details.Ticket[0])

5. Update a ticket ​

python
from otobo import TicketUpdateParams

update_params = TicketUpdateParams(
    TicketID=response.TicketID,
    Ticket={"State": "closed"}
)
await client.update_ticket(update_params)

6. Get ticket history ​

python
from otobo import TicketHistoryParams

history_params = TicketHistoryParams(TicketID=str(response.TicketID))
history_res = await client.get_ticket_history(history_params)
print(history_res.History)

7. Combined search and get ​

python
from otobo import FullTicketSearchResponse

full_res: FullTicketSearchResponse = await client.search_and_get(search_params)

License ​

MIT © Softoft, Tobias A. Bueck