zendesk-guide-api-content-management
eesel Team
Last edited 26 février 2026
{
"title": "Gestion du contenu avec l'API Zendesk Guide : Un guide complet pour les développeurs",
"slug": "zendesk-guide-api-content-management",
"locale": "fr",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Un guide pratique pour les développeurs sur la gestion programmatique du contenu de Zendesk Guide, avec des modèles d'authentification, des points de terminaison API et des exemples de code fonctionnels.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk API",
"Guide API",
"Content Management",
"Developer Guide",
"Help Center API"
],
"readTime": 8,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Gestion du contenu avec l'API Zendesk Guide : Un guide complet pour les développeurs",
"description": "Un guide pratique pour les développeurs sur la gestion programmatique du contenu de Zendesk Guide, avec des modèles d'authentification, des points de terminaison API et des exemples de code fonctionnels.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-db52e74f-4912-436b-828b-fea149a53332"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-db52e74f-4912-436b-828b-fea149a53332",
"coverImageAlt": "Image de bannière pour la gestion du contenu avec l'API Zendesk Guide : Un guide complet pour les développeurs",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Foire aux questions",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Quelle méthode d'authentification la gestion du contenu avec l'API Zendesk Guide requiert-elle ?",
"answer": "Vous pouvez utiliser l'authentification par jeton API (recommandée pour une utilisation sur un seul compte) ou OAuth (requise pour les applications multi-clients). Les jetons API sont générés dans le Centre d'administration et utilisés avec l'authentification de base au format email/token:token."
},
{
"question": "Quelles sont les limites de débit pour les opérations de gestion du contenu avec l'API Zendesk Guide ?",
"answer": "La plupart des points de terminaison autorisent 700 requêtes par minute. Si vous dépassez cette limite, vous recevrez un code d'état 429. Mettez en œuvre une logique de nouvelle tentative avec un repli exponentiel pour les intégrations de production."
},
{
"question": "Puis-je utiliser la gestion du contenu avec l'API Zendesk Guide sur n'importe quel niveau de plan ?",
"answer": "L'accès de base à l'API Guide est disponible sur les plans Suite Team et supérieurs. Cependant, certaines fonctionnalités comme le contenu dynamique nécessitent des plans Professional ou supérieurs. Vérifiez votre cas d'utilisation spécifique par rapport aux fonctionnalités du plan de Zendesk."
},
{
"question": "Comment gérer les téléchargements de fichiers avec la gestion du contenu avec l'API Zendesk Guide ?",
"answer": "Les téléchargements de fichiers utilisent un processus en 3 étapes : (1) demandez une URL de téléchargement avec les métadonnées du fichier, (2) placez le fichier sur l'URL signée, (3) créez l'objet multimédia avec l'ID de l'actif. La taille maximale du fichier est de 20 Mo."
},
{
"question": "Quelle est la différence entre l'utilisation de la gestion du contenu avec l'API Zendesk Guide et une plateforme d'intégration comme eesel AI ?",
"answer": "L'API Guide nécessite un développement personnalisé et est préférable pour les flux de travail uniques ou les migrations à grande échelle. Les plateformes d'intégration comme eesel AI offrent des alternatives sans code qui connectent vos sources de connaissances existantes à Zendesk sans écrire de scripts."
},
{
"question": "La gestion du contenu avec l'API Zendesk Guide prend-elle en charge les opérations en bloc ?",
"answer": "Oui. L'API Content Tags prend en charge les opérations par lots via le point de terminaison des tâches pour les actions de suppression et de fusion. Pour les autres points de terminaison, mettez en œuvre la pagination et parcourez les enregistrements par programme."
}
],
"supportLink": null
}
}
---
La gestion du contenu du centre d'aide à grande échelle devient fastidieuse lorsque vous le faites manuellement. Que vous migriez des articles depuis une autre plateforme, que vous synchronisiez des actifs depuis votre équipe marketing ou que vous organisiez du contenu sur plusieurs marques, l'API Zendesk Guide vous offre un contrôle programmatique sur votre base de connaissances.
Ce guide vous explique tout ce que vous devez savoir sur la gestion du contenu avec l'API Zendesk Guide. Nous aborderons l'authentification, les points de terminaison principaux, les modèles d'implémentation pratiques et quand il est judicieux d'utiliser l'API par rapport à des alternatives comme [eesel AI](https://www.eesel.ai).
## Ce dont vous aurez besoin
Avant de plonger, assurez-vous d'avoir :
- Un [compte Zendesk](https://www.zendesk.com) avec Guide activé (plan Suite Team ou supérieur)
- Un accès administrateur pour générer des jetons API
- Une connaissance de base des API REST et de JSON
- Votre client HTTP préféré (cURL, Postman ou un langage de programmation comme Python)
## Comprendre l'authentification de l'API Zendesk Guide
L'API Zendesk Guide utilise les mêmes modèles d'authentification que les autres API Zendesk. Voici ce que vous devez savoir.
### Authentification par jeton API (recommandée)
Les jetons API sont le moyen le plus simple de s'authentifier. Vous les générerez dans le [Centre d'administration](https://support.zendesk.com/hc/en-us/articles/4408827565338) sous Applications et intégrations > API > API Zendesk.
**Détails importants :**
- Formatez vos informations d'identification comme `{email_address}/token:{api_token}`
- Encodez en Base64 la chaîne entière pour l'en-tête Authorization
- Vous pouvez avoir jusqu'à 256 jetons actifs (2048 pour les anciens comptes)
- Les jetons peuvent usurper l'identité de n'importe quel utilisateur, y compris les administrateurs, alors gardez-les en sécurité
**Exemple de requête cURL :**
```bash
curl https://{subdomain}.zendesk.com/api/v2/guide/medias \
-v -u {email_address}/token:{api_token}
OAuth pour les applications multi-clients
Si vous créez une intégration qui sera distribuée à plusieurs clients Zendesk, vous devrez utiliser OAuth au lieu de jetons API. Les jetons API réguliers ne fonctionneront pas pour les applications qui doivent s'authentifier sur différentes instances Zendesk.
Limites de débit et SSL
La plupart des points de terminaison autorisent 700 requêtes par minute. Si vous atteignez la limite, vous obtiendrez un code d'état 429. Toutes les requêtes doivent utiliser HTTPS avec TLS 1.2 ou supérieur.
Points de terminaison principaux de la gestion du contenu
L'API Guide offre plusieurs points de terminaison pour gérer différents types de contenu. Décomposons les plus utiles.
API Guide Medias
L'API Guide Medias gère les téléchargements de fichiers et la gestion des médias pour votre centre d'aide Zendesk. Ceci est essentiel lorsque vous souhaitez ajouter par programme des images ou des pièces jointes aux articles.
Le processus de téléchargement en 3 étapes :
- Demander une URL de téléchargement POST à
/api/v2/guide/medias/upload_urlavec le type de contenu et la taille du fichier - Télécharger le fichier PUT le fichier à l'URL signée renvoyée à l'étape 1
- Créer l'objet multimédia POST à
/api/v2/guide/mediasavec l'ID de téléchargement de l'actif
Les fichiers peuvent atteindre 20 Mo. L'API utilise des identificateurs basés sur ULID, qui sont triables contrairement aux UUID traditionnels.
Exemple Python :
import requests
import base64
auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {auth}", "Content-Type": "application/json"}
upload_data = {"content_type": "image/png", "file_size": 12345}
response = requests.post(
f"https://{subdomain}.zendesk.com/api/v2/guide/medias/upload_url",
json=upload_data,
headers=headers
)
upload_url = response.json()["upload_url"]["url"]
asset_id = response.json()["upload_url"]["asset_upload_id"]
media_data = {"asset_upload_id": asset_id, "filename": "screenshot.png"}
media = requests.post(
f"https://{subdomain}.zendesk.com/api/v2/guide/medias",
json=media_data,
headers=headers
)
API Content Tags
Les balises de contenu vous aident à organiser les articles et les publications. L'API Content Tags vous permet de créer, de mettre à jour et de gérer les balises par programme.
Capacités clés :
- Créer et gérer des balises avec des requêtes POST/PUT/DELETE
- Opérations par lots via
/api/v2/guide/content_tags/jobs(supprimer ou fusionner des balises) - Filtrer les balises par préfixe de nom
- Trier par ID ou nom par ordre croissant ou décroissant
Les opérations par lots sont utiles pour les tâches de nettoyage, comme la fusion de balises en double ou la suppression de balises obsolètes dans l'ensemble de votre base de connaissances.
API Dynamic Content
Si vous prenez en charge plusieurs langues, l'API Dynamic Content est essentielle. Elle gère les variantes de contenu localisées à l'aide d'espaces réservés comme {{dc.password_reset_instructions}}.
Comment ça marche :
- Chaque élément de contenu dynamique a une langue par défaut et plusieurs variantes
- Les variantes contiennent le texte traduit réel
- Zendesk sert automatiquement la bonne variante en fonction de la langue de l'utilisateur
- Revient à la valeur par défaut si aucune variante correspondante n'existe
Remarque : Le contenu dynamique nécessite un plan Professional ou supérieur.
API External Content Sources
L'API External Content Sources permet la recherche fédérée, vous permettant d'extraire les résultats de systèmes externes dans votre recherche du centre d'aide.
Cas d'utilisation :
- Indexation du contenu d'un système de gestion de l'apprentissage
- Inclusion des publications du forum dans les résultats de recherche
- Rendre les problèmes Jira consultables depuis le centre d'aide
Cela nécessite des autorisations de gestionnaire du centre d'aide et fonctionne avec l'explorateur de Zendesk pour indexer le contenu externe.
Mise en œuvre pratique : Automatisation des téléchargements de médias
Examinons un scénario réel. Votre équipe marketing crée des captures d'écran dans Figma et les enregistre dans Google Drive. Vous souhaitez qu'elles soient automatiquement ajoutées à votre galerie de médias Zendesk afin que les rédacteurs puissent les utiliser dans les articles.
Voici une implémentation Python complète :
import requests
import base64
import time
class ZendeskMediaUploader:
def __init__(self, subdomain, email, token):
self.subdomain = subdomain
self.base_url = f"https://{subdomain}.zendesk.com/api/v2"
self.auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
self.headers = {
"Authorization": f"Basic {self.auth}",
"Content-Type": "application/json"
}
def upload_file(self, file_path, content_type):
"""Upload a file to Zendesk media gallery."""
file_size = os.path.getsize(file_path)
filename = os.path.basename(file_path)
# Step 1: Get upload URL
upload_data = {"content_type": content_type, "file_size": file_size}
resp = requests.post(
f"{self.base_url}/guide/medias/upload_url",
json=upload_data,
headers=self.headers
)
resp.raise_for_status()
upload_info = resp.json()["upload_url"]
# Step 2: Upload file to signed URL
with open(file_path, "rb") as f:
put_headers = {
"Content-Disposition": upload_info["headers"]["Content-Disposition"],
"Content-Type": content_type,
"X-Amz-Server-Side-Encryption": "AES256"
}
put_resp = requests.put(upload_info["url"], data=f, headers=put_headers)
put_resp.raise_for_status()
# Step 3: Create media object
media_data = {
"asset_upload_id": upload_info["asset_upload_id"],
"filename": filename
}
media_resp = requests.post(
f"{self.base_url}/guide/medias",
json=media_data,
headers=self.headers
)
media_resp.raise_for_status()
return media_resp.json()["media"]
Conseils de gestion des erreurs :
- 401 Non autorisé : Vérifiez votre jeton et le format de l'e-mail (doit inclure
/token) - 403 Interdit : Vérifiez que vous disposez des autorisations de gestionnaire Guide
- 409 Conflit : Réessayez la requête (erreur transitoire)
- 429 Limite de débit : Mettez en œuvre un repli exponentiel
Quand utiliser l'API Zendesk Guide par rapport aux alternatives
L'API n'est pas toujours le bon choix. Voici comment vous déciderez.
Utilisez l'API lorsque :
- Vous devez migrer de grandes quantités de contenu depuis une autre plateforme
- Vous créez une intégration personnalisée avec vos outils existants
- Vous souhaitez automatiser les tâches répétitives (comme le balisage en bloc)
- Vous disposez de ressources de développement disponibles pour la maintenance continue
Envisagez les fonctionnalités natives de Zendesk lorsque :
- Vous n'avez besoin que de téléchargements manuels occasionnels
- Votre équipe est à l'aise de travailler dans l'interface Zendesk
- La recherche fédérée répond à vos besoins de contenu externe sans code
Envisagez les plateformes d'intégration lorsque :
- Vous avez besoin d'une automatisation simple sans code personnalisé
- Votre cas d'utilisation correspond aux déclencheurs et actions standard
- Vous voulez que quelque chose fonctionne rapidement sans temps de développement
Envisagez eesel AI lorsque :
Vous pourriez envisager eesel AI si votre objectif est de rendre votre base de connaissances Zendesk plus intelligente sans créer d'intégrations personnalisées. Au lieu d'écrire des scripts pour synchroniser le contenu, eesel se connecte directement à Zendesk, Confluence, Google Docs et d'autres sources.
Voici la différence : l'API Guide vous permet de déplacer du contenu dans Zendesk par programme. eesel AI indexe votre contenu là où il se trouve et le rend accessible à votre équipe de support via un Agent AI qui fonctionne à l'intérieur de Zendesk. Vous ne migrez rien. Vous n'écrivez pas de code. Vous connectez vos sources et l'IA apprend d'elles.
Pour les équipes sans développeurs dédiés, cela peut être un chemin plus rapide vers une connaissance unifiée. Nos prix commencent à 299 $/mois pour le plan Team, qui comprend jusqu'à 3 robots et 1 000 interactions avec l'IA.
Bonnes pratiques et dépannage
Sécurité
- Stockez les jetons API dans des variables d'environnement, jamais dans votre code
- Faites pivoter les jetons régulièrement (Zendesk vous permet d'en avoir jusqu'à 256, vous pouvez donc en créer de nouveaux avant de supprimer les anciens)
- Utilisez des jetons distincts pour différentes intégrations afin de pouvoir en révoquer un sans affecter les autres
Pagination
Les points de terminaison de liste renvoient des résultats paginés. Utilisez la pagination basée sur le curseur pour les grands ensembles de données (elle est plus fiable que la pagination de décalage pour la modification des données) :
params = {"page[size]": 100}
while True:
resp = requests.get(url, params=params, headers=headers)
data = resp.json()
# Process records
for record in data["records"]:
process(record)
# Check for more pages
if not data["meta"]["has_more"]:
break
params["page[after]"] = data["meta"]["after_cursor"]
Tests
- Testez dans un environnement sandbox avant d'exécuter en production
- Utilisez la collection Postman de Zendesk pour explorer les points de terminaison
- Enregistrez les réponses de l'API pendant le développement pour comprendre les conditions d'erreur
Pièges courants
- Oublier le suffixe
/tokendans l'adresse e-mail - Ne pas encoder en Base64 les informations d'identification
- Atteindre les limites de débit lors des opérations en bloc
- Ne pas gérer les conflits 409 avec la logique de nouvelle tentative
Commencez à gérer le contenu Zendesk plus efficacement
L'API Zendesk Guide vous offre des outils puissants pour la gestion du contenu à grande échelle. Que vous automatisiez les téléchargements de médias, organisiez le contenu avec des balises ou créiez une prise en charge multilingue, l'API fournit les primitives dont vous avez besoin.
Mais la création d'intégrations personnalisées n'est pas la seule voie. Si vous souhaitez unifier vos sources de connaissances sans écrire de code, eesel AI offre une alternative. Notre Agent AI se connecte à Zendesk et apprend de votre documentation existante où qu'elle se trouve, sans migration requise.
Le bon choix dépend des ressources techniques de votre équipe et de vos besoins spécifiques. Si vous avez des développeurs et des exigences uniques, l'API Guide est une base solide. Si vous souhaitez être opérationnel rapidement avec une assistance basée sur l'IA, explorez ce que eesel AI peut faire pour votre configuration Zendesk.
Partager cet article
Article by
