Comment créer des utilisateurs avec l'API Zendesk : Un guide complet

La gestion des comptes utilisateurs à grande échelle est l'une de ces tâches qui commence simplement et se complique rapidement. Que vous intégriez des clients à partir d'une nouvelle acquisition, que vous synchronisiez des utilisateurs à partir de votre base de données interne ou que vous construisiez un flux d'inscription en libre-service, vous devrez éventuellement créer des utilisateurs Zendesk par programmation.

L'API Users de Zendesk vous donne les outils pour ce faire. Il s'agit d'une API RESTful qui gère tout, de la création d'utilisateurs individuels à l'importation en masse de milliers à la fois. Ce guide vous explique les étapes pratiques pour la faire fonctionner, avec des exemples de code fonctionnels que vous pouvez adapter à votre pile (stack).

Si vous cherchez à automatiser plus que la simple création d'utilisateurs, des outils comme eesel AI peuvent gérer l'ensemble du spectre de l'automatisation du support, du routage des tickets aux réponses alimentées par l'IA.

Ce dont vous aurez besoin

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

• Un compte Zendesk avec un accès administrateur : seuls les administrateurs peuvent créer des jetons d'API et gérer les utilisateurs via l'API
• Un jeton d'API ou des identifiants OAuth : nous verrons comment les générer ci-dessous
• Une connaissance de base des API REST : vous devez savoir ce qu'est une requête POST
• Un environnement de développement : cURL, Python ou Node.js feront l'affaire

Étape 1 : configurer l'authentification de l'API

Zendesk prend en charge deux méthodes d'authentification principales pour l'accès à l'API : les jetons d'API et OAuth. Pour la plupart des intégrations serveur à serveur, les jetons d'API sont plus simples à implémenter.

Générer un jeton d'API

1. Connectez-vous à votre compte Zendesk en tant qu'administrateur
2. Accédez au Centre d'administration (cliquez sur l'icône d'engrenage, puis sur « Aller au Centre d'administration »)
3. Allez dans Applications et intégrations → API → API Zendesk
4. Cliquez sur l'onglet Paramètres et assurez-vous que Accès par jeton est activé
5. Passez à l'onglet Jetons d'API et cliquez sur Ajouter un jeton d'API
6. Entrez un nom descriptif comme « Intégration de synchronisation des utilisateurs »
7. Copiez le jeton immédiatement : Zendesk ne l'affiche qu'une seule fois

Formater votre en-tête d'authentification

Zendesk utilise l'authentification de base avec votre jeton d'API. Le format est le suivant :

• Nom d'utilisateur : votre adresse e-mail Zendesk avec /token ajouté (par exemple, vous@entreprise.com/token)
• Mot de passe : le jeton d'API lui-même

Encodez ces identifiants en Base64 et incluez-les dans l'en-tête Authorization :

curl https://your-subdomain.zendesk.com/api/v2/users.json \
  -u vous@entreprise.com/token:votre_jeton_api_ici

Ou en Python :

import requests
from requests.auth import HTTPBasicAuth

subdomain = "your-subdomain"
email = "vous@entreprise.com"
token = "votre_jeton_api_ici"

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

url = f"https://{subdomain}.zendesk.com/api/v2/users.json"
response = requests.get(url, auth=auth, headers=headers)
print(response.json())

Meilleures pratiques de sécurité

• Stockez les jetons d'API dans des variables d'environnement, jamais dans votre code
• Faites pivoter les jetons périodiquement : supprimez les anciens et générez-en de nouveaux
• Utilisez des noms de jetons descriptifs pour savoir à quoi sert chacun d'eux
• Supprimez les jetons lorsque les intégrations sont mises hors service
• Envisagez de créer un utilisateur de service dédié avec des autorisations limitées plutôt que d'utiliser le jeton d'un administrateur

Étape 2 : créer un seul utilisateur

La façon la plus simple de créer un utilisateur est via le point de terminaison POST /api/v2/users. Au minimum, vous devez fournir un nom.

Paramètres obligatoires et facultatifs

Comprendre les rôles d'utilisateur

Zendesk a trois rôles intégrés :

• end-user (utilisateur final) : clients qui soumettent des tickets (par défaut si aucun rôle n'est spécifié)
• agent : personnel de support qui traite les tickets
• admin : accès administratif complet

Pour les plans Enterprise, vous pouvez également attribuer des rôles d'agent personnalisés à l'aide du paramètre custom_role_id. Notez que les rôles personnalisés doivent d'abord être créés dans le Centre d'administration : vous ne pouvez pas les créer via l'API.

Exemples de code

cURL :

curl https://your-subdomain.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Jane Smith", "email": "jane@example.com", "role": "end-user"}}' \
  -H "Content-Type: application/json" \
  -X POST \
  -u vous@entreprise.com/token:votre_jeton_api

Python :

import requests
import json
from requests.auth import HTTPBasicAuth

subdomain = "your-subdomain"
auth = HTTPBasicAuth("vous@entreprise.com/token", "votre_jeton_api")
headers = {"Content-Type": "application/json"}

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "role": "end-user",
        "external_id": "user_12345"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/users.json",
    auth=auth,
    headers=headers,
    json=user_data
)

if response.status_code == 201:
    user = response.json()["user"]
    print(f"Utilisateur créé {user['id']} : {user['name']}")
else:
    print(f"Erreur : {response.status_code} - {response.text}")

JavaScript (Node.js avec axios) :

const axios = require('axios');

const subdomain = 'your-subdomain';
const email = 'vous@entreprise.com';
const token = 'votre_jeton_api';

const userData = {
  user: {
    name: 'Jane Smith',
    email: 'jane@example.com',
    role: 'end-user',
    external_id: 'user_12345'
  }
};

axios.post(
  `https://${subdomain}.zendesk.com/api/v2/users.json`,
  userData,
  {
    auth: {
      username: `${email}/token`,
      password: token
    },
    headers: {
      'Content-Type': 'application/json'
    }
  }
)
.then(response => {
  const user = response.data.user;
  console.log(`Utilisateur créé ${user.id} : ${user.name}`);
})
.catch(error => {
  console.error('Erreur :', error.response?.data || error.message);
});

Interpréter la réponse

Une création réussie renvoie HTTP 201 Created avec l'objet utilisateur :

{
  "user": {
    "id": 9873843,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "end-user",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "active": true,
    "verified": false
  }
}

Étape 3 : créer ou mettre à jour des utilisateurs (upsert)

Que se passe-t-il si vous essayez de créer un utilisateur qui existe déjà ? Le point de terminaison de création standard renvoie une erreur 422. Pour les scénarios de synchronisation où vous importez régulièrement des utilisateurs à partir d'un système externe, utilisez plutôt le point de terminaison create_or_update.

Quand utiliser create_or_update

Utilisez POST /api/v2/users/create_or_update lorsque :

• Vous synchronisez des utilisateurs à partir d'une base de données externe
• Vous voulez des opérations idempotentes (la même requête produit le même résultat)
• Vous ne voulez pas vérifier si un utilisateur existe avant de le créer

Comment fonctionne la correspondance

Zendesk fait correspondre les utilisateurs par :

1. ID externe : si fourni, il est prioritaire
2. Adresse e-mail : si aucune correspondance d'ID externe n'est trouvée

Codes de réponse

Exemple pratique : synchronisation à partir d'un système externe

import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth("vous@entreprise.com/token", "votre_jeton_api")
headers = {"Content-Type": "application/json"}

external_users = [
    {"name": "Jane Smith", "email": "jane@example.com", "external_id": "usr_001"},
    {"name": "John Doe", "email": "john@example.com", "external_id": "usr_002"}
]

for external_user in external_users:
    user_data = {"user": external_user}

    response = requests.post(
        "https://your-subdomain.zendesk.com/api/v2/users/create_or_update.json",
        auth=auth,
        headers=headers,
        json=user_data
    )

    if response.status_code == 201:
        print(f"Créé : {external_user['email']}")
    elif response.status_code == 200:
        print(f"Mis à jour : {external_user['email']}")
    else:
        print(f"Échec : {external_user['email']} - {response.text}")

Étape 4 : créer plusieurs utilisateurs en masse

Si vous devez créer des centaines ou des milliers d'utilisateurs, les appels d'API individuels sont inefficaces. Zendesk fournit un point de terminaison en masse qui accepte jusqu'à 100 utilisateurs par requête.

Point de terminaison et limitations

• Point de terminaison : POST /api/v2/users/create_many
• Limite : 100 utilisateurs par requête
• Activation : les importations en masse doivent être activées par le support Zendesk (contactez-les si vous obtenez des erreurs 403)

Comprendre les réponses job_status

Contrairement à la création d'un seul utilisateur, les opérations en masse sont asynchrones. L'API renvoie immédiatement un objet job_status, et la création proprement dite se fait en arrière-plan :

{
  "job_status": {
    "id": "82de0b044094f0c67893ac9fe64f1a99",
    "status": "queued",
    "total": 50,
    "progress": 0,
    "url": "https://your-subdomain.zendesk.com/api/v2/job_statuses/82de0b044094f0c67893ac9fe64f1a99"
  }
}

Interrogez l'URL de l'état du travail pour suivre la progression :

def check_job_status(job_url):
    response = requests.get(job_url, auth=auth)
    job = response.json()["job_status"]

    print(f"Statut : {job['status']}, Progression : {job['progress']}/{job['total']}")

    if job["status"] == "completed":
        for result in job.get("results", []):
            print(f"  {result['action']} : Utilisateur {result['id']} - {result['status']}")

    return job["status"]

import time
while check_job_status(job_url) != "completed":
    time.sleep(5)

Quand la masse est logique

Exemple de création en masse

users_to_create = [
    {"name": "User One", "email": "user1@example.com", "role": "end-user"},
    {"name": "User Two", "email": "user2@example.com", "role": "end-user"},
    # ... jusqu'à 100 utilisateurs
]

response = requests.post(
    "https://your-subdomain.zendesk.com/api/v2/users/create_many.json",
    auth=auth,
    headers=headers,
    json={"users": users_to_create}
)

if response.status_code == 200:
    job = response.json()["job_status"]
    print(f"Travail mis en file d'attente : {job['id']}")
else:
    print(f"Erreur : {response.status_code} - {response.text}")

Erreurs courantes et dépannage

Même avec le bon code, les choses peuvent mal tourner. Voici comment gérer les problèmes les plus courants :

401 Non autorisé

Vos identifiants d'authentification ne sont pas valides. Vérifiez :

• L'adresse e-mail est-elle correcte ?
• Avez-vous ajouté /token au nom d'utilisateur ?
• Le jeton d'API est-il toujours actif (non supprimé) ?
• Utilisez-vous le bon sous-domaine ?

403 Interdit

Vous n'avez pas l'autorisation d'effectuer cette action. Causes courantes :

• Le jeton d'API appartient à un agent, pas à un administrateur
• Les importations en masse ne sont pas activées sur votre compte (contactez le support Zendesk)
• Vous essayez de créer un utilisateur administrateur sans les autorisations suffisantes

422 Entité non traitable

Les données de la requête ne sont pas valides. Vérifiez :

• Le champ name est-il présent ? (il est obligatoire)
• Le format de l'e-mail est-il valide ?
• Le rôle est-il l'un des suivants : end-user, agent, admin ?
• L'organization_id existe-t-il ?

429 Trop de requêtes

Vous avez atteint la limite de débit de Zendesk. L'API renvoie un en-tête Retry-After indiquant le nombre de secondes à attendre. Implémentez une interruption exponentielle dans votre code :

import time

def api_call_with_retry(url, auth, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, auth=auth, headers=headers, json=json_data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Débit limité. Attente de {retry_after} secondes...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Nombre maximal de tentatives dépassé")

Erreurs d'e-mail en double

Si vous obtenez une erreur 422 mentionnant « L'e-mail a déjà été pris », soit :

• Utilisez plutôt le point de terminaison create_or_update
• Vérifiez d'abord si l'utilisateur existe avec GET /api/v2/users/search?query=email@example.com

Meilleures pratiques pour l'automatisation de la gestion des utilisateurs

Après avoir travaillé avec l'API Users de Zendesk, voici des modèles qui fonctionnent toujours bien :

Utilisez external_id pour l'idempotence

Incluez toujours un external_id qui correspond à votre ID d'utilisateur interne. Cela rend les opérations idempotentes et simplifie la synchronisation :

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "external_id": f"internal_db_{internal_user_id}"
    }
}

Définissez l'état vérifié pour ignorer la vérification par e-mail

Si vous créez des utilisateurs à partir d'une source fiable (comme votre propre base de données), définissez verified: true pour empêcher Zendesk d'envoyer des e-mails de vérification :

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "verified": True  # Ignorer l'e-mail de vérification
    }
}

Gérez correctement les rôles personnalisés

Les rôles personnalisés sont une fonctionnalité Enterprise. Pour les attribuer :

1. Créez d'abord le rôle personnalisé dans le Centre d'administration
2. Obtenez le custom_role_id à partir de l'URL ou de l'API du rôle
3. Définissez à la fois role: "agent" et custom_role_id: 12345

Implémentez une gestion des erreurs appropriée

Ne supposez pas que les appels d'API réussissent. Encapsulez les appels dans des blocs try/except et gérez les cas d'erreur spécifiques :

try:
    response = requests.post(url, auth=auth, headers=headers, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    if response.status_code == 422:
        errors = response.json().get("details", {})
        print(f"Erreur de validation : {errors}")
    else:
        raise

Stockez les identifiants en toute sécurité

Ne codez jamais en dur les jetons d'API. Utilisez des variables d'environnement :

import os

ZENDESK_SUBDOMAIN = os.environ.get("ZENDESK_SUBDOMAIN")
ZENDESK_EMAIL = os.environ.get("ZENDESK_EMAIL")
ZENDESK_TOKEN = os.environ.get("ZENDESK_TOKEN")

Tenez compte des besoins d'automatisation plus larges

Si vous automatisez la création d'utilisateurs, vous gérez probablement une opération de support croissante. Bien que l'API Zendesk gère la gestion des utilisateurs, vous devrez peut-être également automatiser la gestion, le routage et les réponses des tickets. eesel AI s'intègre à Zendesk pour gérer automatiquement ces flux de travail, de la classification et du marquage des tickets à la rédaction de réponses alimentées par l'IA.

Commencez à automatiser vos flux de travail Zendesk

Vous avez maintenant les bases pour créer des utilisateurs Zendesk par programmation. Que vous construisiez une intégration de synchronisation des utilisateurs, que vous automatisiez l'intégration ou que vous gériez une large base de clients, l'API Users vous donne le contrôle dont vous avez besoin.

Les modèles de ce guide : authentification, création unique, upserts et opérations en masse : couvrent la plupart des scénarios du monde réel. Commencez par le point de terminaison utilisateur unique pour valider votre configuration, puis passez aux opérations en masse à mesure que votre échelle augmente.

Si vous cherchez à automatiser au-delà de la création d'utilisateurs, réfléchissez à la façon dont l'IA peut rationaliser l'ensemble de votre flux de travail de support. eesel AI s'intègre à Zendesk pour gérer le triage des tickets, la rédaction des réponses et le routage intelligent, réduisant ainsi le travail manuel tout en améliorant les temps de réponse. Vous pouvez explorer notre agent d'IA pour le service client pour voir comment l'automatisation peut s'étendre à l'ensemble de votre pile de support.