Aperçu de l'API Freshservice : Un guide complet pour les développeurs pour 2026

Si vous créez des intégrations avec Freshservice, vous devez comprendre les capacités de son API (Application Programming Interface). Que vous automatisiez la création de tickets, synchronisiez les données utilisateur ou construisiez des tableaux de bord personnalisés, l'API Freshservice vous donne un accès programmatique à vos données de gestion des services informatiques.

Décomposons ce que l'API Freshservice offre, comment s'authentifier, quels points de terminaison sont disponibles et comment travailler dans ses limites de débit. Nous examinerons également comment des outils comme eesel AI peuvent simplifier certaines de ces intégrations sans écrire de code à partir de zéro.

Qu'est-ce que l'API Freshservice ?

L'API Freshservice est une interface RESTful qui vous permet d'interagir avec votre instance Freshservice par programme. Elle suit les conventions HTTP standard, utilise JSON pour l'échange de données et prend en charge toute la gamme des opérations CRUD (Create, Read, Update, Delete — Créer, Lire, Mettre à jour, Supprimer).

Voici ce que cela signifie en pratique. Vous pouvez :

• Extraire les données de tickets dans des outils de reporting externes
• Créer des tickets automatiquement à partir d'alertes de surveillance
• Synchroniser les informations utilisateur avec votre fournisseur d'identité
• Mettre à jour les enregistrements d'actifs à partir d'outils de découverte
• Construire des portails personnalisés ou des applications mobiles

Freshservice propose en fait deux versions d'API. La version 1 est l'API héritée, toujours fonctionnelle mais limitée. La version 2 est celle que vous devriez utiliser pour les nouveaux projets. Elle offre des limites de débit plus élevées, une meilleure gestion des erreurs et plus de points de terminaison. L'API v2 accepte uniquement JSON et nécessite des connexions HTTPS.

Freshservice se décline également en trois saveurs, chacune avec un comportement d'API légèrement différent :

• Freshservice : La plateforme ITSM standard
• Freshservice for Business Teams (FSBT) : Conçu pour les départements non-IT comme les RH ou les installations
• Freshservice for MSPs : Conçu pour les fournisseurs de services gérés (managed service providers) gérant plusieurs clients

L'API de base fonctionne de la même manière sur les trois, mais certains points de terminaison et terminologies diffèrent. Par exemple, les MSP utilisent « Contacts » au lieu de « Requesters » (Demandeurs), et « Clients » au lieu de « Workspaces » (Espaces de travail).

Méthodes d'authentification

Avant de pouvoir effectuer des appels d'API, vous devez vous authentifier. Freshservice offre quelques options selon votre cas d'utilisation.

Authentification par clé API (recommandée)

C'est l'approche la plus simple et la plus courante. Vous générez une clé API à partir de votre profil Freshservice, puis vous l'incluez dans vos requêtes en utilisant Basic Auth (Authentification de base).

Voici comment trouver votre clé API :

1. Connectez-vous à votre portail Freshservice
2. Cliquez sur votre photo de profil en haut à droite
3. Allez dans Profile Settings (Paramètres de profil)
4. Votre clé API apparaît sous la section Change Password (Changer le mot de passe)

Une fois que vous avez votre clé, vous vous authentifiez en la passant comme nom d'utilisateur dans un en-tête Basic Auth, avec n'importe quelle chaîne (conventionnellement « X ») comme mot de passe. Voici à quoi cela ressemble en pratique :

curl -u "votre_clé_api:X" \
  -H "Content-Type: application/json" \
  -X GET \
  "https://votredomaine.freshservice.com/api/v2/tickets"

Ou en JavaScript :

const apiKey = "votre_clé_api_ici";
const encodedKey = Buffer.from(apiKey + ":X").toString("base64");

fetch("https://votredomaine.freshservice.com/api/v2/tickets", {
  method: "GET",
  headers: {
    "Authorization": `Basic ${encodedKey}`,
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data));

Authentification par nom d'utilisateur et mot de passe

Vous pouvez également vous authentifier en utilisant vos identifiants de connexion Freshservice. Cela fonctionne de la même manière que l'authentification par clé API, mais vous passez votre e-mail et votre mot de passe à la place :

curl -u "utilisateur@entreprise.com:motdepasse" \
  -H "Content-Type: application/json" \
  -X GET \
  "https://votredomaine.freshservice.com/api/v2/tickets"

OAuth 2.0

Pour les applications qui doivent agir au nom des utilisateurs (comme les applications de la marketplace), Freshservice prend en charge OAuth 2.0. Ceci est plus complexe à configurer, mais offre une meilleure sécurité pour les intégrations destinées aux utilisateurs.

Meilleures pratiques de sécurité

Quelques éléments à garder à l'esprit :

• Stockez les clés API en toute sécurité, ne les committez jamais dans le contrôle de version
• Utilisez HTTPS pour toutes les requêtes (la v2 l'exige)
• Faites tourner les clés API périodiquement
• Utilisez les permissions minimales nécessaires pour votre intégration
• Envisagez d'utiliser des variables d'environnement pour le stockage des clés

Points de terminaison et capacités de l'API de base

L'API Freshservice couvre pratiquement toutes les fonctionnalités de la plateforme. Voici les principaux points de terminaison avec lesquels vous travaillerez.

Tickets

Le point de terminaison des tickets est le plus couramment utilisé. Vous pouvez :

• Lister tous les tickets avec filtrage et pagination
• Créer de nouveaux tickets par programme
• Mettre à jour les propriétés des tickets (statut, priorité, assigné)
• Supprimer ou restaurer des tickets
• Ajouter des réponses et des notes

Une requête de création de ticket de base ressemble à ceci :

fetch("https://votredomaine.freshservice.com/api/v2/tickets", {
  method: "POST",
  headers: {
    "Authorization": "Basic " + btoa("clé_api:X"),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "demandeur@exemple.com",
    subject: "Nouvelle demande d'ordinateur portable",
    description: "J'ai besoin d'un nouvel ordinateur portable pour le projet à venir",
    priority: 2,
    status: 2
  })
});

Les propriétés des tickets utilisent des valeurs numériques pour le statut et la priorité :

Utilisateurs et groupes

Gérez votre équipe de service desk et vos demandeurs :

• Agents : Le personnel IT qui gère les tickets
• Requesters (Demandeurs) : Les employés qui soumettent des tickets
• Groups (Groupes) : Les équipes qui gèrent des types de tickets spécifiques
• Departments (Départements) : Structure organisationnelle

Actifs

Suivez et gérez les actifs IT tout au long de leur cycle de vie :

• Créer et mettre à jour les enregistrements d'actifs
• Associer les actifs aux tickets
• Gérer les relations et les dépendances des actifs
• Suivre la maintenance et les contrats des actifs

Changements et problèmes

Pour la gestion des changements alignée sur ITIL :

• Créer des demandes de changement
• Gérer les flux de travail d'approbation des changements
• Lier les changements aux tickets et aux problèmes
• Suivre l'état de la mise en œuvre

Catalogue de services

Automatisez les demandes de service :

• Lister les éléments de service disponibles
• Soumettre des demandes de service
• Suivre l'état d'approbation des demandes
• Gérer les accords de niveau de service

Conversations

Gérez les communications des tickets :

• Ajouter des réponses publiques visibles par les demandeurs
• Ajouter des notes privées pour les équipes internes
• Joindre des fichiers aux conversations
• Transférer les tickets à des parties externes

Limites de débit et meilleures pratiques

Freshservice impose des limites de débit pour assurer la stabilité de la plateforme. Celles-ci varient en fonction de votre plan et de la date de création de votre compte.

Limites de débit par plan

Pour les comptes créés après le 1er septembre 2020 :

Notez qu'il s'agit de limites à l'échelle du compte, et non par utilisateur ou par IP. Chaque appel d'API depuis votre compte compte pour le même quota.

En-têtes de limite de débit

Chaque réponse de l'API inclut des en-têtes indiquant l'état actuel de votre limite de débit :

• X-RateLimit-Total : La limite totale de votre compte par minute
• X-RateLimit-Remaining : Les requêtes restantes dans la fenêtre actuelle
• X-RateLimit-Used-CurrentRequest : Le nombre de requêtes que votre dernier appel a consommé
• Retry-After : Secondes à attendre lorsque vous avez atteint la limite (n'apparaît que sur les réponses 429)

Gérer les limites de débit

Lorsque vous atteignez la limite, l'API renvoie un code d'état 429. Votre code doit gérer cela avec élégance :

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response.json();
    }

    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, retries);
    console.log(`Limite de débit atteinte. Nouvelle tentative dans ${retryAfter} secondes...`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    retries++;
  }

  throw new Error('Nombre maximal de tentatives atteint');
}

Pagination

Les points de terminaison de liste renvoient des résultats paginés. Utilisez le paramètre page pour naviguer :

curl -u "clé_api:X" \
  "https://votredomaine.freshservice.com/api/v2/tickets?page=2&per_page=100"

L'API v2 prend en charge les tailles de page allant jusqu'à 100 enregistrements. Implémentez toujours la pagination pour les intégrations de production plutôt que de supposer que vous obtiendrez tous les résultats en un seul appel.

Cas d'utilisation courants de l'intégration

Voici quelques façons pratiques dont les organisations utilisent l'API Freshservice :

Création automatisée de tickets : Les outils de surveillance comme Datadog ou PagerDuty peuvent créer des tickets automatiquement lorsque des alertes se déclenchent, garantissant que les équipes IT répondent rapidement aux incidents.

Provisionnement des utilisateurs : Lorsque de nouveaux employés rejoignent l'entreprise, les systèmes RH peuvent créer des comptes Freshservice automatiquement, en les assignant aux bons départements et groupes en fonction de leur rôle.

Synchronisation des actifs : Les outils de découverte peuvent pousser les données d'actifs dans la CMDB (Configuration Management Database) de Freshservice, en gardant les enregistrements d'inventaire à jour sans saisie manuelle.

Tableaux de bord personnalisés : Les organisations extraient les métriques des tickets dans des outils de business intelligence comme Tableau ou Power BI pour les rapports de direction.

Intégrations de chatbot : Les outils de support basés sur l'IA peuvent créer des tickets à partir de conversations de chat, en les catégorisant et en les acheminant automatiquement en fonction de l'analyse du contenu.

Automatisation des e-mails : Les e-mails entrants provenant de domaines spécifiques ou contenant certains mots-clés peuvent déclencher la création de tickets avec des catégories et des personnes assignées préremplies.

Démarrer avec votre premier appel d'API

Prêt à essayer par vous-même ? Voici un guide de démarrage rapide.

Tout d'abord, récupérez votre clé API dans les paramètres de votre profil Freshservice. Ouvrez ensuite un terminal et exécutez cette commande cURL (remplacez votredomaine et votre_clé_api) :

curl -u "votre_clé_api:X" \
  -H "Content-Type: application/json" \
  -X GET \
  "https://votredomaine.freshservice.com/api/v2/tickets?page=1&per_page=1"

Si tout fonctionne, vous obtiendrez une réponse JSON avec votre ticket le plus récent.

Pour l'exploration, Postman est inestimable. Créez une nouvelle requête, définissez l'authentification sur Basic Auth avec votre clé API comme nom d'utilisateur et « X » comme mot de passe, et commencez à tester les points de terminaison.

Freshworks fournit également un SDK JavaScript/TypeScript officiel qui simplifie les interactions avec l'API :

const { Freshservice } = require("@freshworks/api-sdk");
const fs = new Freshservice("votredomaine", "votre_clé_api");

// Obtenir tous les tickets
const tickets = await fs.tickets.list();

Simplifier les intégrations Freshservice avec eesel AI

La construction d'intégrations API à partir de zéro prend du temps et des ressources d'ingénierie. Si vous avez besoin d'automatiser les flux de travail Freshservice sans écrire de code, eesel AI offre une approche alternative.

Notre plateforme se connecte directement à Freshservice et fournit une automatisation basée sur l'IA pour les tâches courantes :

• AI Agent (Agent IA) : Gère de manière autonome les tickets de support de première ligne, en résolvant les problèmes courants sans intervention humaine
• AI Copilot (Copilote IA) : Rédige des réponses que vos agents peuvent examiner et envoyer, accélérant ainsi les temps de réponse
• AI Triage (Tri IA) : Étiquette, achemine et priorise automatiquement les tickets entrants en fonction du contenu

Au lieu d'écrire des appels d'API pour créer des tickets ou mettre à jour des champs, vous configurez des règles d'automatisation en langage clair. Par exemple : « Si un ticket mentionne 'réinitialisation du mot de passe' et provient d'un utilisateur VIP, assignez-le au groupe de support senior et marquez-le comme haute priorité. »

La configuration prend quelques minutes plutôt que des semaines. Vous connectez votre compte Freshservice, et notre IA apprend de vos tickets existants, des articles du centre d'aide et des macros. Pas besoin de mapper les points de terminaison de l'API ou de gérer vous-même la limitation du débit.

Pour les équipes qui ont besoin à la fois d'intégrations API personnalisées et d'automatisation de l'IA, les approches se complètent. Utilisez l'API pour la synchronisation des données et la communication de système à système, et eesel AI pour la gestion intelligente des tickets et la rédaction des réponses.