Comment créer des tickets Zendesk en utilisant l'API : Un guide JSON complet

Si vous créez des intégrations avec Zendesk, il est probable que vous ayez besoin de créer des tickets par programme. Que vous connectiez un formulaire web personnalisé, que vous synchronisiez des données à partir d'un autre système ou que vous automatisiez les flux de travail de support, l'API Zendesk Tickets est la méthode standard pour intégrer des données dans Zendesk.

Ce guide vous explique tout ce que vous devez savoir sur la création de tickets via l'API, de l'authentification aux payloads JSON avancés.

Ce dont vous aurez besoin pour commencer

Avant de commencer à effectuer des appels API, assurez-vous d'avoir couvert ces bases :

• Un compte Zendesk Support avec un accès administrateur ou agent. Si vous n'en avez pas, vous pouvez obtenir un compte d'essai gratuit pour le développement
• L'accès au jeton API activé dans votre Centre d'administration sous Applications et intégrations > API > Jetons API
• Une connaissance de base des requêtes HTTP et des structures de données JSON
• Un outil pour effectuer des appels API : cURL, Python avec la bibliothèque requests ou un environnement JavaScript

Si vous débutez avec les API REST, la documentation Zendesk propose un guide de démarrage rapide utile qui utilise la console JavaScript de votre navigateur pour tester les requêtes sans aucune configuration.

Comprendre l'endpoint de l'API Zendesk Tickets

L'endpoint JSON de création de ticket de l'API Zendesk suit un modèle cohérent sur toutes les instances Zendesk :

POST https://{subdomain}.zendesk.com/api/v2/tickets.json

Voici ce que vous devez savoir sur l'endpoint :

• Méthode HTTP : POST pour créer de nouveaux tickets
• En-tête Content-Type : Doit être défini sur application/json
• Authentification : Authentification de base utilisant votre e-mail et votre jeton API
• Limites de débit : 700 requêtes par minute pour la plupart des endpoints

L'API renvoie un statut 201 Created en cas de succès, ainsi que l'objet ticket complet, y compris l'ID de ticket nouvellement attribué. Si quelque chose ne va pas, vous obtiendrez un statut 4xx ou 5xx avec un message d'erreur expliquant le problème.

Configuration de l'authentification API

L'authentification est l'endroit où la plupart des développeurs rencontrent leur premier problème. Zendesk utilise l'authentification de base avec une particularité : au lieu de votre mot de passe, vous utilisez un jeton API.

Génération d'un jeton API

1. Connectez-vous à Zendesk en tant qu'administrateur
2. Accédez à Centre d'administration > Applications et intégrations > API > Jetons API
3. Cliquez sur l'icône plus pour ajouter un jeton
4. Donnez-lui un nom descriptif (comme « Script de création de ticket »)
5. Copiez immédiatement le jeton (vous ne le reverrez plus)

Format d'authentification

Les informations d'identification suivent ce format :

Nom d'utilisateur : {your_email}/token
Mot de passe : {your_api_token}

Par exemple, si votre e-mail est admin@company.com et votre jeton est abc123xyz, vous utiliserez :

Nom d'utilisateur : admin@company.com/token
Mot de passe : abc123xyz

Meilleures pratiques de sécurité

Ne codez jamais en dur vos informations d'identification API dans vos scripts. Utilisez plutôt des variables d'environnement :

import os

ZENDESK_SUBDOMAIN = os.getenv('ZENDESK_SUBDOMAIN')
ZENDESK_API_TOKEN = os.getenv('ZENDESK_API_TOKEN')
ZENDESK_USER_EMAIL = os.getenv('ZENDESK_USER_EMAIL')

Cela maintient vos informations d'identification hors du contrôle de version et rend votre code plus portable entre les environnements.

Structure JSON de création de ticket de base

Au minimum, un ticket Zendesk a besoin de deux choses : un sujet et un commentaire. Voici le payload JSON valide le plus simple :

{
  "ticket": {
    "subject": "Mon imprimante est en feu !",
    "comment": {
      "body": "La fumée est très colorée."
    }
  }
}

L'objet ticket enveloppe tout. À l'intérieur, vous définissez :

• subject : Le titre du ticket (obligatoire)
• comment : Un objet contenant au moins un body (obligatoire)

Par défaut, les commentaires sont publics. Si vous souhaitez créer une note interne à la place, ajoutez "public": false à l'objet de commentaire.

Format de réponse

Lorsque votre requête réussit, l'API renvoie le ticket créé :

{
  "ticket": {
    "id": 35436,
    "url": "https://company.zendesk.com/api/v2/tickets/35436.json",
    "subject": "Mon imprimante est en feu !",
    "status": "open",
    "created_at": "2026-03-01T22:55:29Z",
    ...
  }
}

Le champ id est ce que vous utiliserez pour référencer ce ticket dans les futurs appels API.

Exemples de code pour la création de tickets

Examinons des exemples de travail dans trois langages courants.

Exemple cURL

curl https://yourcompany.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "Ticket de test", "comment": {"body": "Ceci est un test"}}}' \
  -H "Content-Type: application/json" \
  -v -u your@email.com/token:your_api_token \
  -X POST

L'indicateur -v affiche une sortie détaillée, ce qui facilite le débogage. Supprimez-le en production.

Exemple Python

import requests
import os
import json

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_USER_EMAIL')
token = os.getenv('ZENDESK_API_TOKEN')

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
auth = (f'{email}/token', token)
headers = {'Content-Type': 'application/json'}

data = {
    'ticket': {
        'subject': 'Problème d\'imprimante',
        'comment': {
            'body': 'L\'imprimante ne répond pas.',
            'public': True
        }
    }
}

response = requests.post(url, json=data, auth=auth, headers=headers)

if response.status_code == 201:
    ticket = response.json()['ticket']
    print(f"Ticket créé # {ticket['id']}")
else:
    print(f"Erreur : {response.status_code}")
    print(response.text)

Notez que requests.post() avec le paramètre json= sérialise automatiquement le dictionnaire en JSON et définit l'en-tête Content-Type.

Exemple JavaScript

Si vous travaillez dans un navigateur avec Zendesk déjà chargé, vous pouvez utiliser jQuery :

const ticket = {
  ticket: {
    subject: 'Aide à la connexion',
    comment: {
      body: 'Je ne peux pas accéder à mon compte.'
    }
  }
};

$.ajax({
  url: '/api/v2/tickets.json',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify(ticket)
}).done(data => {
  console.log('Ticket créé :', data.ticket.id);
}).fail(err => {
  console.error('Erreur :', err);
});

Pour Node.js, utilisez l'API fetch native ou une bibliothèque comme axios :

const response = await fetch('https://company.zendesk.com/api/v2/tickets.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${email}/token:${token}`).toString('base64')
  },
  body: JSON.stringify(ticket)
});

const data = await response.json();

Propriétés de ticket avancées

Une fois que vous avez maîtrisé les bases, vous pouvez définir des propriétés supplémentaires pour créer des tickets plus complets.

Champs personnalisés

Si votre instance Zendesk possède des champs de ticket personnalisés, définissez-les à l'aide de leurs ID de champ :

{
  "ticket": {
    "subject": "Demande de commande",
    "comment": {"body": "Question sur une commande récente"},
    "custom_fields": [
      {"id": 25356371, "value": "ORD-12345"},
      {"id": 25356634, "value": "2026-03-01"}
    ]
  }
}

Pour les champs de liste déroulante, utilisez la valeur de la balise (pas le texte affiché). Pour les champs à sélection multiple, transmettez un tableau de valeurs de balise.

Définition du demandeur

Vous pouvez créer un ticket au nom de quelqu'un d'autre :

{
  "ticket": {
    "subject": "Demande de support",
    "comment": {"body": "Besoin d'aide pour la facturation"},
    "requester": {
      "name": "John Smith",
      "email": "john@example.com",
      "locale_id": 8
    }
  }
}

Si l'e-mail n'existe pas dans Zendesk, un nouveau profil utilisateur est créé automatiquement.

Collaborateurs et abonnés

Ajoutez des collaborateurs (utilisateurs qui reçoivent des mises à jour) ou des abonnés (agents qui suivent le ticket) :

{
  "ticket": {
    "subject": "Problème d'équipe",
    "comment": {"body": "Cela affecte plusieurs services"},
    "collaborators": ["user1@example.com", "user2@example.com"],
    "followers": [
      {"user_email": "agent@company.com", "action": "put"}
    ]
  }
}

Pièces jointes

Pour joindre des fichiers, vous devez d'abord les télécharger séparément pour obtenir un jeton de téléchargement, puis inclure ce jeton dans votre création de ticket :

{
  "ticket": {
    "subject": "Capture d'écran jointe",
    "comment": {
      "body": "Voir le message d'erreur ci-joint",
      "uploads": ["vz7ll9ud8oofowy"]
    }
  }
}

Création asynchrone

Pour les tickets avec des règles métier complexes qui peuvent prendre du temps à traiter, utilisez la création asynchrone :

POST /api/v2/tickets.json?async=true

Cela renvoie immédiatement un 202 Accepted avec un statut de tâche que vous pouvez interroger pour vérifier l'achèvement.

Clés d'idempotence

Pour éviter les tickets en double lors de la nouvelle tentative de requêtes ayant échoué, incluez une clé d'idempotence :

curl ... -H "Idempotency-Key: unique-request-id-123"

Les clés expirent après 2 heures. La réutilisation de la même clé avec des paramètres différents renvoie une erreur.

Erreurs courantes et dépannage

Voici les erreurs les plus susceptibles de se produire et comment les corriger.

422 Entité non traitable

Cela signifie généralement que votre JSON est mal formé. Causes courantes :

• Guillemets manquants autour des noms de propriété ou des valeurs de chaîne
• Virgules de fin dans les objets JSON
• Utilisation de guillemets simples au lieu de guillemets doubles
• Séquences d'échappement non valides dans les chaînes

Si vous créez des chaînes JSON manuellement (en particulier dans VBA ou des langages plus anciens), faites attention aux caractères de guillemet supplémentaires. Le JSON doit ressembler à ceci :

{"ticket": {"subject": "Test", "comment": {"body": "Bonjour"}}}

Pas comme ceci :

"{"ticket": {"subject": "Test"}}"

401 Non autorisé

Vos informations d'identification d'authentification sont incorrectes. Vérifiez :

• L'adresse e-mail est-elle correcte ?
• Avez-vous inclus /token après l'e-mail ?
• Le jeton API est-il valide et n'a-t-il pas expiré ?
• L'utilisateur a-t-il l'autorisation de créer des tickets ?

429 Limite de débit dépassée

Vous avez atteint la limite de débit de l'API. Zendesk autorise 700 requêtes par minute pour la plupart des endpoints. Si vous devez créer de nombreux tickets, ajoutez des délais entre les requêtes ou utilisez l'endpoint de création de ticket en bloc.

400 Mauvaise requête avec erreurs de champ

Cela se produit lorsque les valeurs des champs de ticket ne sont pas valides :

• Les ID de champ personnalisés n'existent pas
• Les valeurs de liste déroulante ne correspondent pas aux options disponibles
• Les champs obligatoires sont manquants
• Les formats de date sont incorrects (utilisez ISO 8601 : 2026-03-01)

Automatisation de la création de tickets sans code

La création et la maintenance des intégrations API prennent du temps. 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 la création de tickets plutôt que de créer une intégration personnalisée, déterminez si vous avez réellement besoin d'écrire du code. Des outils comme eesel AI peuvent gérer la création et les réponses aux tickets sans aucun travail de développement.

Voici la différence : avec l'approche API, vous écrivez des scripts pour créer des tickets auxquels les humains répondront. 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, de la création à la résolution. Vous le connectez à votre compte Zendesk, et il apprend de vos tickets passés, des articles du centre d'aide et des 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 que de simplement automatiser la création, cela donne souvent des résultats plus rapides que le développement d'API personnalisées.