description: Uitgebreide handleiding voor OTOBO / Znuny Web Services (REST), van configuratie tot voorbeelden, met afbeeldingen en tabellen.

OTOBO / Znuny Web Services – REST API

In deze uitgebreide handleiding leert u hoe u de OTOBO REST API (onderdeel van de Generic Interface) activeert, configureert en integreert in uw eigen applicaties.

1. Architectuur & Grondbeginselen

OTOBO biedt zijn Generic Interface via REST- en SOAP-webservices. De REST API communiceert via HTTP(S)/JSON en maakt het volgende mogelijk:

• Ticket-operaties: Aanmaken, ophalen, wijzigen, verwijderen
• Artikel-operaties: Posten, bijlagen beheren
• Geschiedenis & Zoeken: Ticketgeschiedenis en complexe zoekopdrachten

Opmerking: Een standaardinstallatie bevat geen vooraf geconfigureerde webservices – u maakt deze zelf aan in de adminmodule „Processen & Automatisering → Web Services“.

2. Configuratie

2.1 Generic Interface activeren

1. Ga in het admin-gedeelte naar SysConfig → GenericInterface.Transport en schakel over naar REST (HTTP).
2. Stel onder AdminGenericInterfaceTransportHTTPREST Timeouts, Host-headers en Debug-niveau in.
3. Maak en activeer de gewenste operaties (bijv. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) onder GenericInterface.Operation.

2.2 Basis-URL & Authenticatie

• Basis-URL

  https://UW-SERVER/otobo/nph-genericinterface.pl/Webservice/<UwServiceName>/

• Authenticatie

  • OTOBO-sessiecookies
  • API-sleutels / Tokens (aanmaken via SysConfig)
  • Gebruik altijd HTTPS!

3. Endpoints & HTTP-Methoden (Detail)

Voor elke endpoint vindt u hier een gedetailleerd overzicht van parameters, mogelijke antwoorden en praktijkvoorbeelden.

3.1 TicketCreate (POST)

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

Beschrijving: Maakt een nieuw ticket aan en creëert direct een artikel.

Parameter	Type	Vereist	Beschrijving
SessionID	Integer	Ja¹	Sessie-ID of UserLogin+Password
UserLogin	String	Ja²	Agent-login (in combinatie met Password)
Password	String	Ja²	Wachtwoord (in combinatie met UserLogin)
Ticket.Title	String	Ja	Onderwerp van het ticket
Ticket.Queue	String	Ja	Queue-naam of Ticket.QueueID
Ticket.State	String	Ja	Beginstatus (bijv. new)
Ticket.Priority	String	Ja	Prioriteit (bijv. 3 normal)
Ticket.CustomerUser	String	Ja	Klant-e-mail of login
Article.Subject	String	Ja	Onderwerp van het eerste artikel
Article.Body	String	Ja	Inhoud van het eerste artikel
Article.MimeType	String	Ja	text/plain of text/html

¹ Ofwel SessionID OF UserLogin+Password vereist. ² Indien geen SessionID-token wordt meegegeven.

Voorbeeld 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":        "Nieuwe bestelling",
      "Queue":        "Sales",
      "State":        "new",
      "Priority":     "3 normal",
      "CustomerUser": "max.mustermann@example.com"
    },
    "Article": {
      "Subject":  "Prijsaanvraag – Product XY",
      "Body":     "Graag prijsopgave…",
      "MimeType": "text/plain"
    }
  }
}

Voorbeeld Antwoord:

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

3.2 TicketSearch (GET)

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

Beschrijving: Zoekt tickets op basis van diverse filtercriteria.

Parameter	Type	Vereist	Beschrijving
UserLogin, Password	String,String	Ja¹	Agent-credentials of SessionID²
SessionID	Integer	Ja²	Token voor geauthenticeerde sessies
Title	String/String[]	Nee	Wildcard-zoekopdracht in de titel (%Bestelling%)
TicketNumber	String/String[]	Nee	Ticketnummer(s)
QueueIDs	Integer[]	Nee	Queue-ID's
States	String[]	Nee	Statussen (new, open, …)
StateType	String/String[]	Nee	Open/Closed-categorie
DynamicField_Name.Op	Mixed	Nee	Dynamische velden met operator (Equals, Like, GreaterThan …)

¹ Ofwel UserLogin+Password OF SessionID. ² Indien geen login-paar wordt meegegeven.

Voorbeeld Request:

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

Voorbeeld Antwoord:

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

3.3 TicketGet (GET)

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

Beschrijving: Geeft gedetailleerde ticketgegevens terug, inclusief artikelen, bijlagen en dynamische velden.

Parameter	Type	Vereist	Beschrijving
UserLogin, Password	String,String	Ja¹	Agent-credentials of SessionID²
SessionID	Integer	Ja²	Token voor geauthenticeerde sessies
TicketID	String/String[]	Ja	Eén of meerdere ticket-ID's (komma-gescheiden of array)
DynamicFields	Boolean (0/1)	Nee	1 = Dynamische velden in het resultaat, Standaard = 0
Extended	Boolean	Nee	1 = Uitgebreide metadata (bijv. FirstResponse)
AllArticles	Boolean	Nee	1 = Alle artikelen teruggeven
ArticleLimit	Integer	Nee	Max. aantal teruggegeven artikelen
Attachments	Boolean	Nee	1 = Bijlagen in Base64 insluiten
GetAttachmentContents	Boolean	Nee	1 = Inhoud van bijlagen ook laden
HTMLBodyAsAttachment	Boolean	Nee	1 = HTML-versie van het artikel als bijlage toevoegen

¹ Ofwel UserLogin+Password OF SessionID. ² Indien geen login-paar wordt meegegeven.

Voorbeeld Request:

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

Voorbeeld Antwoord (ingekort):

{
  "Success":1,
  "Data":{
    "Ticket":[{
      "TicketID":12345,
      "TicketNumber":"202501230001",
      "Title":"Nieuwe bestelling",
      "State":"open",
      "DynamicField":[{"Name":"Urgency","Value":"high"}],
      "Article":[{
        "ArticleID":67890,
        "Subject":"Prijsaanvraag…",
        "Body":"Graag prijsopgave…",
        "Attachment":[{"Filename":"Angebot.pdf","Content":"JVBERi0x…="}]
      }]
    }]
  }
}

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdateMethode: PUT

Beschrijving: Werkt velden van een bestaand ticket bij en maakt optioneel een nieuw artikel aan.

Parameter	Type	Vereist	Beschrijving
SessionID	Integer	Ja¹	Token of UserLogin+Password²
TicketID	Integer	Ja	ID van het bij te werken ticket
Ticket.Title	String	Nee	Nieuwe titel
Ticket.State	String	Nee	Nieuwe status
Ticket.Owner	String/ID	Nee	Nieuwe eigenaar
Ticket.PendingTime	Hash / Diff	Nee	Nieuwe pending-tijd
Article.Subject	String	Nee	Creëert een nieuw artikel
Article.Body	String	Nee	Inhoud van het nieuwe artikel
DynamicField…	Array	Nee	Dynamische velden bijwerken
Attachment…	Array	Nee	Nieuwe bijlagen toevoegen

¹ Ofwel SessionID OF UserLogin+Password. ² Indien geen SessionID-token wordt meegegeven.

Voorbeeld 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":"Herinnering ingesteld","Body":"Ticket wordt verwerkt." }
  }
}

Voorbeeld Antwoord:

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

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDeleteMethode: DELETE

Beschrijving: Verwijdert definitief één of meerdere tickets.

Parameter	Type	Vereist	Beschrijving
SessionID	Integer	Ja¹	Token of UserLogin+Password²
TicketID	String/Array	Ja	Eén of meerdere ticket-ID's

Voorbeeld Request:

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

Voorbeeld Antwoord:

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

3.6 TicketHistoryGet (GET)

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

Beschrijving: Haalt de geschiedenis van één of meerdere tickets op.

Parameter	Type	Vereist	Beschrijving
SessionID	Integer	Ja¹	Token of UserLogin+Password²
TicketID	String/Array	Ja	Eén of meerdere ticket-ID's

Voorbeeld Request:

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

5. Uitbreiding & Aanpassing

5.1 WADL-definitie

Nieuwe resources 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

Alternatief via YAML in development/webservices/GenericTicketConnectorREST.yml:

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

---

6. Foutafhandeling & Logging

• Succesindicator: Success: 0|1
• Foutmelding: ErrorMessage in de JSON
• Debugging: Stel in het transportdialoogvenster Debug-niveau in op Debug → Logboekvermeldingen zichtbaar in de database

---

7. Gebruiksscenario's

Scenario	Beschrijving
Systeem-overkoepelende automatisering	Tickets aanmaken vanuit monitoringtools (Nagios, Zabbix)
Gegevenssynchronisatie	Batch-updates van ticketvelden vanuit externe CRM
Self-service portals	Klanten maken zelf tickets aan via REST
Mobiele apps	Native iOS/Android-apps communiceren via REST

---

8. Verdere UI-elementen & Integratie

Web Service Klonen

Error Handling Module

Conclusie

De OTOBO REST API is flexibel, performant en dankzij de Generic Interface zeer uitbreidbaar. Of het nu gaat om eenvoudige ticket-aanmaak of complexe workflow-automatisering – met een paar klikken in de admin en standaard JSON-requests realiseert u naadloze integraties in elk IT-landschap.

Python OTOBO Client Library

Een asynchrone Python client voor interactie met de OTOBO REST API. Gebouwd met httpx en pydantic voor typeveiligheid en gebruiksgemak.

Kenmerken

• Asynchrone HTTP-verzoeken met httpx.AsyncClient

• Pydantic modellen voor validatie van request- en responsegegevens

• Volledige CRUD-operaties voor tickets:

  • TicketCreate
  • TicketSearch
  • TicketGet
  • TicketUpdate
  • TicketHistoryGet

• Foutafhandeling via OTOBOError voor API-fouten

• Hulpmethode search_and_get om zoekresultaten te combineren met gedetailleerde ophaalacties

Installatie

Installeren vanaf PyPI:

pip install otobo

Quickstart

OTOBO Webservices configureren:

Maak een nieuwe webservice aan in OTOBO met de volgende configuratie:

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

Maak een nieuwe Agent aan

Maak een nieuwe Otobo Agent aan met een veilig wachtwoord en geef deze de benodigde rechten voor de gewenste actie.

1. Configureer de client

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. Initialiseer de client

import logging
from otobo import OTOBOClient

logging.basicConfig(level=logging.INFO)


client = OTOBOClient(config)

3. Maak een ticket aan

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

payload = TicketCreateParams(
    Ticket={
        "Title": "Nieuwe bestelling",
        "Queue": "Sales",
        "State": "new",
        "Priority": "3 normal",
        "CustomerUser": "customer@example.com"
    },
    Article={
        "Subject": "Productaanvraag",
        "Body": "Graag prijsdetails...",
        "MimeType": "text/plain"
    }
)

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

4. Zoek en haal tickets op

from otobo import TicketSearchParams, TicketGetParams

search_params = TicketSearchParams(Title="%Bestelling%")
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. Werk een ticket bij

from otobo import TicketUpdateParams

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

6. Haal ticketgeschiedenis op

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. Gecombineerd zoeken en ophalen

from otobo import FullTicketSearchResponse

full_res: FullTicketSearchResponse = await client.search_and_get(search_params)

Licentie

MIT © Softoft, Tobias A. Bueck