API de la base de connaissances du Guide Zendesk : Le guide complet du développeur pour 2026
Stevia Putri
Dernière modification February 25, 2026
Si vous créez des intégrations avec Zendesk ou si vous cherchez à gérer par programmation le contenu de votre base de connaissances, l'API du Centre d'aide Zendesk (souvent appelée API de la base de connaissances du Guide Zendesk) est votre porte d'entrée. Que vous ayez besoin de synchroniser des articles avec un système de recherche externe, de créer une solution de sauvegarde ou d'intégrer du contenu dans une base de connaissances d'IA, cette API REST fournit les outils nécessaires pour y parvenir.
Voyons comment cela fonctionne et comment l'utiliser efficacement.
Qu'est-ce que l'API de la base de connaissances du Guide Zendesk ?
L'API du Centre d'aide Zendesk est une API REST qui vous permet de gérer par programmation le contenu de votre base de connaissances du Guide Zendesk. Elle fait partie de l'écosystème API plus large de Zendesk et utilise JSON pour les requêtes et les réponses.
Voici ce que vous pouvez faire avec elle :
- Lire le contenu : récupérer des articles, des sections et des catégories pour une utilisation externe
- Écrire du contenu : créer, mettre à jour et archiver des articles par programmation
- Gérer les traductions : gérer le contenu multilingue à grande échelle
- Rechercher et filtrer : trouver du contenu spécifique à l'aide d'étiquettes, de dates et d'autres critères
L'API suit les conventions REST standard. Votre URL de base ressemble à https://{your-subdomain}.zendesk.com/api/v2/help_center/, et toutes les réponses sont filtrées en fonction des autorisations de l'utilisateur qui fait la requête. Cela signifie que les utilisateurs anonymes ne voient que le contenu public, tandis que les agents peuvent accéder aux articles internes en fonction de leurs autorisations.
Démarrer avec l'authentification
Avant de pouvoir faire des appels d'API, vous devez vous authentifier. Zendesk offre deux méthodes principales : les jetons API (API tokens) et OAuth 2.0.
Authentification par jeton API (recommandée pour les scripts côté serveur)
Les jetons API sont la façon la plus simple de démarrer. Vous les générez dans votre Centre d'administration Zendesk sous Applications et intégrations > API > API Zendesk.
| Attribut | Détail |
|---|---|
| Limite de jetons | 256 par compte (jusqu'à 2 048 pour les comptes plus importants) |
| Format | {adresse_courriel}/token:{jeton_api} |
| En-tête | Authorization: Basic {informations_d'identification_encodées_en_base64} |
Voici à quoi cela ressemble en pratique :
curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
-u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv
L'indicateur -u dans cURL gère automatiquement l'encodage Base64 pour vous. Si vous créez l'en-tête manuellement dans le code, combinez votre courriel et votre jeton avec un deux-points, encodez le résultat en Base64 et ajoutez-le à l'en-tête Authorization.
OAuth 2.0 (pour les applications destinées aux utilisateurs)
Si vous créez une application côté client ou si vous devez agir au nom d'utilisateurs individuels, OAuth est le meilleur choix. Il utilise des jetons Bearer :
curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
L'avantage principal ici est qu'OAuth prend en charge CORS, ce qui le rend adapté aux applications basées sur un navigateur. Les jetons API ne prennent pas en charge CORS et sont limités à une utilisation côté serveur.
Note de sécurité : Toutes les connexions doivent utiliser TLS 1.2 ou une version ultérieure. Stockez vos jetons en toute sécurité et ne les validez jamais dans le contrôle de version.
Points d'extrémité et opérations de l'API de base
L'API du Centre d'aide est organisée autour de trois principaux types de contenu : les catégories, les sections et les articles. Considérez cela comme une hiérarchie : les catégories contiennent des sections et les sections contiennent des articles.
Travailler avec des articles
Le point d'extrémité des articles est l'endroit où vous passerez le plus de temps. Voici les opérations clés :
Répertorier tous les articles :
GET /api/v2/help_center/articles.json
Cela renvoie une liste paginée d'articles. Vous pouvez filtrer les résultats à l'aide de paramètres de requête :
| Paramètre | Objectif | Exemple |
|---|---|---|
label_names | Filtrer par étiquettes | ?label_names=faq,billing |
sort_by | Champ de tri | ?sort_by=updated_at |
sort_order | Ordre de tri | ?sort_order=desc |
start_time | Exportation incrémentale | ?start_time=1704067200 |
Obtenir un article spécifique :
GET /api/v2/help_center/articles/{article_id}.json
Créer un article :
POST /api/v2/help_center/sections/{section_id}/articles.json
Les champs obligatoires comprennent title, locale et permission_group_id. Vous pouvez également définir des champs facultatifs comme body (contenu HTML), author_id, label_names et l'état draft.
Mettre à jour un article :
PUT /api/v2/help_center/articles/{article_id}.json
Archiver un article :
DELETE /api/v2/help_center/articles/{article_id}.json
Points d'extrémité de la hiérarchie de contenu
| Point d'extrémité | Objectif |
|---|---|
GET /api/v2/help_center/categories.json | Répertorier toutes les catégories |
GET /api/v2/help_center/categories/{id}/sections.json | Répertorier les sections dans une catégorie |
GET /api/v2/help_center/sections.json | Répertorier toutes les sections |
GET /api/v2/help_center/sections/{id}/articles.json | Répertorier les articles dans une section |
Chargement latéral des données associées
Une fonctionnalité utile est le chargement latéral, qui vous permet d'inclure des données associées dans une seule requête. Ajoutez ?include=users,sections,categories à votre requête d'articles, et la réponse inclura des objets complets pour les auteurs, les sections et les catégories au lieu de seulement des identifiants.
Gérer la pagination efficacement
La pagination est l'endroit où de nombreux développeurs rencontrent leur premier problème. L'API du Centre d'aide prend en charge deux méthodes de pagination, et choisir la bonne est important.
Pagination basée sur un curseur (recommandée)
La pagination par curseur est l'approche moderne et fonctionne beaucoup mieux avec les grands ensembles de données. Pour l'utiliser, ajoutez page[size] à votre requête :
GET /api/v2/help_center/articles.json?page[size]=100
La réponse comprend un objet meta avec un booléen has_more et un objet links avec les URL next et prev :
{
"articles": [...],
"meta": {
"has_more": true
},
"links": {
"next": "https://.../articles.json?page[size]=100&page[after]=xxx",
"prev": null
}
}
Continuez à suivre l'URL next jusqu'à ce que has_more soit faux. Voici un exemple en Python :
import requests
from base64 import b64encode
def fetch_all_articles(subdomain, email, token):
base_url = f"https://{subdomain}.zendesk.com/api/v2/help_center/articles.json"
credentials = b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {credentials}"}
articles = []
url = f"{base_url}?page[size]=100"
while url:
response = requests.get(url, headers=headers)
data = response.json()
articles.extend(data["articles"])
url = data["links"]["next"] if data["meta"]["has_more"] else None
return articles
Pagination basée sur un offset (héritée)
La pagination par offset fonctionne toujours, mais elle a des limites. Depuis août 2023, vous ne pouvez pas récupérer plus de 10 000 enregistrements (100 pages) en utilisant cette méthode. Si vous essayez, vous obtiendrez une erreur 400 Bad Request.
GET /api/v2/help_center/articles.json?per_page=100&page=2
La réponse comprend les URL next_page et previous_page. Arrêtez lorsque next_page est nul.
En résumé : Utilisez la pagination par curseur pour les nouvelles intégrations. Elle est plus rapide, plus fiable et n'a pas de limites strictes.
Modèles d'intégration courants
Maintenant que vous comprenez les bases, regardons comment les développeurs utilisent généralement cette API en production.
Indexation de recherche externe
Un cas d'utilisation courant est l'indexation de vos articles Zendesk dans un moteur de recherche externe comme Elasticsearch ou Algolia. Le modèle ressemble à ceci :
- Récupérer tous les articles à l'aide de la pagination par curseur
- Transformer le corps HTML en texte brut (supprimer les balises)
- Indexer l'identifiant de l'article, le titre, le corps du texte et l'URL
- Configurer une synchronisation périodique à l'aide du paramètre
start_timepour les mises à jour incrémentales
La clé est de préserver l'URL de l'article original dans votre index afin que les résultats de recherche puissent revenir à Zendesk.
Sauvegarde et migration de contenu
Pour les flux de travail de sauvegarde, vous voudrez peut-être exporter l'ensemble de votre base de connaissances :
- Parcourir toutes les catégories
- Pour chaque catégorie, obtenir ses sections
- Pour chaque section, obtenir ses articles
- Enregistrer les objets d'article complets (y compris le corps HTML) dans votre stockage de sauvegarde
Cela préserve votre hiérarchie de contenu et rend la restauration simple.
Intégration du système d'IA et de RAG
Un cas d'utilisation croissant est l'intégration du contenu Zendesk dans les systèmes de génération augmentée par récupération (RAG) pour le soutien alimenté par l'IA. Le flux de travail implique généralement :
- Extraire des articles via l'API
- Convertir HTML en Markdown ou en texte brut
- Découper le contenu pour le stockage vectoriel
- Préserver l'URL originale pour les citations
C'est là que des outils comme eesel AI peuvent aider. Au lieu de créer des pipelines ETL personnalisés, vous pouvez connecter directement votre compte Zendesk et avoir un agent d'IA qui répond aux questions en utilisant le contenu de votre base de connaissances, avec des citations vers les articles originaux.
Limites de débit et meilleures pratiques
Comprendre les limites de débit empêche votre intégration d'atteindre des limites à grande échelle.
Limites de requêtes par plan
| Plan | Limite de l'API Support/Centre d'aide |
|---|---|
| Suite Team | 200 requêtes/minute |
| Suite Growth | 400 requêtes/minute |
| Suite Professional | 400 requêtes/minute |
| Suite Enterprise | 700 requêtes/minute |
| Suite Enterprise Plus | 2 500 requêtes/minute |
Source : Documentation sur les limites de débit de Zendesk
Gérer les erreurs de limite de débit
Lorsque vous dépassez la limite, l'API renvoie un code d'état 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre. Votre code devrait :
- Vérifier les réponses 429
- Extraire la valeur
Retry-After - Attendre ce nombre de secondes avant de réessayer
- Envisager de mettre en œuvre un repli exponentiel pour les échecs répétés
Voici un simple décorateur de nouvelle tentative en Python :
import time
import requests
from functools import wraps
def with_rate_limit_retry(func):
def wrapper(*args, **kwargs):
max_retries = 3
for attempt in range(max_retries):
response = func(*args, **kwargs)
if response.status_code != 429:
return response
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
raise Exception("Rate limit exceeded after retries")
return wrapper
def api_call(url, headers):
return requests.get(url, headers=headers)
Conseils de performance
- Utiliser la pagination par curseur : elle est plus rapide et n'a pas de limite de 10 000 enregistrements
- Activer le chargement latéral : récupérer les données associées en une seule requête au lieu de faire plusieurs appels
- Mettre en cache de manière agressive : le contenu des articles ne change pas si fréquemment
- Utiliser les exportations incrémentales : le paramètre
start_timevous permet de récupérer uniquement le contenu modifié
Autres approches à considérer
La création d'une intégration d'API personnalisée n'est pas toujours le bon choix. Voici un cadre rapide pour décider :
Utiliser l'API directement lorsque :
- Vous avez besoin d'un contrôle complet sur la transformation des données
- Vous avez des ressources d'ingénierie dédiées
- Votre cas d'utilisation est unique ou complexe
Utiliser les fonctionnalités natives de Zendesk lorsque :
- Vous voulez simplement faire apparaître du contenu externe dans la recherche : utilisez la recherche fédérée
- Vous avez besoin d'une gestion de contenu de base : utilisez l'interface utilisateur intégrée
Utiliser une plateforme d'intégration lorsque :
- Vous voulez des réponses alimentées par l'IA sans créer de pipelines RAG
- Vous avez besoin d'une configuration rapide sans ressources d'ingénierie
- Vous voulez une synchronisation continue sans frais de maintenance
C'est là que eesel AI s'intègre. Plutôt que d'écrire des scripts personnalisés pour extraire, transformer et synchroniser votre contenu Zendesk, vous pouvez connecter votre compte en quelques minutes et obtenir un coéquipier d'IA qui répond aux questions des clients en utilisant votre base de connaissances. Il gère l'intégration de l'API, l'indexation du contenu et la génération de réponses, vous permettant de vous concentrer sur un travail de plus grande valeur.
Créer des intégrations de connaissances puissantes avec Zendesk
L'API du Centre d'aide Zendesk vous donne les éléments de base pour créer des flux de travail de gestion des connaissances sophistiqués. Que vous créiez un index de recherche personnalisé, que vous migriez du contenu entre des systèmes ou que vous intégriez des articles dans des plateformes d'IA, la compréhension de l'authentification, de la pagination et des limites de débit vous prépare au succès.
Commencez petit : récupérez une liste d'articles, expérimentez avec la pagination, puis passez à des intégrations plus complexes. Et si vous vous retrouvez à passer plus de temps à maintenir les pipelines de données qu'à résoudre des problèmes commerciaux, déterminez si une plateforme d'intégration pourrait être une meilleure solution.
Si vous cherchez à améliorer votre configuration Zendesk avec des capacités d'IA, eesel AI offre une intégration directe qui transforme votre base de connaissances en un agent de soutien intelligent. Aucun développement d'API personnalisé n'est requis.
Foire aux questions
Share this article
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
