---
title: L’API du Centre d’assistance
description: Déposer, suivre et répondre aux tickets du Centre d’assistance depuis vos outils, changer leur statut et leur priorité, écrire des notes internes et lire les articles publiés, par l’API publique d’Illizeo.
url: "https://illizeo.com/centre-aide/centre-assistance-api/"
updated: "2026-11-20"
category: Plateforme / API REST
---

# L’API du Centre d’assistance

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](https://illizeo.com/centre-aide/api-gerer-les-jetons/)). 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](https://illizeo.com/centre-aide/api-guide-du-developpeur/).

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

1. Ouvrez **Paramètres › Centre d’assistance › Services** et cliquez sur le service.
2. Dans la rubrique **Identité**, sous **API publique**, basculez l’interrupteur sur **Ouvert à l’API**.
3. Cliquez sur **Enregistrer**.

![Rubrique Identité d’un service : Ouvert aux, État, puis API publique avec l’interrupteur Ouvert à l’API, la phrase Les jetons de l’API et les webhooks n’atteignent que les services ouverts ici, et le bouton Enregistrer](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-01.fr_.png?resize=800%2C189&quality=80&ssl=1)
Ouvrir un service à l’API

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](https://illizeo.com/centre-aide/centre-assistance-webhooks/)). |

![Formulaire Nouveau jeton API, groupe Données : Centre d’assistance — tickets cochée en lecture et en écriture, notes internes non cochée, articles de la base de connaissances cochée en lecture, abonnements aux webhooks non cochée](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-02.fr_.png?resize=800%2C191&quality=80&ssl=1)
Les droits du Centre d’assistance sur un jeton

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.

![Documentation de l’API dans l’application, carte Centre d’assistance : sa présentation puis les douze opérations, chacune avec sa méthode, son adresse sous /v1/helpdesk, son résumé et son droit](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-03.fr_.png?resize=800%2C494&quality=80&ssl=1)
Les opérations du Centre dans la documentation de l’API

## 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 `langue` donné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 donne `GET /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. Un `statut` facultatif 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. `statut` n’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.

![Fiche du ticket AST-000071 côté agent : canal API, aucun agent, puis les échanges : réponse automatique, réponse de l’équipe marquée via API · Supervision, note interne d’une agente, réponse du demandeur écrite par l’API](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-04.fr_.png?resize=800%2C672&quality=80&ssl=1)
Un ticket déposé et suivi par l’API, vu par l’agent

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](https://illizeo.com/centre-aide/centre-assistance-incidents-et-problemes/) ouvert, et une [demande du catalogue](https://illizeo.com/centre-aide/centre-assistance-catalogue-de-services/) 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](https://illizeo.com/centre-aide/centre-assistance-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](https://illizeo.com/centre-aide/api-suivre-et-depanner-un-jeton/)).
- 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](https://illizeo.com/centre-aide/centre-assistance-webhooks/).

### *Similaire*
