API de Requêtes Zendesk : Un guide complet pour les utilisateurs finaux (2026)

Lorsque vous créez un portail client ou une intégration en libre-service, vous avez besoin d’un moyen pour les utilisateurs finaux de créer et de consulter des tickets sans leur donner un accès administrateur complet. L’API de Requêtes Zendesk est conçue exactement à cet effet.

L’API de Requêtes fournit le point de vue d’un utilisateur final sur les tickets. Les utilisateurs peuvent créer des requêtes, consulter l’historique de leurs tickets et ajouter des commentaires, tout en ne voyant que les informations publiques. C’est l’alternative sécurisée à accès limité à l’API de Tickets complète.

Si vous cherchez à automatiser le support sans créer d’intégrations API personnalisées, des outils comme eesel AI peuvent gérer l’ensemble du spectre de l’automatisation du support, du routage des tickets aux réponses basées sur l’IA. eesel s’intègre directement à Zendesk et apprend à partir de vos tickets et de votre documentation existants. Mais si vous avez besoin d’un accès API direct pour des intégrations personnalisées, ce guide vous expliquera tout ce que vous devez savoir.

Ce dont vous aurez besoin

Avant de commencer à faire des appels API, assurez-vous d’avoir :

• Un compte Zendesk avec les autorisations appropriées (accès administrateur pour configurer les jetons API)
• Un jeton API ou des identifiants OAuth (nous verrons comment les générer)
• Une connaissance de base des API REST (vous devez comprendre les requêtes GET, POST et PUT)
• Un environnement de développement (cURL, Python ou Node.js feront l’affaire)

Comprendre l’API de Requêtes

Qu’est-ce qu’une requête ?

Dans Zendesk, une requête est le point de vue d’un utilisateur final sur un ticket. Alors que les agents voient le ticket complet avec les notes internes, les champs personnalisés et les commentaires privés, les utilisateurs finaux ne voient que les commentaires publics et un ensemble limité de champs.

Voici à quoi ressemble le format JSON pour une requête :

{
  "id": 35436,
  "subject": "Au secours, mon imprimante est en feu !",
  "description": "Le feu est très coloré.",
  "status": "open",
  "priority": "normal",
  "type": "problem",
  "requester_id": 1462,
  "created_at": "2009-07-20T22:55:29Z",
  "updated_at": "2011-05-05T10:38:52Z"
}

Les propriétés clés comprennent :

• subject (obligatoire) : la ligne d’objet visible par l’utilisateur final
• description : premier commentaire en lecture seule sur la requête
• status : nouveau, ouvert, en attente, en suspens, résolu ou fermé
• priority : faible, normale, élevée ou urgente
• type : question, incident, problème ou tâche

Source : Référence de l’API de Requêtes Zendesk

API de Requêtes vs API de Tickets : laquelle utiliser ?

Il s’agit d’une décision essentielle qui affectera le comportement de votre intégration. Voici la ventilation :

Le problème d’Agent Copilot est important. Lorsque vous créez un ticket via l’API de Tickets au nom d’un utilisateur final, Zendesk l’interprète comme créé par un agent. Cela signifie qu’Agent Copilot ne se déclenchera pas car il attend une réponse du client qui ne vient jamais. L’utilisation de l’API de Requêtes garantit que les tickets se comportent exactement comme ceux créés par e-mail ou par messagerie.

Source : Note interne - Requêtes API et Agent Copilot

Méthodes d’authentification

Authentification de l’utilisateur final

Les utilisateurs finaux peuvent s’authentifier en utilisant leurs propres identifiants. Lors de l’utilisation du point de terminaison Requêtes, les administrateurs et les agents sont traités comme des utilisateurs finaux, ils voient donc la même vue limitée.

Authentification par jeton API :

curl https://your-subdomain.zendesk.com/api/v2/requests.json \
  -u user@example.com/token:your_api_token_here

Remarque importante : Un utilisateur final ne pourra pas consulter ses requêtes s’il a ajouté une identité d’e-mail après le 17 septembre 2017 et n’a pas vérifié l’adresse e-mail. L’API renvoie une réponse 403 dans ce cas.

Source : Référence de l’API de Requêtes Zendesk

Faire des requêtes au nom des utilisateurs finaux (usurpation d’identité de l’administrateur)

Parfois, vous aurez besoin qu’un administrateur crée des tickets pour les utilisateurs finaux. Cela nécessite OAuth avec une portée d’usurpation d’identité.

Étape 1 : Créez un client OAuth dans le Centre d’administration (Applications et intégrations > API > Clients OAuth)

Étape 2 : Demandez un jeton d’accès avec la portée « impersonate » :

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
  -H "Content-Type: application/json" \
  -d '{
    "token": {
      "client_id": "your_client_id",
      "scopes": ["impersonate", "write"]
    }
  }' \
  -X POST -v -u {email_address}/token:{api_token}

Étape 3 : Incluez l’en-tête X-On-Behalf-Of dans vos requêtes :

curl https://z3napi.zendesk.com/api/v2/requests.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: customer@example.com" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Demande d’aide",
      "comment": {"body": "J’ai besoin d’aide avec ma commande"}
    }
  }'

Important : L’utilisateur final usurpé doit avoir un profil utilisateur existant. Sinon, la requête échouera avec une erreur invalid_token.

Source : Faire des requêtes API au nom des utilisateurs finaux

Requêtes anonymes

Si votre administrateur Zendesk l’a activé, vous pouvez créer des requêtes sans aucune authentification. Ceci est utile pour les formulaires de contact publics.

Exigences :

• Les requêtes anonymes doivent être activées dans le Centre d’administration
• Incluez un objet requester avec au moins un nom

{
  "request": {
    "requester": {"name": "Client anonyme"},
    "subject": "Au secours !",
    "comment": {"body": "Mon imprimante est en feu !"}
  }
}

Limites de débit : Les requêtes anonymes sont limitées à 5 par heure pour les comptes d’essai.

Source : Création et gestion des requêtes

Principaux points de terminaison API

Lister les requêtes

Récupérer toutes les requêtes pour l’utilisateur authentifié :

GET /api/v2/requests

Paramètres :

• page : Pagination (prend en charge le décalage ou basé sur le curseur)
• per_page : Nombre d’enregistrements par page
• sort_by : « updated_at » ou « created_at »
• sort_order : « asc » ou « desc »

Créer une requête

Créer un nouveau ticket du point de vue d’un utilisateur final :

POST /api/v2/requests

Champs obligatoires :

• subject : L’objet du ticket
• comment : Objet avec body contenant la description

Champs facultatifs :

• requester : Pour les requêtes anonymes (objet avec nom, e-mail)
• collaborators : Tableau d’ID d’utilisateur ou d’e-mails à mettre en copie (CC)
• custom_fields : Tableau de valeurs de champs personnalisés
• tags : Tableau de balises à appliquer

Mettre à jour une requête

Ajouter des commentaires ou marquer une requête comme résolue :

PUT /api/v2/requests/{id}

Propriétés inscriptibles :

• comment : Ajouter un nouveau commentaire
• solved : Définir sur true pour marquer comme résolu (uniquement si can_be_solved_by_me est vrai)
• additional_collaborators : Ajouter des CC à la requête

Lister les commentaires

Afficher l’historique des conversations :

GET /api/v2/requests/{request_id}/comments

Par défaut, les commentaires sont triés par date de création par ordre croissant.

Source : Référence de l’API de Requêtes Zendesk

Exemples de code

Création d’une requête avec cURL

#!/bin/bash

SUBDOMAIN="your-subdomain"
EMAIL="admin@example.com"
TOKEN="your_api_token"

curl "https://${SUBDOMAIN}.zendesk.com/api/v2/requests.json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Demande d’état de la commande",
      "comment": {
        "body": "J’ai passé une commande la semaine dernière et j’aimerais vérifier l’état. Mon numéro de commande est #12345."
      },
      "collaborators": ["spouse@example.com"]
    }
  }'

Création d’une requête avec Python

import requests
import json

subdomain = "your-subdomain"
email = "admin@example.com"
api_token = "your_api_token"

url = f"https://{subdomain}.zendesk.com/api/v2/requests.json"

payload = {
    "request": {
        "subject": "Besoin d’assistance technique",
        "comment": {
            "body": "J’ai des difficultés à me connecter à mon compte. Pouvez-vous m’aider ?"
        }
    }
}

auth = (f"{email}/token", api_token)
headers = {"Content-Type": "application/json"}

try:
    response = requests.post(url, json=payload, auth=auth, headers=headers)
    response.raise_for_status()

    data = response.json()
    print(f"Requête créée avec succès !")
    print(f"ID de ticket : {data['request']['id']}")
    print(f"Statut : {data['request']['status']}")

except requests.exceptions.HTTPError as err:
    print(f"Erreur HTTP : {err}")
    print(f"Réponse : {response.text}")
except Exception as err:
    print(f"Erreur : {err}")

Création d’une requête avec Node.js

const axios = require('axios');

const config = {
  subdomain: 'your-subdomain',
  email: 'admin@example.com',
  apiToken: 'your_api_token'
};

async function createRequest() {
  const url = `https://${config.subdomain}.zendesk.com/api/v2/requests.json`;

  const payload = {
    request: {
      subject: 'Question de facturation',
      comment: {
        body: 'J’ai été facturé deux fois pour mon abonnement ce mois-ci. Veuillez m’aider à résoudre ce problème.'
      }
    }
  };

  try {
    const response = await axios.post(url, payload, {
      auth: {
        username: `${config.email}/token`,
        password: config.apiToken
      },
      headers: {
        'Content-Type': 'application/json'
      }
    });

    console.log('Requête créée avec succès !');
    console.log(`ID de ticket : ${response.data.request.id}`);
    console.log(`Statut : ${response.data.request.status}`);

  } catch (error) {
    console.error('Erreur lors de la création de la requête :', error.response?.data || error.message);
  }
}

createRequest();

Erreurs courantes et dépannage

403 Interdit

Il s’agit de l’erreur la plus courante lors de l’utilisation de l’API de Requêtes. Causes courantes :

• E-mail non vérifié : L’utilisateur final a ajouté un e-mail après le 17 septembre 2017 sans le vérifier
• Autorisations insuffisantes : Tentative d’accès à des points de terminaison non autorisés pour les utilisateurs finaux
• Portée d’usurpation d’identité manquante : Tentative de faire des requêtes au nom des utilisateurs sans la portée OAuth appropriée

Solution : Vérifiez l’adresse e-mail de l’utilisateur dans l’administration Zendesk ou assurez-vous que vous utilisez la méthode d’authentification correcte pour votre cas d’utilisation.

401 Non autorisé

• Jeton API ou identifiants OAuth non valides
• Le jeton a expiré (les jetons OAuth ont une durée de vie limitée)
• Le compte d’utilisateur est suspendu ou supprimé

Solution : Vérifiez vos identifiants et régénérez les jetons si nécessaire.

429 Limite de débit dépassée

• API standard : 700 requêtes par minute
• Requêtes anonymes : 5 par heure (comptes d’essai)

Solution : Implémentez une interruption exponentielle dans votre code. Lorsque vous recevez un 429, attendez avant de réessayer :

import time

def make_request_with_retry(url, payload, auth, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, auth=auth)
            response.raise_for_status()
            return response
        except requests.exceptions.HTTPError as err:
            if response.status_code == 429:
                wait_time = (2 ** attempt)  # Interruption exponentielle
                print(f"Limite de débit atteinte. Attente de {wait_time} secondes...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Nombre maximal de tentatives dépassé")

Agent Copilot ne se déclenche pas

Si vous utilisez Agent Copilot de Zendesk et qu’il ne suggère pas de réponses pour les tickets créés via l’API, vous utilisez probablement l’API de Tickets au lieu de l’API de Requêtes.

Solution : Passez à l’API de Requêtes (POST /api/v2/requests.json) au lieu de l’API de Tickets (POST /api/v2/tickets.json).

Source : Note interne - Requêtes API et Agent Copilot

Bonnes pratiques

Utilisez l’API de Requêtes pour les intégrations destinées aux utilisateurs finaux

Si vous créez un portail client, un widget en libre-service ou toute interface où les utilisateurs finaux créent des tickets, utilisez toujours l’API de Requêtes. Cela garantit :

• Un comportement approprié d’Agent Copilot
• Des calculs corrects du délai de première réponse
• Un cycle de vie de ticket cohérent avec les tickets créés par e-mail

Gérez les limites de débit avec élégance

Implémentez toujours une logique de nouvelle tentative avec une interruption exponentielle. L’API de Zendesk est partagée entre tous les clients, et un sondage agressif peut entraîner une limitation de débit ou un blocage de votre intégration.

Validez l’état de vérification de l’e-mail

Avant d’autoriser les utilisateurs à consulter leurs requêtes, vérifiez que leur e-mail est confirmé. Vous pouvez vérifier cela via l’API Utilisateurs et leur demander de vérifier si nécessaire.

Stockez les identifiants en toute sécurité

Ne codez pas en dur les jetons API dans votre code frontal ou ne les validez pas dans le contrôle de version. Utilisez des variables d’environnement ou des systèmes de gestion des secrets sécurisés.

Envisagez des alternatives sans code

La création et la maintenance des intégrations API nécessitent des ressources de développement importantes. Si votre objectif est d’automatiser les réponses de support plutôt que de créer des portails personnalisés, envisagez des outils comme eesel AI qui s’intègrent directement à Zendesk et fournissent une automatisation basée sur l’IA sans écrire de code. eesel AI ne nécessite pas de configuration complexe, il vous suffit de l’inviter dans votre équipe et il apprend votre activité en quelques minutes.

Nous offrons :

• Agent d’IA qui gère le support de première ligne de manière autonome
• Copilote d’IA qui rédige des réponses que les agents peuvent examiner
• Triage d’IA qui balise, achemine et hiérarchise automatiquement les tickets
• Intégration en un clic avec Zendesk (aucun développement API requis)

Source : Produits eesel AI

Commencez à créer avec l’API de Requêtes Zendesk

L’API de Requêtes Zendesk vous offre un moyen sécurisé de permettre aux utilisateurs finaux d’interagir avec votre système de support. En comprenant la différence entre les API de Requêtes et de Tickets, en mettant en œuvre une authentification appropriée et en suivant les bonnes pratiques, vous pouvez créer des intégrations en libre-service robustes.

Principaux points à retenir :

• Utilisez l’API de Requêtes pour les intégrations destinées aux utilisateurs finaux
• Mettez en œuvre OAuth avec une portée d’usurpation d’identité lorsque les administrateurs doivent agir au nom des utilisateurs
• Gérez les limites de débit et les erreurs avec élégance
• Testez minutieusement avant de déployer en production

Pour plus de détails, consultez la documentation officielle de l’API de Requêtes Zendesk.

Si vous cherchez à automatiser le support sans les frais généraux de développement, découvrez comment eesel AI peut vous aider. Nos agents d’IA s’intègrent directement à Zendesk, apprennent à partir de votre documentation existante et de vos tickets passés, et peuvent gérer jusqu’à 81 % du support de première ligne de manière autonome.