Vos outils — supervision, site web, ERP, n8n, Power Automate — peuvent travailler directement dans le Centre d’assistance : déposer un ticket quand une alerte se déclenche, le retrouver, y répondre côté équipe ou au nom du demandeur, en changer le statut et la priorité, écrire une note interne et lire les articles publiés de la base de connaissances. Cet article décrit cette partie de l’API publique d’Illizeo. Il s’adresse aux développeurs qui construisent l’intégration et à l’administrateur du Centre qui l’autorise.
Avant de commencer #
- Le module Centre d’assistance doit être installé, et votre abonnement doit comprendre l’accès à l’API.
- L’administrateur du Centre ouvre à l’API le ou les services concernés (voir ci-dessous) : un jeton n’atteint jamais un service fermé.
- Le jeton se crée dans Paramètres › Gérer Illizeo › Jetons API (voir Créer et gérer les jetons API). Il agit au nom de la personne qui le crée : celle-ci doit détenir, dans la matrice des rôles, Agent du Centre d’assistance ou Administrer le Centre d’assistance, au palier Accès pour lire et Exécuter pour écrire, et le module doit lui être ouvert.
- L’adresse de l’API, l’authentification, l’enveloppe des réponses et les limites de débit sont communes à toute l’API : voir API publique : le guide du développeur.
Ouvrir un service à l’API #
Chaque service est fermé à l’API par défaut. L’ouvrir demande le droit Administrer le Centre d’assistance au palier Exécuter.
- Ouvrez Paramètres › Centre d’assistance › Services et cliquez sur le service.
- Dans la rubrique Identité, sous API publique, basculez l’interrupteur sur Ouvert à l’API.
- Cliquez sur Enregistrer.

Comme le rappelle l’écran, les jetons de l’API et les webhooks n’atteignent que les services ouverts ici. Refermer un service vaut dès l’appel suivant : ses tickets et ses articles répondent alors 404, et il n’émet plus de webhook. L’ouverture et la fermeture s’inscrivent au journal d’activité.
Créer le jeton de l’intégration #
Dans Paramètres › Gérer Illizeo › Jetons API, cliquez sur Nouveau jeton. Choisissez le Nom avec soin : c’est lui qui signe ce que l’intégration écrit. Un jeton nommé « Supervision » répond sous la mention « via API · Supervision » dans la fiche du ticket, et l’e-mail reçu par le demandeur est signé « Supervision ». Cochez ensuite, dans le groupe Données, les droits du Centre dont l’intégration a besoin :
| Droit (écran) | Code | Ce qu’il ouvre |
|---|---|---|
| Centre d’assistance — tickets (Lire) | helpdesk_tickets:read |
Lister les services et les tickets ; lire un ticket, ses messages publics et sa chronologie publique. |
| Centre d’assistance — tickets (Écrire) | helpdesk_tickets:write |
Déposer un ticket, répondre (côté équipe ou demandeur), changer le statut et la priorité. |
| Centre d’assistance — notes internes (Lire) | helpdesk_notes:read |
Lire les notes internes, seules ou avec le ticket. |
| Centre d’assistance — notes internes (Écrire) | helpdesk_notes:write |
Écrire une note interne. |
| Centre d’assistance — articles de la base de connaissances (Lire) | helpdesk_articles:read |
Lister et lire les articles publiés. |
| Centre d’assistance — abonnements aux webhooks (Écrire) | helpdesk_webhooks:write |
S’abonner aux webhooks du Centre et s’en désabonner (voir Les webhooks du Centre d’assistance). |

L’écriture ne comprend pas la lecture : une intégration qui dépose puis suit ses tickets coche les deux. Sans un droit helpdesk_notes, aucune note interne ne sort ni n’entre par l’API. Ces droits n’apparaissent que si le module Centre d’assistance est actif.
Ce que le jeton atteint #
Le jeton atteint les services ouverts à l’API, et parmi eux ceux que son créateur atteint dans Illizeo :
- créé par un agent : les services dont il est agent. Il y agit comme à l’écran : sur un ticket libre, sur les siens, et sur tous ceux d’un service dont il est responsable. Le ticket d’un collègue, il le lit, peut y ajouter une note ou y écrire au nom du demandeur ; y répondre côté équipe ou en changer le statut ou la priorité est refusé (422) ;
- créé par l’administrateur du Centre (« Administrer le Centre d’assistance » au palier Exécuter) : tous les services ouverts à l’API, avec le droit d’agir sur chaque ticket.
Un ticket ou un article hors de cette portée répond 404, comme s’il n’existait pas. Si les droits du créateur changent, ceux du jeton suivent dès l’appel suivant.
Les opérations #
Toutes les adresses partent de https://api.illizeo.app, avec l’en-tête Authorization: Bearer illz_…. Dans les adresses, {ticket} est le numéro d’un ticket (AST-000812) ou son identifiant, et {article} le slug d’un article ou son identifiant.
| Opération | Droit | Usage |
|---|---|---|
GET /v1/helpdesk/services |
helpdesk_tickets:read |
Les services atteints, avec leurs types de demande et les champs de leur formulaire. |
GET /v1/helpdesk/tickets |
helpdesk_tickets:read |
La liste des tickets, sans leurs messages. |
GET /v1/helpdesk/tickets/{ticket} |
helpdesk_tickets:read |
Un ticket, ses messages et sa chronologie publique. |
POST /v1/helpdesk/tickets |
helpdesk_tickets:write |
Déposer un ticket. |
PATCH /v1/helpdesk/tickets/{ticket} |
helpdesk_tickets:write |
Changer le statut ou la priorité. |
POST /v1/helpdesk/tickets/{ticket}/messages |
helpdesk_tickets:write |
Répondre, côté équipe ou côté demandeur. |
GET /v1/helpdesk/tickets/{ticket}/notes |
helpdesk_notes:read |
Les notes internes du ticket. |
POST /v1/helpdesk/tickets/{ticket}/notes |
helpdesk_notes:write |
Écrire une note interne. |
GET /v1/helpdesk/articles |
helpdesk_articles:read |
Chercher parmi les articles publiés. |
GET /v1/helpdesk/articles/{article} |
helpdesk_articles:read |
Lire un article publié. |
POST /v1/helpdesk/webhooks, DELETE /v1/helpdesk/webhooks/{id} |
helpdesk_webhooks:write |
S’abonner aux webhooks du Centre, s’en désabonner. |
Le bouton Documentation de la page des jetons décrit chaque opération dans la carte Centre d’assistance ; le bouton openapi.json y donne le contrat complet.

Lire les tickets #
La liste accepte les filtres statut (un ou plusieurs codes séparés par des virgules), service_id, reference_externe et modified_since (une date ISO 8601 ; modifie_depuis est accepté aussi). Un ticket compte comme modifié quand sa fiche change ou qu’une activité visible par le jeton s’y ajoute : un message, un changement de statut. Les tickets viennent par identifiant croissant, 50 par page (limit, 200 au plus) ; la réponse porte items, next_cursor et has_more. Pour synchroniser un autre système, relancez la lecture avec cursor égal à next_cursor tant que has_more est vrai.
Un ticket porte notamment numero, objet, description, statut, priorite, service, type, canal, demandeur (salarie ou externe, avec nom et e-mail), agent, ses dates (depose_le, modifie_le, resolu_le, clos_le, en ISO 8601 UTC), ses echeances de première réponse et de résolution, les reponses_au_formulaire, la reference_externe, et les numéros du parent (la demande dont il est une tâche) et de l’incident majeur auquel il est rattaché, ou null. Les clés sont en français, comme dans l’application ; les valeurs sont des codes :
| Champ | Codes (libellé à l’écran) |
|---|---|
statut |
new (Nouveau), taken (Pris en charge), waiting_requester (En attente du demandeur), waiting_third_party (En attente d’un tiers), resolved (Résolu), closed (Clos) |
priorite |
low (Basse), normal (Normale), high (Haute), critical (Critique) |
canal |
internal (Espace salarié), portal (Portail), email (E-mail), agent (Déposé par un agent), widget (Widget du site), teams (Microsoft Teams), api (API) |
La lecture d’un ticket ajoute messages — chacun avec cote (equipe, demandeur ou note), auteur, via_api, le, corps en HTML et pieces (nom et taille ; les fichiers se téléchargent dans Illizeo) — puis chronologie, celle que voit le demandeur. Les notes internes n’y figurent qu’avec le droit helpdesk_notes:read.
Déposer un ticket #
Le corps de POST /v1/helpdesk/tickets porte service_id et objet (obligatoires), au besoin type_id, description, priorite, reponses_au_formulaire et reference_externe (votre propre identifiant, par exemple celui de l’alerte), et le demandeur : email (obligatoire), nom et langue.
POST /v1/helpdesk/tickets
Authorization: Bearer illz_…
Content-Type: application/json
{
"service_id": 3,
"objet": "Serveur de fichiers injoignable",
"description": "FS-01 ne répond plus depuis 08:42.",
"priorite": "high",
"demandeur": { "email": "supervision@votre-entreprise.ch", "nom": "Supervision" },
"reference_externe": "ALERTE-20261120-0042"
}
La réponse, en 201, rend le ticket et son fil ("numero": "AST-000812", "statut": "new", "canal": "api"…). Le ticket entre dans la file comme les autres : règles du Centre, engagements de service, accusé de réception au demandeur.
- Le demandeur se donne par son adresse e-mail. Si le service est ouvert aux salariés et que l’adresse est celle d’un seul salarié actif qui peut déposer au Centre (droit « Demandes au Centre d’assistance » au palier Exécuter), c’est lui. Sinon, si le service est ouvert aux externes, c’est une personne extérieure, créée à sa première demande dans la
languedonnée. Sinon, la réponse est 422. Une alerte peut donc porter l’adresse de l’outil qui l’émet. - Le type est facultatif. S’il est donné, il doit être actif et proposé à ce demandeur, et ses champs obligatoires doivent figurer dans
reponses_au_formulaire, sous les clés que donneGET /v1/helpdesk/services. - La priorité, à défaut, est celle du type, sinon Normale ; elle remonte au minimum prévu par le contrat de l’organisation cliente, s’il y en a un.
- Un service fermé à l’API, hors de la portée du jeton ou inactif est refusé (422 sur
service_id).
Répondre #
POST /v1/helpdesk/tickets/{ticket}/messages prend un corps en HTML, nettoyé à l’arrivée, et un cote.
"cote": "equipe": une réponse publique de l’équipe, marquée « via API · » suivi du nom du jeton, et envoyée au demandeur par un e-mail signé de ce nom. Elle compte comme première réponse pour les engagements de service, mais ne prend pas le ticket : il garde son agent, ou n’en a toujours pas. Unstatutfacultatif le change dans le même geste ; le demandeur ne reçoit alors qu’un e-mail. La réponse est refusée (422) sur un ticket clos, sur un ticket en attente d’approbation et sur le ticket d’un collègue. Sur une tâche d’une demande du catalogue, elle s’écrit sur la demande, comme à l’écran."cote": "demandeur": la réponse est écrite au nom du demandeur du ticket, par exemple depuis votre portail client. Elle suit les règles d’une réponse du demandeur : un ticket en attente du demandeur repasse Pris en charge ; un ticket résolu depuis moins que le délai de réouverture est rouvert ; au-delà, ou sur un ticket clos, une suite est créée et reçoit le message.statutn’est pas accepté de ce côté, ni une réponse sur une tâche.
POST /v1/helpdesk/tickets/AST-000812/messages
{ "cote": "equipe", "corps": "<p>La sonde est revenue à la normale.</p>", "statut": "resolved" }
La réponse, en 201, porte message (le message écrit, avec "via_api": true) et ticket, le ticket qui l’a reçu : le même, sa suite, ou la demande d’une tâche.

Dans la fiche du ticket, les agents voient le canal API et la mention via API · Supervision sur chaque message de l’intégration ; la chronologie la nomme aussi (« Supervision (API) a répondu »). Le demandeur voit la même mention dans sa demande.
Changer le statut ou la priorité #
PATCH /v1/helpdesk/tickets/{ticket} prend statut, priorite ou les deux, en tout ou rien. Les règles sont celles de l’écran :
- un ticket clos ne change plus ; un ticket résolu ne peut que repasser Pris en charge ou se clore ; un ticket ne redevient Nouveau que depuis Pris en charge ;
- un ticket en attente d’approbation ne change ni de statut ni de priorité ; le statut ne change pas sur un ticket rattaché à un incident majeur ouvert, et une demande du catalogue ne se résout ni ne se clôt tant qu’une de ses tâches est ouverte (422, avec le motif) ;
- la priorité ne change plus sur un ticket résolu ou clos, et ne descend pas sous le minimum du contrat de l’organisation cliente ;
- le ticket d’un collègue est refusé (422).
La réponse, en 200, rend le ticket sans son fil. Dans un même appel, la priorité est traitée avant le statut : pour rouvrir un ticket résolu et en changer la priorité, faites deux appels, le statut d’abord. Le geste est signé du nom du jeton dans la chronologie. "statut": "taken" ne donne le ticket à personne, et "statut": "new" le rend à la file, sans agent.
Les notes internes #
Avec helpdesk_notes:write, POST /v1/helpdesk/tickets/{ticket}/notes et un corps en HTML écrivent une note interne signée du nom du jeton, sur tout ticket atteint, même clos, en attente d’approbation ou tenu par un collègue. Elle ne change ni le statut ni l’agent, et n’est jamais montrée au demandeur. Avec helpdesk_notes:read, GET …/notes rend les notes seules, et la lecture d’un ticket les mêle à ses messages ("cote": "note").
Les articles de la base #
Avec helpdesk_articles:read, l’intégration lit les articles publiés des services atteints, dans leur version courante, par exemple pour proposer des réponses sur votre site. GET /v1/helpdesk/articles accepte q (la même recherche que l’aide de l’espace), service_id, public (interne ou externe ; internal et external sont acceptés aussi) et langue, et rend pour chaque article son titre, un extrait, la langue servie, sa visibilité et sa catégorie. GET /v1/helpdesk/articles/{article} rend l’article entier, corps en HTML ; repli vaut true quand la langue demandée manque et qu’une autre est servie. Un brouillon, un article archivé ou hors de portée répond 404, et un article rattaché à aucun service n’est pas servi. Voir La base de connaissances.
Les refus #
| Réponse | Cause |
|---|---|
403, SCOPE_MANQUANT |
Le droit de l’opération n’est pas coché sur le jeton ; data.required_scope le nomme. Un jeton en lecture seule ne peut rien écrire. |
403, MODULE_NOT_ACTIVE ou MODULE_DISABLED_FOR_EMPLOYEE (champ code) |
Le Centre d’assistance n’est pas actif dans l’espace, ou pas ouvert au créateur du jeton. |
| 403 | Le créateur du jeton n’a pas le droit de l’écran au bon palier : « Agent du Centre d’assistance » ou « Administrer le Centre d’assistance » (ce dernier, au palier Exécuter, pour les webhooks). |
404, NOT_FOUND |
Ticket ou article hors de la portée du jeton, ou d’un service fermé à l’API. |
422, VALIDATION_ERROR |
Un champ refusé, détaillé dans errors ; ou une règle de l’écran, dont le motif est dans message, dans la langue demandée par X-Locale ou Accept-Language, sinon dans celle du créateur du jeton. |
À savoir #
- Les gestes de l’API ne sont signés d’aucune personne : le nom du jeton les signe dans le fil et la chronologie. Ce nom est recopié sur chaque message : renommer le jeton ne change pas les messages déjà écrits. Au journal d’activité, les modifications sont inscrites au nom du créateur du jeton.
- Une réponse de l’équipe écrite par l’API sur le ticket d’un agent ne lui envoie pas de notification.
- Les pièces jointes ne s’envoient pas par l’API : les messages les nomment seulement.
- Chaque appel compte une unité dans la consommation de la plateforme API, comme chaque webhook livré (voir Suivre l’utilisation d’un jeton et le dépanner).
- Le canal API se retrouve dans le pilotage et dans la condition « Canal » des automatisations.
- Pour être prévenu de ce qui arrive aux tickets plutôt que de les relire, abonnez-vous à leurs webhooks : voir Les webhooks du Centre d’assistance.
