API de requête d'application Zendesk : Un guide complet pour les développeurs pour 2026

Si vous développez une application Zendesk, vous devrez éventuellement effectuer des requêtes API. Peut-être que vous récupérez des données d'un service externe, que vous créez des tickets de manière programmatique ou que vous vous intégrez à une autre plateforme. L'API de requête d'application Zendesk vous offre plusieurs façons de le faire, mais la documentation est répartie sur plusieurs pages et les options d'authentification peuvent être déroutantes.

Ce guide regroupe tout ce que vous devez savoir sur la façon d'effectuer des requêtes API à partir d'applications Zendesk. Nous aborderons la méthode request() du client ZAF, le point de terminaison API Requests, les stratégies d'authentification et les pièges courants que rencontrent les développeurs. Si vous recherchez un moyen plus simple d'automatiser les flux de travail Zendesk sans écrire de code personnalisé, nous aborderons également la façon dont eesel AI s'intègre à Zendesk pour gérer la gestion des tickets grâce à des agents d'IA.

Qu'est-ce que l'API de requête d'application Zendesk ?

Lorsque les développeurs recherchent « API de requête d'application Zendesk », ils recherchent généralement l'une des deux choses suivantes :

1. La méthode request() du client ZAF – Une fonction JavaScript qui permet à votre application Zendesk d'effectuer des requêtes HTTP vers des API externes ou l'API Zendesk elle-même
2. Le point de terminaison API Requests – Une API REST qui permet aux utilisateurs finaux de créer et de consulter des tickets de leur point de vue

La méthode request() de ZAF est ce que vous utilisez lorsque vous créez des applications qui s'exécutent à l'intérieur de Zendesk. Elle gère l'authentification, évite les restrictions interdomaines et gère la complexité des appels API sécurisés à partir d'un environnement de navigateur. L'API Requests est ce que vous appelez lorsque vous souhaitez permettre aux clients de soumettre des tickets sans leur donner un accès complet en tant qu'agent.

Décomposons le fonctionnement de chacun et quand les utiliser.

Comprendre la méthode request() du client ZAF

Le Zendesk Apps Framework (ZAF) fournit un client JavaScript qui s'exécute à l'intérieur de votre application. La méthode client.request() est votre passerelle pour effectuer des requêtes HTTP depuis l'environnement Zendesk.

Voici pourquoi elle existe : les navigateurs bloquent les requêtes inter-origines pour des raisons de sécurité. Si votre application tente d'appeler une API externe directement, vous rencontrerez des erreurs CORS. ZAF résout ce problème en acheminant vos requêtes via un serveur proxy Zendesk. Le proxy effectue la requête réelle et renvoie la réponse à votre application.

La méthode request() renvoie une promesse JavaScript (Promise), vous gérez donc les réponses avec .then() ou async/await :

const client = ZAFClient.init();

client.request({
  url: 'https://api.example.com/data',
  type: 'GET',
  headers: {
    'Authorization': 'Bearer {{setting.api_token}}'
  }
}).then(data => {
  console.log('Response:', data);
}).catch(error => {
  console.error('Error:', error);
});

Principales capacités de la méthode request() :

• Routage du serveur proxy – Évite CORS en effectuant des requêtes côté serveur
• Paramètres sécurisés – Masque les clés API des outils de développement du navigateur à l'aide d'espaces réservés manifest.json
• Gestion des jetons OAuth – Gère les flux OAuth tiers sans exposer les jetons
• Encodage JWT – Signe les requêtes avec des jetons Web JSON (JSON Web Tokens) pour plus de sécurité

Une limitation à noter : la méthode request() ne prend pas en charge les téléchargements de fichiers binaires. Si vous devez joindre des fichiers, vous devrez utiliser une approche différente (plus d'informations à ce sujet plus tard).

Méthodes d'authentification pour les requêtes d'application Zendesk

L'authentification est l'endroit où la plupart des développeurs sont bloqués. Zendesk propose plusieurs méthodes d'authentification, et le choix de la bonne dépend de ce que vous essayez de faire.

Authentification de base avec des jetons API

L'approche la plus simple pour appeler l'API Zendesk elle-même. Formatez vos informations d'identification sous la forme {email}/token:{api_token}, encodez-les en base64 et incluez-les dans l'en-tête Authorization avec le préfixe « Basic » :

const credentials = btoa('agent@company.com/token:abc123xyz');
const authHeader = `Basic ${credentials}`;

Erreur courante : oublier le préfixe « Basic ». L'en-tête doit commencer par « Basic » suivi d'un espace, puis de la chaîne encodée en base64. De nombreux développeurs encodent correctement les informations d'identification, mais omettent le préfixe, ce qui entraîne des erreurs 401 Non autorisé.

Paramètres sécurisés

Si vous appelez une API tierce, vous ne voulez pas exposer les clés API dans votre JavaScript où tout le monde peut les voir dans la console du navigateur. Les paramètres sécurisés résolvent ce problème en stockant les données sensibles côté serveur.

Dans votre manifest.json :

{
  "parameters": [
    {
      "name": "api_token",
      "type": "text",
      "secure": true
    }
  ],
  "domainWhitelist": ["api.example.com"]
}

Référencez le paramètre dans votre code avec des doubles accolades :

headers: {
  'Authorization': 'Bearer {{setting.api_token}}'
}

La valeur réelle du jeton est stockée sur les serveurs de Zendesk et injectée au moment de la requête. Les utilisateurs la configurent lors de l'installation de l'application, et elle n'est jamais exposée dans le navigateur.

OAuth 2.0

Pour les intégrations avec des services comme Salesforce, Slack ou Google, OAuth est la norme. ZAF prend en charge le flux de code d'autorisation :

1. Votre application redirige l'utilisateur vers le fournisseur OAuth
2. L'utilisateur autorise l'accès
3. Le fournisseur redirige avec un code d'autorisation
4. Votre application échange le code contre un jeton d'accès
5. ZAF stocke le jeton en toute sécurité et l'actualise automatiquement

La configuration nécessite l'enregistrement de votre application auprès du fournisseur OAuth et la configuration des URL de redirection. Une fois configurée, la gestion des jetons est gérée automatiquement.

Jetons JWT

Pour les requêtes signées, ZAF prend en charge l'encodage JWT avec l'algorithme HS256. Vous fournissez une clé secrète, et ZAF génère des jetons avec des revendications comme l'heure d'expiration. Ceci est utile lorsque vous devez vérifier que les requêtes proviennent de votre application Zendesk et n'ont pas été falsifiées.

Authentification par cookie de navigateur

Lorsque vous appelez l'API Zendesk depuis votre application, vous pouvez ignorer complètement l'authentification explicite. Le client ZAF utilise automatiquement le cookie de session Zendesk du navigateur pour authentifier les requêtes. Cela ne fonctionne que pour les points de terminaison de l'API Zendesk, pas pour les API externes.

Quelle méthode d'authentification devez-vous utiliser ?

Pour plus de détails sur l'utilisation des API Zendesk, consultez notre guide sur l'API des tickets Zendesk.

Effectuer des requêtes vers des API tierces

Par défaut, ZAF achemine les requêtes via son serveur proxy. Ceci est contrôlé par l'option cors :

// Comportement par défaut - utilise le proxy (cors: false)
client.request({
  url: 'https://api.example.com/data',
  type: 'GET'
});

// Requête directe - nécessite la prise en charge de CORS sur l'API
client.request({
  url: 'https://api.example.com/data',
  type: 'GET',
  cors: true
});

L'approche du proxy fonctionne avec n'importe quelle API, mais ajoute de la latence. Les requêtes directes sont plus rapides, mais nécessitent que l'API prenne en charge les en-têtes CORS. La plupart des applications de production utilisent le proxy pour la fiabilité.

Voici un exemple de travail complet qui récupère des données d'une API externe à l'aide de paramètres sécurisés :

const client = ZAFClient.init();

async function fetchCustomerData(customerId) {
  try {
    const response = await client.request({
      url: `https://api.example.com/customers/${customerId}`,
      type: 'GET',
      headers: {
        'Authorization': 'Bearer {{setting.api_key}}',
        'Content-Type': 'application/json'
      }
    });

    return response;
  } catch (error) {
    console.error('Failed to fetch customer:', error);
    throw error;
  }
}

La gestion des erreurs est importante. La promesse (Promise) est rejetée si la requête échoue, alors enveloppez toujours les appels dans try/catch ou utilisez .catch().

Utilisation de l'API Requests de Zendesk

L'API Requests est distincte de la méthode request() de ZAF. Il s'agit d'un point de terminaison API REST qui permet aux utilisateurs finaux (clients) d'interagir avec les tickets de leur point de vue.

Principales différences par rapport à l'API Tickets :

• Vue de l'utilisateur final – Ne voit que les commentaires publics et les champs auxquels l'utilisateur a accès
• Support anonyme – Peut être appelé sans authentification (limité en débit)
• Permissions simplifiées – Pas besoin d'informations d'identification d'agent

Points de terminaison courants :

Création d'une requête :

curl https://company.zendesk.com/api/v2/requests.json \
  -d '{"request": {"subject": "Help needed", "comment": {"body": "I have a question"}}}' \
  -H "Content-Type: application/json" \
  -X POST

Pour les requêtes authentifiées, incluez l'en-tête Authorization. Pour les requêtes anonymes (comme un formulaire de contact), omettez l'authentification. Les requêtes anonymes sont limitées à 5 par heure pour les comptes d'essai.

Si vous créez des intégrations qui créent des tickets, vous trouverez peut-être également utile notre guide sur la création de tickets Zendesk à l'aide de l'API.

Erreurs courantes et dépannage

Même avec une bonne documentation, les choses tournent mal. Voici les problèmes les plus courants que rencontrent les développeurs :

401 Non autorisé

L'en-tête d'authentification est mal formé. Vérifiez :

• Le préfixe « Basic » est présent (avec un espace après)
• Les informations d'identification sont correctement encodées en base64
• Le format de l'e-mail est {email}/token:{api_token} (notez le suffixe « /token »)
• Le jeton API est actif et n'a pas expiré

Erreurs CORS

Vous essayez d'effectuer une requête directe vers une API qui ne prend pas en charge CORS. Activez le proxy en omettant cors: true, ou demandez au fournisseur d'API d'ajouter des en-têtes CORS.

429 Limite de débit dépassée

Zendesk a plusieurs limites de débit. Les applications ont leur propre limite (généralement 100 requêtes par minute), et votre compte a une limite distincte (700 requêtes par minute pour la plupart des points de terminaison). Si vous atteignez un 429, vérifiez l'en-tête Retry-After et attendez avant de réessayer. Consultez la documentation officielle sur les limites de débit pour plus de détails.

422 Entité non traitable

Votre JSON est mal formé. Causes courantes :

• Guillemets manquants autour des noms de propriétés
• Virgules finales dans les objets
• Guillemets simples au lieu de guillemets doubles
• Séquences d'échappement non valides

Problèmes de téléchargement de fichiers

La méthode request() de ZAF ne prend pas en charge les téléchargements binaires. Les solutions de contournement incluent :

• Utiliser un serveur distinct pour gérer les téléchargements
• Encoder les fichiers en base64 et décoder côté serveur
• Utiliser une bibliothèque comme RestSharp pour la gestion binaire

Pour plus d'exemples d'intégration, consultez notre guide sur la connexion de Zendesk à Slack à l'aide d'applications tierces.

Créer des intégrations d'applications Zendesk sans code

Les intégrations API personnalisées prennent du temps à créer et à maintenir. Vous devez gérer l'authentification, la logique de nouvelle tentative d'erreur, la limitation de débit et la maintenance continue à mesure que les API changent.

Si votre objectif est d'automatiser les flux de travail des tickets plutôt que de créer une application personnalisée, déterminez si vous avez réellement besoin d'écrire du code. Notre agent d'IA pour Zendesk gère la création, le routage et les réponses des tickets sans aucun travail de développement.

Voici la différence : avec l'approche API, vous écrivez des scripts pour déplacer les tickets auxquels les humains devront toujours répondre. Avec un agent d'IA, vous formez un système pour comprendre votre entreprise et gérer l'ensemble du cycle de vie des tickets. Vous le connectez à votre compte Zendesk, et il apprend de vos tickets passés, de vos articles du centre d'aide et de vos macros.

Le modèle de déploiement progressif signifie que vous commencez par l'IA qui rédige des réponses pour examen, puis vous passez à l'automatisation complète à mesure qu'elle fait ses preuves. Pour les équipes qui cherchent à réduire le volume de tickets plutôt qu'à simplement automatiser les appels API, cela donne souvent des résultats plus rapides que le développement personnalisé.