Comment mettre à jour des tickets en utilisant l'API Zendesk en 2026

La gestion des tickets de support de manière programmatique est essentielle pour les équipes qui cherchent à automatiser les flux de travail, à s'intégrer à d'autres systèmes ou à créer des outils personnalisés. L'API de billetterie Zendesk vous donne un contrôle total sur les mises à jour des tickets, des simples changements de statut aux opérations en masse complexes impliquant des champs personnalisés.

Ce guide vous explique tout ce que vous devez savoir pour commencer à mettre à jour les tickets via l'API, avec des exemples de code fonctionnels que vous pouvez adapter à vos propres projets.

Ce dont vous aurez besoin pour commencer

Avant de faire votre premier appel API, assurez-vous que vous avez les éléments suivants en place :

• Un compte Zendesk Support avec un accès administrateur ou agent. Vous aurez besoin des autorisations pour générer des jetons API (API tokens) et afficher les données des tickets.
• L'authentification par jeton API activée. L'accès par jeton doit être activé dans votre Centre d'administration sous Applications et intégrations > API > Jetons API.
• Une connaissance de base des API REST. Vous devez comprendre les méthodes HTTP (GET, PUT, POST) et les formats de données JSON.
• Vos outils préférés. Ce guide inclut des exemples en cURL et Python en utilisant la bibliothèque Requests, mais vous pouvez utiliser Postman, JavaScript ou n'importe quel client HTTP.

Si vous débutez avec l'API Zendesk, vous voudrez peut-être consulter d'abord le guide de démarrage rapide de l'API. Il couvre les bases de la création de requêtes et de la gestion des réponses.

Configuration de l'authentification API

Zendesk utilise l'authentification basée sur un jeton (token) pour l'accès à l'API. Voici comment configurer cela.

Génération d'un jeton API

1. Connectez-vous à votre compte Zendesk en tant qu'administrateur
2. Allez dans Centre d'administration > Applications et intégrations > API > Jetons API
3. Cliquez sur l'icône plus pour ajouter un nouveau jeton
4. Donnez-lui un nom descriptif comme « Script de mise à jour des tickets »
5. Copiez le jeton immédiatement. Zendesk ne l'affiche qu'une seule fois.

Format d'authentification

Zendesk attend les informations d'identification dans ce format :

{adresse_email}/token:{jeton_api}

Par exemple, si votre e-mail est admin@company.com et que votre jeton est abc123xyz, votre chaîne d'authentification serait :

admin@company.com/token:abc123xyz

Stockage sécurisé des informations d'identification

Ne codez jamais en dur votre jeton API dans les scripts. Utilisez plutôt des variables d'environnement :

export ZENDESK_SUBDOMAIN="yourcompany"
export ZENDESK_EMAIL="admin@company.com"
export ZENDESK_TOKEN="your_api_token_here"

Ensuite, accédez-y en Python :

import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)

Test de votre authentification

Faites une simple requête GET pour vérifier que tout fonctionne :

curl "https://yourcompany.zendesk.com/api/v2/tickets.json?per_page=1" \
  -u "admin@company.com/token:your_api_token"

Si vous recevez une réponse JSON avec les données du ticket, vous êtes authentifié et prêt à continuer. Si vous obtenez une erreur 401, vérifiez votre jeton et votre adresse e-mail.

Mise à jour d'un seul ticket

L'endpoint pour la mise à jour des tickets est simple :

PUT /api/v2/tickets/{ticket_id}.json

Mise à jour de base avec cURL

Voici comment mettre à jour le statut d'un ticket et ajouter un commentaire :

curl "https://yourcompany.zendesk.com/api/v2/tickets/12345.json" \
  -X PUT \
  -u "admin@company.com/token:your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "status": "solved",
      "comment": {
        "body": "Ce problème a été résolu. Le correctif est maintenant en ligne.",
        "public": true
      }
    }
  }'

Implémentation Python

En utilisant la bibliothèque Requests, la même opération ressemble à ceci :

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "status": "solved",
        "priority": "normal",
        "assignee_id": 987654321,
        "comment": {
            "body": "Ce problème a été résolu. Le correctif est maintenant en ligne.",
            "public": True
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("Ticket mis à jour avec succès")
    updated_ticket = response.json()['ticket']
    print(f"Nouveau statut : {updated_ticket['status']}")
else:
    print(f"Erreur : {response.status_code}")
    print(response.text)

Champs courants que vous pouvez mettre à jour

Lors de la mise à jour du champ comment, le fait de définir "public": true en fait une réponse publique visible pour le demandeur. L'omission de ceci ou le fait de le définir sur false crée une note interne.

Travailler avec des champs personnalisés

Les champs personnalisés sont courants dans les configurations Zendesk pour le suivi de données spécifiques comme les catégories de produits, les niveaux de clients ou les types de problèmes. Leur mise à jour via l'API nécessite de connaître l'ID du champ.

Trouver les ID des champs personnalisés

Vous pouvez trouver les ID des champs personnalisés de deux manières :

1. Centre d'administration : Allez dans Objets et règles > Tickets > Champs personnalisés. L'ID apparaît dans l'URL lorsque vous modifiez un champ.
2. API : Listez tous les champs personnalisés avec GET /api/v2/ticket_fields.json

Mise à jour des champs personnalisés

Les champs personnalisés utilisent un format spécifique dans l'API. Vous fournissez un tableau d'objets avec les propriétés id et value :

{
  "ticket": {
    "custom_fields": [
      {"id": 25356371, "value": "enterprise"},
      {"id": 25356372, "value": 42},
      {"id": 25356373, "value": "billing_issue"}
    ]
  }
}

Voici un exemple Python complet :

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "custom_fields": [
            {"id": 360012345678, "value": "premium"},      # Dropdown
            {"id": 360012345679, "value": "2026-03-15"},  # Date
            {"id": 360012345680, "value": 1500.00},        # Decimal
            {"id": 360012345681, "value": True}            # Checkbox
        ],
        "comment": {
            "body": "Niveau client et date de renouvellement mis à jour.",
            "public": False
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("Champs personnalisés mis à jour avec succès")
else:
    print(f"Erreur {response.status_code} : {response.text}")

Pièges courants avec les champs personnalisés

• Mauvais type de données : L'envoi d'une chaîne lorsque le champ attend un nombre renverra une erreur 422
• Valeurs d'option non valides : Les champs de liste déroulante n'acceptent que des valeurs prédéfinies. Vérifiez la configuration du champ si les mises à jour échouent.
• Autorisations de champ : Certains champs personnalisés sont en lecture seule ou ne peuvent être modifiés que par certains rôles

Mise à jour en masse de plusieurs tickets

Lorsque vous devez mettre à jour des dizaines ou des centaines de tickets, les appels API individuels sont inefficaces. Zendesk fournit des endpoints de mise à jour en masse pour ce scénario.

L'endpoint de mise à jour en masse

PUT /api/v2/tickets/update_many.json?ids=1,2,3,4,5

Vous pouvez spécifier les tickets par ID ou utiliser une requête de recherche :

PUT /api/v2/tickets/update_many.json?query=status:open+priority:high

Quand utiliser les mises à jour en masse

Les mises à jour en masse sont utiles lorsque vous devez :

• Réaffecter tous les tickets d'un agent partant
• Fermer les tickets résolus datant de plus de 30 jours
• Mettre à jour une valeur de champ personnalisé dans une catégorie de tickets
• Ajouter des balises aux tickets correspondant à des critères spécifiques

Considérations sur la limitation du débit

Zendesk applique des limites de débit qui varient selon le plan : les plans Team ont 200 requêtes par minute, les plans Growth et Professional en ont 400 et les plans Enterprise en ont 700. Les mises à jour en masse comptent comme une seule requête, quel que soit le nombre de tickets concernés, ce qui les rend beaucoup plus efficaces que les appels individuels.

Meilleures pratiques pour les mises à jour à grande échelle

1. Testez d'abord sur un petit lot. Exécutez votre mise à jour sur 5 à 10 tickets pour vérifier la logique avant de traiter des centaines de tickets.
2. Utilisez les requêtes de recherche avec précaution. Une requête mal construite pourrait correspondre à des milliers de tickets involontairement.
3. Gérez la pagination. Si votre recherche renvoie de nombreux résultats, traitez-les par lots.
4. Enregistrez vos modifications. Conservez un enregistrement des tickets qui ont été mis à jour et de la date de mise à jour.

Voici un exemple qui met à jour tous les tickets ouverts affectés à un agent spécifique :

import requests
import os
import time

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)
base_url = f"https://{subdomain}.zendesk.com/api/v2"

search_url = f"{base_url}/search.json?query=assignee:987654321+status:open"
response = requests.get(search_url, auth=auth)
results = response.json()

ticket_ids = [str(ticket['id']) for ticket in results['results']]

for i in range(0, len(ticket_ids), 100):
    batch = ticket_ids[i:i+100]
    ids_param = ','.join(batch)

    update_url = f"{base_url}/tickets/update_many.json?ids={ids_param}"
    data = {
        "ticket": {
            "assignee_id": 123456789,  # Nouvel assigné
            "comment": {
                "body": "Réaffecté à un nouveau membre de l'équipe.",
                "public": False
            }
        }
    }

    response = requests.put(update_url, json=data, auth=auth)

    if response.status_code == 200:
        print(f"Lot mis à jour {i//100 + 1} : {len(batch)} tickets")
    else:
        print(f"Erreur dans le lot {i//100 + 1} : {response.text}")

    # Soyez gentil avec l'API
    time.sleep(1)

Gestion des erreurs et dépannage

Même avec une planification minutieuse, les appels API échouent parfois. Savoir comment interpréter les réponses d'erreur vous fera gagner du temps de débogage.

Codes d'erreur HTTP courants

Gestion des erreurs de validation

Une erreur 422 signifie généralement que vos données ne correspondent pas à ce que Zendesk attend. Le corps de la réponse contient des détails :

{
  "error": "RecordInvalid",
  "description": "Erreurs de validation d'enregistrement",
  "details": {
    "custom_fields": [
      {
        "description": "La valeur du champ ne peut pas être vide",
        "error": "BlankValue"
      }
    ]
  }
}

Conseils de débogage

1. Activez la journalisation détaillée dans votre client HTTP pour voir les détails complets de la requête et de la réponse
2. Vérifiez les journaux de l'API Zendesk dans le Centre d'administration pour les requêtes ayant échoué
3. Validez votre JSON avant de l'envoyer. Une virgule de fin ou une guillemet manquante provoquera des erreurs.
4. Testez dans Postman ou avec cURL avant d'écrire du code pour isoler les problèmes de syntaxe

Quand contacter le support Zendesk

La plupart des problèmes d'API peuvent être résolus en vérifiant la documentation et en vérifiant le format de votre requête. Contactez le support Zendesk si vous rencontrez :

• Des erreurs 500 cohérentes (problèmes côté serveur)
• Une limitation de débit inattendue malgré le fait d'être en dessous des limites documentées
• Un comportement qui contredit la documentation officielle de l'API

Rationalisation des mises à jour de tickets avec eesel AI

La création et la maintenance d'intégrations API prennent du temps et des ressources d'ingénierie. Pour les équipes qui ont besoin d'une gestion automatisée des tickets sans écrire de code, eesel AI offre une approche différente.

Pourquoi les équipes choisissent l'automatisation plutôt que le script manuel

Les scripts API personnalisés fonctionnent bien pour des tâches spécifiques et ponctuelles. Mais ils deviennent un fardeau lorsque vous devez :

• Mettre à jour continuellement les tickets en fonction des conditions changeantes
• Maintenir les intégrations à mesure que votre flux de travail évolue
• Former les membres de l'équipe à utiliser et à modifier le code
• Mettre à l'échelle l'automatisation sur plusieurs types de tickets et canaux

Comment eesel AI se connecte à Zendesk

Au lieu d'écrire des appels API, vous invitez eesel AI dans votre équipe en tant qu'agent AI. Il apprend de vos tickets passés, des articles du centre d'aide et des macros, puis gère automatiquement les mises à jour de routine.

Voici à quoi cela ressemble en pratique :

• Auto-balisage : eesel lit les tickets entrants et applique les balises pertinentes en fonction du contenu
• Routage intelligent : Les tickets sont affectés à la bonne équipe ou au bon agent sans triage manuel
• Mises à jour de statut : eesel peut modifier le statut du ticket lorsque des conditions spécifiques sont remplies
• Gestion de l'escalade : Les problèmes complexes sont automatiquement transmis aux agents humains avec le contexte

Cas d'utilisation pour la gestion automatisée des tickets

Les équipes utilisent l'intégration Zendesk d'eesel AI pour des scénarios qui nécessiteraient autrement un script API complexe :

• Router immédiatement les tickets des clients VIP vers les agents seniors
• Fermer automatiquement les spams ou les messages de « remerciement »
• Mettre à jour les champs personnalisés en fonction de l'analyse du contenu du ticket
• Fusionner les tickets en double du même client

Démarrer avec eesel AI

Si votre équipe passe plus de temps à maintenir les scripts API qu'à bénéficier de l'automatisation, la tarification d'eesel AI offre une alternative sans code. Les plans commencent à 239 $ par mois en cas de facturation annuelle, avec un essai gratuit de 7 jours pour tester son adéquation à votre flux de travail.

La différence réside dans l'approche. Plutôt que d'écrire du code pour mettre à jour les tickets, vous décrivez ce que vous voulez en anglais simple. eesel apprend votre entreprise, commence par des conseils et passe à un niveau supérieur pour travailler de manière autonome à mesure qu'il fait ses preuves.