Web Services OTOBO – REST API

OTOBO REST API

Dans ce guide détaillé, vous apprendrez comment activer, configurer et intégrer l’API REST OTOBO (partie de l’Interface Générique) dans vos propres applications.

1. Architecture & Principes de base

OTOBO met à disposition son Interface Générique via des Web Services REST et SOAP. L’API REST communique via HTTP(S)/JSON et permet :

Opérations sur les tickets : Créer, récupérer, modifier, supprimer
Opérations sur les articles : Publier, gérer les pièces jointes
Historique & Recherche : Historique des tickets et requêtes de recherche complexes

Remarque : Une installation standard ne contient aucun Web Service préconfiguré – vous devez les créer vous-même dans le module d’administration « Processus & Automatisation → Web Services ».

2. Configuration

2.1 Activer l’Interface Générique

Dans la zone d’administration → SysConfig → GenericInterface.Transport, passez à REST (HTTP).
Sous AdminGenericInterfaceTransportHTTPREST, configurez les timeouts, l’en-tête Host et le niveau de debug.
Dans GenericInterface.Operation, créez et activez les opérations souhaitées (par ex. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet).

Ajouter un Web Service Fournisseur de Web Service

2.2 URL de base & Authentification

URL de base

https://VOTRE-SERVEUR/otobo/nph-genericinterface.pl/Webservice/<VotreNomDeService>/

Authentification
- Cookies de session OTOBO
- Clés API / Token (à créer via SysConfig)
- Toujours utiliser HTTPS !

Configurer le Requester REST

3. Endpoints & Méthodes HTTP (Détail)

Pour chaque endpoint, vous trouverez ici un aperçu détaillé des paramètres, des réponses possibles et des exemples pratiques.

3.1 TicketCreate (POST)

URL : /Webservice/<ServiceName>/TicketCreate Méthode : POST

Description : Crée un nouveau ticket et génère immédiatement un article.

Paramètre	Type	Requis	Description
SessionID	Integer	Oui¹	ID de session ou UserLogin+Password
UserLogin	String	Oui²	Login de l’agent (en combinaison avec Password)
Password	String	Oui²	Mot de passe (en combinaison avec UserLogin)
Ticket.Title	String	Oui	Objet du ticket
Ticket.Queue	String	Oui	Nom de la file ou Ticket.QueueID
Ticket.State	String	Oui	État initial (par ex. `new`)
Ticket.Priority	String	Oui	Priorité (par ex. `3 normal`)
Ticket.CustomerUser	String	Oui	E-mail ou login du client
Article.Subject	String	Oui	Objet du premier article
Article.Body	String	Oui	Contenu du premier article
Article.MimeType	String	Oui	`text/plain` ou `text/html`

¹ Soit SessionID OU UserLogin+Password requis. ² Si aucun token SessionID n’est disponible.

Exemple de requête :

POST /Webservice/MyConnectorREST/TicketCreate HTTP/1.1
Host: demo.otobo.org
Content-Type: application/json
X-API-Key: abc123

{
  "Data": {
    "SessionID":  42,
    "Ticket": {
      "Title":        "Nouvelle commande",
      "Queue":        "Sales",
      "State":        "new",
      "Priority":     "3 normal",
      "CustomerUser": "max.mustermann@example.com"
    },
    "Article": {
      "Subject":  "Demande d'achat – Produit XY",
      "Body":     "Veuillez envoyer une offre de prix…",
      "MimeType": "text/plain"
    }
  }
}

Exemple de réponse :

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

3.2 TicketSearch (GET)

URL : /Webservice/<ServiceName>/TicketSearch Méthode : GET

Description : Recherche des tickets selon divers critères de filtrage.

Paramètre	Type	Requis	Description
UserLogin, Password	String,String	Oui¹	Identifiants de l’agent ou SessionID²
SessionID	Integer	Oui²	Token pour les sessions authentifiées
Title	String/String[]	Non	Recherche par wildcard dans le titre (`%Commande%`)
TicketNumber	String/String[]	Non	Numéro(s) de ticket
QueueIDs	Integer[]	Non	IDs des files
States	String[]	Non	États (`new`, `open`, …)
StateType	String/String[]	Non	Catégorie Open/Closed
DynamicField_Name.Op	Mixed	Non	Champs dynamiques avec opérateur (Equals, Like, GreaterThan …)

¹ Soit UserLogin+Password OU SessionID. ² Si aucun couple de login n’est transmis.

Exemple de requête :

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

Exemple de réponse :

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

3.3 TicketGet (GET)

URL : /Webservice/<ServiceName>/TicketGet Méthode : GET

Description : Renvoie les données détaillées du ticket, y compris les articles, les pièces jointes et les champs dynamiques.

Paramètre	Type	Requis	Description
UserLogin, Password	String,String	Oui¹	Identifiants de l’agent ou SessionID²
SessionID	Integer	Oui²	Token pour les sessions authentifiées
TicketID	String/String[]	Oui	Un ou plusieurs IDs de ticket (séparés par virgule ou tableau)
DynamicFields	Boolean (0/1)	Non	1 = Champs dynamiques dans le résultat, défaut = 0
Extended	Boolean	Non	1 = Métadonnées étendues (par ex. FirstResponse)
AllArticles	Boolean	Non	1 = Renvoyer tous les articles
ArticleLimit	Integer	Non	Nombre max. d’articles renvoyés
Attachments	Boolean	Non	1 = Intégrer les pièces jointes en Base64
GetAttachmentContents	Boolean	Non	1 = Charger également le contenu des pièces jointes
HTMLBodyAsAttachment	Boolean	Non	1 = Ajouter la version HTML de l’article en pièce jointe

¹ Soit UserLogin+Password OU SessionID. ² Si aucun couple de login n’est transmis.

Exemple de requête :

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

Exemple de réponse (tronqué) :

{
  "Success":1,
  "Data":{
    "Ticket":[{
      "TicketID":12345,
      "TicketNumber":"202501230001",
      "Title":"Nouvelle commande",
      "State":"open",
      "DynamicField":[{"Name":"Urgency","Value":"high"}],
      "Article":[{
        "ArticleID":67890,
        "Subject":"Demande d'achat…",
        "Body":"Veuillez envoyer une offre de prix…",
        "Attachment":[{"Filename":"Offre.pdf","Content":"JVBERi0x…="}]
      }]
    }]
  }
}

3.4 TicketUpdate (PUT)

URL : /Webservice/<ServiceName>/TicketUpdate Méthode : PUT

Description : Met à jour les champs d’un ticket existant et crée éventuellement un nouvel article.

Paramètre	Type	Requis	Description
SessionID	Integer	Oui¹	Token ou UserLogin+Password²
TicketID	Integer	Oui	ID du ticket à mettre à jour
Ticket.Title	String	Non	Nouveau titre
Ticket.State	String	Non	Nouvel état
Ticket.Owner	String/ID	Non	Nouveau propriétaire
Ticket.PendingTime	Hash / Diff	Non	Nouveau temps d’attente
Article.Subject	String	Non	Crée un nouvel article
Article.Body	String	Non	Contenu du nouvel article
DynamicField…	Array	Non	Mettre à jour les champs dynamiques
Attachment…	Array	Non	Ajouter de nouvelles pièces jointes

¹ Soit SessionID OU UserLogin+Password. ² Si aucun token SessionID n’est disponible.

Exemple de requête :

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":"Rappel défini","Body":"Le ticket est en cours de traitement." }
  }
}

Exemple de réponse :

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

3.5 TicketDelete (DELETE)

URL : /Webservice/<ServiceName>/TicketDelete Méthode : DELETE

Description : Supprime définitivement un ou plusieurs tickets.

Paramètre	Type	Requis	Description
SessionID	Integer	Oui¹	Token ou UserLogin+Password²
TicketID	String/Array	Oui	Un ou plusieurs IDs de ticket

Exemple de requête :

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

Exemple de réponse :

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

3.6 TicketHistoryGet (GET)

URL : /Webservice/<ServiceName>/TicketHistoryGet Méthode : GET

Description : Récupère l’historique d’un ou plusieurs tickets.

Paramètre	Type	Requis	Description
SessionID	Integer	Oui¹	Token ou UserLogin+Password²
TicketID	String/Array	Oui	Un ou plusieurs IDs de ticket

Exemple de requête :

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

5. Extension & Personnalisation

5.1 Définition WADL

Nouvelles ressources dans 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 Import YAML

Alternativement via YAML dans development/webservices/GenericTicketConnectorREST.yml :

Provider:
  Operation:
    MyTest:
      Description: "Opération de test"
      MappingInbound: { }
      MappingOutbound: { }
      Type: Test::Module
Transport:
  Config:
RouteOperationMapping:
  MyTest:
    RequestMethod: [ GET ]
    Route: /MyTest

Ajouter un fournisseur SOAP

6. Gestion des erreurs & Logging

Indicateur de succès : Success: 0|1
Message d’erreur : ErrorMessage dans le JSON
Debugging : Dans la boîte de dialogue Transport, réglez Debug-Level sur Debug → entrées de log visibles dans la DB

Debugger de Web Service

7. Cas d’utilisation

Scénario	Description
Automatisation inter-systèmes	Créer des tickets à partir d’outils de monitoring (Nagios, Zabbix)
Synchronisation de données	Mises à jour par lots des champs de ticket depuis un CRM externe
Portails Self-Service	Les clients créent leurs propres tickets via REST
Applications mobiles	Les applications natives iOS/Android communiquent via REST

8. Autres éléments UI & Intégration

Cloner un Web Service

Module de gestion des erreurs

Conclusion

L’API REST OTOBO est flexible, performante et hautement extensible grâce à l’Interface Générique. Qu’il s’agisse d’une simple création de ticket ou d’une automatisation de workflow complexe, vous réalisez des intégrations transparentes dans n’importe quel paysage informatique en quelques clics dans l’Admin et avec des requêtes JSON standard.

Bibliothèque cliente Python OTOBO

Un client Python asynchrone pour interagir avec l’API REST OTOBO. Construit avec httpx et pydantic pour la sécurité des types et la facilité d’utilisation.

Fonctionnalités

Requêtes HTTP asynchrones utilisant httpx.AsyncClient
Modèles Pydantic pour la validation des données de requête et de réponse
Opérations CRUD complètes pour les tickets :
- TicketCreate
- TicketSearch
- TicketGet
- TicketUpdate
- TicketHistoryGet
Gestion des erreurs via OTOBOError pour les erreurs d’API
Méthode utilitaire search_and_get pour combiner les résultats de recherche avec une récupération détaillée

Installation

Installer depuis PyPI :

pip install otobo

Démarrage rapide

Configurer les Web Services OTOBO :

Créez un nouveau Web Service dans OTOBO avec la configuration suivante :

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

Créer un nouvel agent

Créez un nouvel agent Otobo avec un mot de passe sécurisé et donnez-lui les permissions nécessaires pour accomplir la tâche souhaitée.

1. Configurer le 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. Initialiser le client

import logging
from otobo import OTOBOClient

logging.basicConfig(level=logging.INFO)


client = OTOBOClient(config)

3. Créer un ticket

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

payload = TicketCreateParams(
    Ticket={
        "Title": "Nouvelle commande",
        "Queue": "Sales",
        "State": "new",
        "Priority": "3 normal",
        "CustomerUser": "customer@example.com"
    },
    Article={
        "Subject": "Demande de produit",
        "Body": "Veuillez envoyer les détails de prix...",
        "MimeType": "text/plain"
    }
)

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

4. Rechercher et récupérer des tickets

from otobo import TicketSearchParams, TicketGetParams

search_params = TicketSearchParams(Title="%Commande%")
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. Mettre à jour un ticket

from otobo import TicketUpdateParams

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

6. Obtenir l’historique d’un ticket

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. Recherche et récupération combinées

from otobo import FullTicketSearchResponse

full_res: FullTicketSearchResponse = await client.search_and_get(search_params)

Web Services OTOBO – REST API

Web Services OTOBO – REST API

1. Architecture & Principes de base

2. Configuration

2.1 Activer l’Interface Générique

2.2 URL de base & Authentification

3. Endpoints & Méthodes HTTP (Détail)

3.1 TicketCreate (POST)

3.2 TicketSearch (GET)

3.3 TicketGet (GET)

3.4 TicketUpdate (PUT)

3.5 TicketDelete (DELETE)

3.6 TicketHistoryGet (GET)

5. Extension & Personnalisation

5.1 Définition WADL

5.2 Import YAML

6. Gestion des erreurs & Logging

7. Cas d’utilisation

8. Autres éléments UI & Intégration

Cloner un Web Service

Module de gestion des erreurs

Conclusion

Bibliothèque cliente Python OTOBO

Fonctionnalités

Installation

Démarrage rapide

Configurer les Web Services OTOBO :

Créer un nouvel agent

1. Configurer le client

2. Initialiser le client

3. Créer un ticket

4. Rechercher et récupérer des tickets

5. Mettre à jour un ticket

6. Obtenir l’historique d’un ticket

7. Recherche et récupération combinées

Licence