Comment importer des tickets en masse en utilisant l'API Zendesk

La migration des données de tickets vers Zendesk est un défi courant pour les équipes qui changent de plateforme, consolident des instances ou importent des enregistrements historiques. Bien que Zendesk propose plusieurs méthodes d'importation, l'API d'importation de tickets est la seule option qui préserve les horodatages historiques et gère correctement les grands ensembles de données.

Ce guide vous explique le processus complet d'importation en masse de tickets à l'aide de l'API Zendesk. Vous apprendrez à structurer vos données, à gérer les cas limites et à éviter les pièges qui peuvent transformer un projet de week-end en un casse-tête de plusieurs semaines.

Ce dont vous aurez besoin

Avant de commencer, assurez-vous que vous avez les éléments suivants en place :

• Accès administrateur Zendesk : seuls les administrateurs peuvent utiliser l'API d'importation
• Jeton API : l'authentification par mot de passe seule ne fonctionnera pas ; vous avez besoin d'un jeton API approprié à partir de vos paramètres d'administrateur Zendesk
• Utilisateurs existants : les demandeurs doivent déjà exister dans Zendesk avant que vous n'importiez leurs tickets
• Connaissance de JSON : vous travaillerez avec des requêtes API REST et des charges utiles JSON
• Environnement de script : Python ou Node.js facilitera grandement le traitement par lots

Si vous recherchez un moyen plus simple de gérer les flux de travail d'assistance sans migrations complexes, les solutions d'IA modernes comme eesel AI peuvent s'intégrer directement à votre configuration existante.

Comprendre le point de terminaison d'importation en masse de tickets de l'API Zendesk

L'API d'importation de tickets diffère de l'API Tickets standard de plusieurs manières importantes. Voici ce que vous devez savoir.

Principales différences entre les points de terminaison

Le point de terminaison d'importation est POST /api/v2/imports/tickets (ou /api/v2/imports/tickets/create_many pour les lots allant jusqu'à 100 tickets). Contrairement à l'API de création de tickets standard, le point de terminaison d'importation :

• Préserve les horodatages historiques, notamment created_at, updated_at et solved_at
• Prend en charge le paramètre archive_immediately pour les tickets fermés
• Ne déclenche pas les règles de gestion ni les automatisations lors de l'importation
• N'envoie aucune notification aux utilisateurs en copie
• Vous permet de définir des horodatages de commentaires personnalisés

Source : Documentation de l'API d'importation de tickets Zendesk

Limites de débit et tailles de lots

Zendesk autorise jusqu'à 100 tickets par requête d'importation en masse. Pour les ensembles de données plus volumineux, vous devrez implémenter une logique de traitement par lots dans votre script. Les limites de débit de l'API standard s'appliquent (700 requêtes par minute pour la plupart des plans), alors planifiez votre migration en conséquence.

Exigences d'authentification

Toutes les requêtes d'importation nécessitent une authentification de base à l'aide de votre adresse e-mail combinée à un jeton API (pas votre mot de passe). Le format est {email_address}/token:{api_token} encodé en Base64.

Étape 1 : Préparer vos données

La préparation des données est l'étape où la plupart des migrations réussissent ou échouent. Prenez le temps de bien faire les choses.

Champs obligatoires et facultatifs

Au minimum, chaque ticket a besoin d'un requester_id et d'un subject. Voici un exemple complet :

{
  "ticket": {
    "requester_id": 827,
    "subject": "Help with account access",
    "description": "Initial ticket description",
    "assignee_id": 19,
    "tags": ["migration", "account-issue"],
    "created_at": "2023-06-25T10:15:18Z",
    "comments": [
      {
        "author_id": 827,
        "created_at": "2023-06-25T10:15:18Z",
        "value": "I can't log into my account"
      }
    ]
  }
}

Conditions préalables pour l'utilisateur

Le demandeur et tous les auteurs de commentaires doivent déjà exister dans Zendesk en tant qu'utilisateurs actifs. L'API rejettera les tickets avec des demandeurs suspendus ou inexistants. Importez d'abord vos utilisateurs à l'aide de l'importation CSV en masse (jusqu'à 2 000 lignes) ou de l'API Utilisateurs.

Gestion des pièces jointes

Les pièces jointes nécessitent un processus en deux étapes :

1. Téléchargez les fichiers vers Zendesk à l'aide du point de terminaison des pièces jointes pour obtenir des jetons de téléchargement
2. Incluez ces jetons dans votre charge utile d'importation de tickets

Pour les images en ligne (captures d'écran dans les commentaires), notez que la documentation de l'API ne couvre pas entièrement ces éléments. Les migrations réelles révèlent que les pièces jointes en ligne sont gérées différemment des pièces jointes standard.

Étape 2 : Structurer votre requête API

Une fois vos données préparées, vous pouvez commencer à créer les requêtes API proprement dites.

Structure de requête de base

Voici un exemple Python montrant comment structurer une requête d'importation de base :

import requests
import base64

email = 'your-email@example.com'
api_token = 'your_api_token_here'
auth_string = base64.b64encode(f"{email}/token:{api_token}".encode()).decode()

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Basic {auth_string}'
}

ticket_data = {
    "ticket": {
        "requester_id": 827,
        "subject": "Help",
        "description": "A description",
        "created_at": "2023-06-25T10:15:18Z",
        "comments": [
            {
                "author_id": 827,
                "created_at": "2023-06-25T10:15:18Z",
                "value": "This is a comment"
            }
        ]
    }
}

response = requests.post(
    'https://your-subdomain.zendesk.com/api/v2/imports/tickets',
    headers=headers,
    json=ticket_data
)

Inclure les commentaires historiques

Le tableau des commentaires prend en charge plusieurs entrées avec des horodatages individuels. Ceci est essentiel pour préserver l'historique complet des conversations de votre système source.

Champs personnalisés et balises

Mappez les champs personnalisés de votre système source aux champs personnalisés Zendesk à l'aide du tableau custom_fields avec des paires id et value. Les balises peuvent être transmises sous forme de simple tableau de chaînes.

Étape 3 : Gérer les cas particuliers

Les migrations réelles impliquent toujours des cas limites. Voici comment gérer les plus courants.

Importer des tickets fermés

Pour les tickets avec un statut fermé, utilisez le paramètre de requête archive_immediately :

POST /api/v2/imports/tickets?archive_immediately=true

Cela contourne le cycle de vie normal des tickets et crée des tickets directement dans vos archives. Zendesk recommande cette approche lors de l'importation de 750 000 tickets historiques ou plus afin d'éviter d'impacter les performances de votre file d'attente de tickets active.

Gérer les grands ensembles de données

Pour les migrations importantes, mettez en œuvre ces pratiques :

• Traitez les tickets par lots de 100 (le maximum de l'API)
• Enregistrez les résultats de chaque lot pour le suivi des erreurs
• Créez une logique de nouvelle tentative pour les requêtes ayant échoué
• Envisagez d'exécuter les importations pendant les heures creuses

Gérer les utilisateurs suspendus

L'API exige que les demandeurs soient des utilisateurs actifs. Si vos données sources incluent des tickets d'utilisateurs suspendus ou supprimés, vous avez deux options :

1. Réactivez les utilisateurs avant l'importation
2. Mappez les utilisateurs supprimés à un compte de remplacement « ancien employé »

Une équipe de migration l'a découvert à ses dépens : « L'API rechignera si les demandeurs et les expéditeurs sont suspendus. Nous avons dû réactiver temporairement les anciens employés pendant le processus d'importation. »

Source : Expérience de migration de la communauté Zendesk

Corps de commentaires vides

L'API rejette les commentaires avec des corps vides, même si l'interface utilisateur de Zendesk le permet (par exemple, lorsqu'une personne envoie une pièce jointe par e-mail sans texte). Vous devrez ajouter un texte de remplacement comme « (Aucun texte de commentaire) » pour ces cas.

Étape 4 : Exécuter et valider

Une fois vos données préparées et les cas limites gérés, il est temps d'exécuter l'importation.

Envoyer des requêtes par lots

Parcourez vos données de tickets par blocs de 100, en envoyant chaque lot au point de terminaison d'importation en masse. Enregistrez la réponse de chaque lot, y compris tous les ID de ticket qui ont été créés avec succès.

Gestion des erreurs

Codes d'état HTTP courants que vous rencontrerez :

• 200 OK : Ticket créé avec succès
• 422 Entité non traitable : Erreur de validation (vérifiez votre structure JSON)
• 429 Trop de requêtes : Limite de débit atteinte ; mettez en œuvre un repli exponentiel
• 401 Non autorisé : Problème d'authentification ; vérifiez votre jeton API

Stratégies de vérification

Après l'importation, vérifiez le succès en :

• Vérifiant que le nombre de tickets correspond à vos données sources
• Échantillonnant les tickets pour vérifier que les horodatages et les commentaires ont été importés correctement
• Confirmant que les pièces jointes sont accessibles
• Testant que les balises et les champs personnalisés apparaissent correctement

Pièges courants et comment les éviter

Apprendre des erreurs des autres peut vous faire gagner beaucoup de temps. Voici les principaux problèmes rencontrés par les équipes de migration.

Les demandeurs doivent être actifs

Comme mentionné, les utilisateurs suspendus provoquent des échecs d'importation. Réactivez-les d'abord ou utilisez des comptes de remplacement.

L'ordre d'importation est important

Vous devez importer dans cette séquence :

1. Organisations (si vous en utilisez)
2. Utilisateurs
3. Tickets

Les tickets référencent les utilisateurs et les organisations par ID, ces enregistrements doivent donc exister en premier.

Les mesures et les SLA ne seront pas calculés

Les mesures et les SLA Zendesk ne sont pas calculés pour les tickets importés. Si vous avez besoin de rapports sur les données historiques, envisagez d'ajouter une balise comme « importé » pour exclure ces tickets des mesures actuelles.

Aucune réservation d'ID de ticket

Vous ne pouvez pas conserver les relations d'ID de ticket de votre système source. Les tickets fusionnés et les références croisées devront être gérés manuellement ou via des tables de mappage externes.

Les conversations secondaires ne sont pas prises en charge

Si votre système source a des conversations secondaires ou des fils de discussion collaboratifs, ceux-ci ne peuvent pas être importés via l'API. Convertissez-les en commentaires internes ou acceptez que ces données ne soient pas transférées.

Particularités de l'analyse JSON

Une équipe de migration utilisant PowerShell a rencontré des problèmes inattendus d'analyse JSON : « Zendesk a rechigné en disant qu'il ne pouvait pas analyser le JSON. Le JSON que j'ai généré était syntaxiquement correct, mais j'ai remis l'objet PowerShell directement. Enregistrer d'abord le JSON dans un fichier, puis l'envoyer à Zendesk a fonctionné sans problème. »

Source : Expérience de migration de la communauté Zendesk

Approches alternatives : eesel AI et autres options

Parfois, l'API n'est pas le bon choix. Envisagez ces alternatives.

Quand utiliser l'importation CSV à la place

L'importation CSV en masse de Zendesk fonctionne pour les utilisateurs et les organisations (pas les tickets) et gère jusqu'à 2 000 lignes par fichier. C'est plus simple que l'API, mais cela a des limitations importantes : pas d'importation de fuseau horaire, pas de photos, pas de préférences de langue et pas de prise en charge des tickets.

Services de migration tiers

Pour les migrations complexes, les services professionnels comme zendesk-import.com ou l'application Zenplates Import peuvent gérer la complexité technique. Ces services facturent généralement en fonction du volume de données, mais permettent de gagner beaucoup de temps de développement.

Alternatives modernes basées sur l'IA

Si vous migrez parce que votre service d'assistance actuel ne répond pas à vos besoins, déterminez si une solution d'IA moderne pourrait être mieux adaptée qu'une migration de plateforme traditionnelle. eesel AI s'intègre à Zendesk pour ajouter une gestion des tickets basée sur l'IA, des réponses automatisées et un routage intelligent sans nécessiter un changement complet de plateforme.

Commencez à créer de meilleurs flux de travail d'assistance

L'importation en masse de tickets via l'API Zendesk vous donne un contrôle précis sur la migration des données historiques, mais elle nécessite une planification minutieuse et une attention particulière aux cas limites. Les étapes clés sont simples : préparez soigneusement vos données, gérez les utilisateurs suspendus, traitez par lots et vérifiez tout par la suite.

Si vous envisagez une migration parce que vos outils d'assistance actuels ne répondent pas à vos besoins, explorez comment l'intégration Zendesk d'eesel AI peut améliorer votre configuration existante avec des fonctionnalités basées sur l'IA. Ou si vous évaluez des approches entièrement nouvelles du service client, consultez la tarification d'eesel AI pour voir comment les solutions d'IA modernes se comparent aux migrations de plateforme traditionnelles.