Znuny Web Services – REST API

Znuny Web Services – REST API

Dans ce guide détaillé, vous apprendrez comment activer, configurer et intégrer la Znuny REST API (partie du Generic Interface) dans vos propres applications.

1. Architecture & principes de base

Znuny met à disposition son Generic Interface via des Web Services REST et SOAP. La REST API communique via HTTP(S) avec le format de données JSON et permet :

• Gestion des tickets : Créer, récupérer, modifier, supprimer
• Gestion des articles : Ajouter des articles, gérer les pièces jointes
• Historique & recherche : Consulter l’historique des tickets et effectuer des recherches complexes

Remarque importante : Une installation standard ne contient aucun Web Service préconfiguré – ceux-ci doivent être créés manuellement dans la zone d’administration sous « Processus & Automatisation → Web Services ».

2. Configuration

2.1 Activer le Generic Interface

1. Naviguez dans la zone d’administration vers SysConfig → GenericInterface.Transport et sélectionnez REST (HTTP).
2. Sous AdminGenericInterfaceTransportHTTPREST, configurez les timeouts, les en-têtes d’hôte (Host-Header) et le niveau de débogage (Debug-Level).
3. Dans GenericInterface.Operation, créez les opérations souhaitées (par ex. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) et activez-les.

2.2 URL de base & authentification

• URL de base TicketCreate
• Authentification
  • Cookies de session Znuny
  • API-Keys / Token (configurables via SysConfig)
  • Utilisez toujours HTTPS pour des transferts sécurisés !

3. Endpoints & méthodes HTTP (aperçu détaillé)

Pour chaque endpoint, vous trouverez ici une présentation détaillée 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 ajoute simultanément un premier article.

Paramètre	Type	Obligatoire	Description
SessionID	Integer	Oui¹	Session-ID 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 d’attente 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 présent.

Exemple de Request: TicketSearch Exemple de réponse: TicketGet

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch Méthode: GET Description: Recherche des tickets selon divers critères de filtrage.

Paramètre	Type	Obligatoire	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 d’attente
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 Request: TicketUpdate Exemple de réponse: TicketDelete

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Méthode: GET Description: Récupère les données détaillées d’un ticket, y compris les articles, les pièces jointes et les champs dynamiques.

Paramètre	Type	Obligatoire	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 Ticket-IDs (séparés par virgule ou tableau)
DynamicFields	Boolean (0/1)	Non	1 = Champs dynamiques dans le résultat, par défaut = 0
Extended	Boolean	Non	1 = Métadonnées étendues (par ex. FirstResponse)
AllArticles	Boolean	Non	1 = Retourner tous les articles
ArticleLimit	Integer	Non	Nombre max. d’articles retourné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 = Joindre 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 Request: TicketHistoryGet Exemple de réponse (abrégé): /Webservice/<ServiceName>/TicketCreate

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Méthode: PUT Description: Met à jour les champs d’un ticket existant et peut optionnellement créer un nouvel article.

Paramètre	Type	Obligatoire	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 présent.

Exemple de Request: POST Exemple de réponse: new

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete Méthode: DELETE Description: Supprime définitivement un ou plusieurs tickets.

Paramètre	Type	Obligatoire	Description
SessionID	Integer	Oui¹	Token ou UserLogin+Password²
TicketID	String/Array	Oui	Un ou plusieurs Ticket-IDs
Exemple de Request:
3 normal
Exemple de réponse:
text/plain

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	Obligatoire	Description
SessionID	Integer	Oui¹	Token ou UserLogin+Password²
TicketID	String/Array	Oui	Un ou plusieurs Ticket-IDs
Exemple de Request:
text/html

4. Extension & personnalisation

4.1 Définition WADL

Définir de nouvelles ressources dans le fichier WADL : /Webservice/<ServiceName>/TicketSearch

4.2 Import YAML

Alternativement, vous pouvez définir des opérations via YAML : GET

---

5. Gestion des erreurs & Logging

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

---

6. 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 tickets 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

---

Conclusion

La Znuny REST API est flexible, performante et hautement extensible grâce au Generic Interface. Qu’il s’agisse d’une simple création de ticket ou d’une automatisation de workflow complexe, vous pouvez réaliser des intégrations fluides dans n’importe quel environnement IT avec quelques étapes dans la zone d’administration et des requêtes JSON standard.

---

7. Client Python : pyznuny

Pour les développeurs Python, le package officiel pyznuny est disponible, encapsulant toute la Znuny REST API dans une bibliothèque simple et typée. Vous n’avez pas besoin de formuler des requêtes HTTP manuellement – pyznuny gère l’authentification, la gestion de session et la sérialisation de tous les paramètres.

7.1 Installation

pip install pyznuny

7.2 Démarrage rapide

from pyznuny import ZnunyClient

client = ZnunyClient(
    url="https://znuny.example.com",
    username="admin",
    password="geheim"
)

# Créer un ticket
ticket_id = client.ticket_create(
    title="Serveur inaccessible",
    queue="Support",
    state="new",
    priority="3 normal",
    customer_user="client@example.com",
    article_subject="Rapport initial",
    article_body="Le serveur ne répond plus depuis 08:00.",
    mime_type="text/plain"
)
print(f"Nouveau ticket créé : #{ticket_id}")

# Récupérer un ticket
ticket = client.ticket_get(ticket_id=ticket_id, all_articles=True)
print(ticket)

# Mettre à jour un ticket
client.ticket_update(ticket_id=ticket_id, state="open", owner="max.muster")

7.3 Opérations supportées

Méthode	Description
ticket_create()	Créer un nouveau ticket avec un premier article
ticket_get()	Récupérer les détails du ticket, articles & pièces jointes
ticket_search()	Rechercher des tickets selon des filtres
ticket_update()	Mettre à jour les champs, l’état, le propriétaire et les articles
ticket_delete()	Supprimer définitivement un ticket
ticket_history_get()	Charger l’historique complet d’un ticket

Remarque : pyznuny est disponible sur PyPI et est activement maintenu par Softoft.

---

8. OpenTicketAI Runtime & Znuny-Connector

Pour ceux qui souhaitent non seulement utiliser la Znuny REST API, mais aussi l’automatiser intelligemment, la solution est la OpenTicketAI Runtime – une plateforme IA on-premise qui classifie, priorise et redirige automatiquement les tickets entrants.

8.1 Architecture système

                            ┌─────────────────────────┐
  E-mails entrants    ────► │   Znuny (Generic Interface / REST API)  │
                            └────────────┬────────────┘
                                         │  Webhook / Polling
                                         ▼
                            ┌─────────────────────────┐
                            │  OpenTicketAI Runtime   │
                            │  (Docker, On-Premise)   │
                            │  ┌───────────────────┐  │
                            │  │  Modèle IA (NLP)  │  │
                            │  └───────────────────┘  │
                            └────────────┬────────────┘
                                         │  Connecteur otai-znuny-znuny
                                         ▼
                            ┌─────────────────────────┐
                            │  Znuny REST API          │
                            │  TicketUpdate / Routing  │
                            └─────────────────────────┘

La Runtime s’exécute entièrement localement dans votre centre de données – aucune donnée de ticket ne quitte votre infrastructure.

8.2 Installation du connecteur Znuny

Installez la bibliothèque principale OpenTicketAI avec le package de connecteur spécifique à Znuny otai-znuny-znuny :

pip install open-ticket-ai otai-hf-local otai-znuny-znuny

Package	Fonction
open-ticket-ai	Noyau OpenTicketAI : orchestration, pipelines, config
otai-hf-local	Modèles IA locaux via Hugging Face (On-Premise)
otai-znuny-znuny	Connecteur : lit & écrit des tickets via Znuny REST

8.3 Configuration

Créez un fichier config.yaml et connectez la Runtime à votre instance Znuny :

connector:
  type: znuny
  url: https://znuny.example.com
  username: otai-bot
  password: "${ZNUNY_PASSWORD}"

model:
  provider: hf-local
  model_name: softoft/ticket-classifier-de

routing:
  default_queue: "Non classifié"
  rules:
    - category: "Réseau"
      queue: "Infrastructure IT"
      priority: "4 high"
    - category: "Facturation"
      queue: "Comptabilité"
      priority: "3 normal"

8.4 Déroulement d’un traitement automatique de ticket

1. Le ticket arrive dans Znuny (via e-mail ou REST TicketCreate)
2. Le connecteur interroge via TicketSearch les nouveaux tickets à l’intervalle configuré
3. Le modèle IA analyse l’objet et le texte de l’article avec le traitement du langage naturel (NLP)
4. Le résultat de la classification (catégorie, priorité, file d’attente suggérée) est déterminé
5. TicketUpdate via REST définit la file d’attente, la priorité et un article interne optionnel
6. Le ticket arrive automatiquement dans la bonne équipe – sans triage manuel

8.5 Avantages par rapport à une intégration REST manuelle

Caractéristique	Intégration REST manuelle	OpenTicketAI + Connecteur
Classification	❌ Manuelle	✅ Entièrement automatique (IA)
Protection des données	✅ Locale	✅ 100 % On-Premise
Routage basé sur des règles	✅ Possible	✅ Inclus
Capacité d’apprentissage	❌ Règles rigides	✅ Modèle entraînable
Effort de mise en place	Élevé	Faible (Config YAML)

En savoir plus : Visitez openticketai.com ou contactez Softoft pour une démo personnalisée.