zendesk-guide-knowledge-base-api
eesel Team
Last edited 26 février 2026
{
"title": "API de la base de connaissances du Guide Zendesk : Le guide complet du développeur pour 2026",
"slug": "zendesk-guide-knowledge-base-api",
"locale": "fr",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Un guide technique complet de l'API du Centre d'aide Zendesk avec des exemples de code fonctionnels, des modèles d'authentification et les meilleures pratiques d'intégration pour les développeurs.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk API",
"Knowledge Base",
"Help Center API",
"Developer Guide",
"Customer Support"
],
"readTime": 10,
"author": 16,
"reviewer": 14,
"seo": {
"title": "API de la base de connaissances du Guide Zendesk : Le guide complet du développeur pour 2026",
"description": "Un guide technique complet de l'API du Centre d'aide Zendesk avec des exemples de code fonctionnels, des modèles d'authentification et les meilleures pratiques d'intégration pour les développeurs.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-3923a02a-382e-4c4c-a4bb-d10f99180563"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-3923a02a-382e-4c4c-a4bb-d10f99180563",
"coverImageAlt": "Image de la bannière pour l'API de la base de connaissances du Guide Zendesk : Le guide complet du développeur pour 2026",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Foire aux questions",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Quelle méthode d'authentification dois-je utiliser pour l'API de la base de connaissances du Guide Zendesk ?",
"answer": "Pour les scripts côté serveur et les intégrations backend, utilisez l'authentification par jeton API (API token). Elle est plus simple à implémenter et à gérer. Pour les applications côté client ou lorsque vous devez agir au nom d'utilisateurs individuels, utilisez OAuth 2.0. OAuth prend en charge CORS, ce qui le rend adapté aux applications basées sur un navigateur."
},
{
"question": "Comment gérer la pagination lors de la récupération de tous les articles via l'API de la base de connaissances du Guide Zendesk ?",
"answer": "Utilisez la pagination basée sur un curseur en ajoutant `?page[size]=100` à votre requête. Suivez l'URL `links.next` dans la réponse jusqu'à ce que `meta.has_more` soit faux. Cette méthode est plus rapide que la pagination par offset et n'a pas de limite de 10 000 enregistrements."
},
{
"question": "Quelles sont les limites de débit pour l'API de la base de connaissances du Guide Zendesk ?",
"answer": "Les limites de débit varient selon le plan : Suite Team obtient 200 requêtes/minute, Growth et Professional obtiennent 400/minute, Enterprise obtient 700/minute et Enterprise Plus obtient 2 500/minute. Si vous atteignez la limite, l'API renvoie un statut 429 avec un en-tête `Retry-After`."
},
{
"question": "Puis-je utiliser l'API de la base de connaissances du Guide Zendesk pour synchroniser le contenu avec des systèmes d'IA externes ?",
"answer": "Oui. Vous pouvez extraire des articles via l'API, convertir le contenu HTML dans votre format préféré (Markdown, texte brut) et l'intégrer dans des bases de données vectorielles ou des systèmes RAG. Alternativement, les plateformes d'intégration comme eesel AI peuvent gérer cette synchronisation automatiquement."
},
{
"question": "Quelle est la différence entre l'API du Centre d'aide Zendesk et l'API de la base de connaissances du Guide Zendesk ?",
"answer": "C'est la même chose. « API du Centre d'aide » est le nom officiel dans la documentation de Zendesk, tandis que « API de la base de connaissances du Guide » est un nom alternatif courant qui souligne sa connexion au produit Guide de Zendesk. Les deux font référence à l'API REST à l'adresse `/api/v2/help_center/`."
}
],
"supportLink": null
}
}
---
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](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) (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](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) 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 :
```bash
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):
@wraps(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
@with_rate_limit_retry
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.
Partager cet article
Article by
