Comment créer des organisations à l'aide de l'API Zendesk : un guide complet

Les organisations sont l'une des fonctionnalités les plus puissantes de Zendesk pour gérer les relations client à grande échelle. Elles vous permettent de regrouper les utilisateurs, de router automatiquement les tickets et de contrôler la visibilité des conversations de support. Bien que vous puissiez créer des organisations manuellement via l'interface Zendesk, la véritable puissance réside dans l'automatisation de ce processus via l'API Zendesk.

Que vous migriez depuis une autre plateforme, que vous vous synchronisiez avec votre CRM ou que vous construisiez un flux d'inscription en libre-service, savoir comment créer des organisations via l'API Zendesk Organizations est essentiel pour toute implémentation sérieuse. Ce guide vous explique tout ce que vous devez savoir, de l'authentification à la gestion des cas extrêmes. Si vous cherchez à automatiser la gestion des organisations au-delà des appels API de base, eesel AI peut gérer l'ensemble du flux de travail pour vous.

Ce dont vous aurez besoin pour commencer

Avant de plonger dans le code, assurez-vous d'avoir mis en place ces prérequis :

• Un compte Zendesk avec accès administrateur. Seuls les administrateurs et les agents avec des rôles personnalisés peuvent créer des organisations via l'API.
• Un jeton API (API token). Vous devrez le générer à partir de votre Centre d'administration Zendesk sous Applications et intégrations > API > API Zendesk.
• Votre sous-domaine Zendesk. C'est la première partie de votre URL Zendesk (par exemple, votreentreprise dans votreentreprise.zendesk.com).
• Un outil pour effectuer des requêtes HTTP. Nous allons montrer des exemples en utilisant cURL, Python et JavaScript, alors choisissez ce qui fonctionne pour votre stack.

L'API Zendesk utilise l'authentification de base avec une combinaison d'adresse e-mail et de jeton API. C'est plus sûr que d'utiliser votre mot de passe et cela vous permet de contrôler l'accès de manière granulaire.

Étape 1 : Générer votre jeton API Zendesk

Votre jeton API est la clé qui permet à votre code de s'authentifier auprès de Zendesk. Voici comment en créer un :

1. Connectez-vous à votre compte Zendesk en tant qu'administrateur
2. Cliquez sur l'icône Centre d'administration dans la barre latérale
3. Accédez à Applications et intégrations > API > API Zendesk
4. Cliquez sur l'onglet Paramètres
5. Activez Accès par jeton si ce n'est pas déjà fait
6. Cliquez sur l'icône plus (+) pour ajouter un nouveau jeton
7. Donnez-lui un nom descriptif comme « API de gestion des organisations »
8. Copiez le jeton immédiatement (Zendesk ne l'affiche qu'une seule fois)

Stockez ce jeton en toute sécurité. Traitez-le comme un mot de passe. Toute personne possédant votre jeton peut accéder à vos données Zendesk via l'API.

Conseil de pro : Créez des jetons distincts pour différentes intégrations plutôt que de réutiliser le même partout. Cela facilite la révocation de l'accès si nécessaire sans casser d'autres systèmes.

Étape 2 : Comprendre l'endpoint des organisations

L'API Organizations suit les conventions REST. Pour créer une organisation, vous devez effectuer une requête POST vers :

https://{sous-domaine}.zendesk.com/api/v2/organizations

Le corps de la requête est un objet JSON contenant les propriétés de l'organisation. Voici à quoi ressemble une requête de création minimale :

{
  "organization": {
    "name": "Acme Corporation"
  }
}

Le seul champ obligatoire est name, et il doit être unique dans votre compte Zendesk. Vous ne pouvez pas inclure de caractères pipe (|) dans le nom, sinon la requête échouera.

Au-delà des bases, vous pouvez définir plusieurs propriétés utiles :

L'authentification utilise HTTP Basic Auth. Combinez votre adresse e-mail avec /token: et votre jeton API, puis encodez le résultat en base64. L'en-tête ressemble à ceci :

Authorization: Basic {base64_encoded_credentials}

Étape 3 : Créer votre première organisation

Mettons cela en pratique avec des exemples de code fonctionnels. Chaque exemple crée une organisation avec des champs courants que vous utiliseriez réellement.

Utilisation de cURL

SUBDOMAIN="votreentreprise"
EMAIL="admin@votreentreprise.com"
TOKEN="votre_jeton_api_ici"

curl -X POST "https://${SUBDOMAIN}.zendesk.com/api/v2/organizations" \
  -H "Content-Type: application/json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -d '{
    "organization": {
      "name": "Acme Corporation",
      "domain_names": ["acme.com", "acmecorp.com"],
      "external_id": "CRM-12345",
      "tags": ["enterprise", "priority"],
      "details": "Client entreprise depuis 2020"
    }
  }'

Utilisation de Python

import requests
import base64

subdomain = "votreentreprise"
email = "admin@votreentreprise.com"
token = "votre_jeton_api_ici"

credentials = base64.b64encode(
    f"{email}/token:{token}".encode()
).decode()

organization = {
    "organization": {
        "name": "Acme Corporation",
        "domain_names": ["acme.com", "acmecorp.com"],
        "external_id": "CRM-12345",
        "tags": ["enterprise", "priority"],
        "details": "Client entreprise depuis 2020"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/organizations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Basic {credentials}"
    },
    json=organization
)

if response.status_code == 201:
    created_org = response.json()["organization"]
    print(f"ID de l'organisation créée : {created_org['id']}")
    print(f"Nom : {created_org['name']}")
else:
    print(f"Erreur : {response.status_code}")
    print(response.json())

Utilisation de JavaScript/Node.js

const axios = require('axios');

// Configuration
const config = {
  subdomain: 'votreentreprise',
  email: 'admin@votreentreprise.com',
  token: 'votre_jeton_api_ici'
};

// Données de l'organisation
const organization = {
  organization: {
    name: 'Acme Corporation',
    domain_names: ['acme.com', 'acmecorp.com'],
    external_id: 'CRM-12345',
    tags: ['enterprise', 'priority'],
    details: 'Client entreprise depuis 2020'
  }
};

// Effectuer la requête
axios.post(
  `https://${config.subdomain}.zendesk.com/api/v2/organizations`,
  organization,
  {
    headers: {
      'Content-Type': 'application/json'
    },
    auth: {
      username: `${config.email}/token`,
      password: config.token
    }
  }
)
.then(response => {
  const org = response.data.organization;
  console.log(`ID de l'organisation créée : ${org.id}`);
  console.log(`Nom : ${org.name}`);
})
.catch(error => {
  console.error('Erreur :', error.response?.data || error.message);
});

Une création réussie renvoie HTTP 201 avec l'objet organisation complet, y compris le champ id généré automatiquement dont vous aurez besoin pour les mises à jour futures.

Étape 4 : Travailler avec des champs d'organisation personnalisés

La plupart des implémentations Zendesk utilisent des champs personnalisés pour stocker des données d'organisation supplémentaires comme les niveaux de compte, les régions ou les ID CRM. Voici comment travailler avec eux via l'API.

Tout d'abord, vous devez savoir quels champs personnalisés existent. Vous pouvez les trouver dans votre Centre d'administration Zendesk sous Objets et règles > Organisations > Champs, ou les récupérer via l'API :

curl "https://{sous-domaine}.zendesk.com/api/v2/organization_fields" \
  -u "{email}/token:{token}"

Chaque champ personnalisé a une clé unique (comme niveau_de_compte ou région). Lorsque vous créez ou mettez à jour une organisation, incluez-les dans l'objet organization_fields :

{
  "organization": {
    "name": "Acme Corporation",
    "organization_fields": {
      "account_tier": "enterprise",
      "region": "north_america",
      "crm_id": "CRM-12345",
      "contract_value": 50000
    }
  }
}

Le format de la valeur dépend du type de champ :

• Champs de texte : Valeurs de chaîne
• Champs de liste déroulante : La valeur de la balise d'option (pas le nom d'affichage)
• Champs numériques : Nombres (pas des chaînes)
• Champs de date : Format ISO 8601 (2024-01-15)
• Champs de case à cocher : Booléen (true ou false)

Cas d'utilisation courant : Synchronisation des données d'organisation depuis votre CRM. Configurez un webhook ou une tâche planifiée qui envoie des mises à jour à Zendesk chaque fois que les détails du compte changent dans votre système principal. Cela permet aux agents de support de travailler avec des informations à jour.

Étape 5 : Gérer les erreurs et les cas extrêmes

Le code de production doit gérer les problèmes. Voici les erreurs les plus courantes que vous rencontrerez :

401 Non autorisé

Cela signifie que vos informations d'identification ne sont pas valides. Vérifiez que :

• Votre jeton API est correct et n'a pas été révoqué
• Votre adresse e-mail correspond au compte qui possède le jeton
• Vous utilisez le bon format : email/token:token (notez la partie /token:)

422 Entité non traitable

La requête a été comprise mais n'a pas pu être traitée. Causes courantes :

• Nom en double : Les noms d'organisation doivent être uniques. Vérifiez d'abord les organisations existantes.
• Caractères non valides : Les noms ne peuvent pas contenir de caractères pipe (|).
• Champs obligatoires manquants : Le champ name est obligatoire.
• Valeurs de champs personnalisés non valides : Assurez-vous que les valeurs de liste déroulante correspondent exactement aux options définies.

429 Trop de requêtes

Vous avez atteint la limite de débit de Zendesk. L'API Organizations autorise 700 requêtes par minute. Si vous devez créer des organisations en masse, ajoutez des délais entre les requêtes :

import time

for org_data in organizations:
    response = requests.post(url, json=org_data, auth=auth)
    if response.status_code == 429:
        # Attendre et réessayer
        time.sleep(1)
        response = requests.post(url, json=org_data, auth=auth)
    # Traiter la réponse...
    time.sleep(0.1)  # Être gentil avec l'API

Meilleure pratique : Lors de la création d'intégrations, vérifiez toujours les codes d'état de réponse et implémentez un backoff exponentiel pour les erreurs 429. Enregistrez les requêtes ayant échoué afin de pouvoir les réessayer plus tard.

Automatisation de la gestion des organisations avec eesel AI

La gestion manuelle des organisations n'est pas évolutive. À mesure que votre base de clients augmente, la synchronisation des organisations Zendesk avec votre CRM, votre système de facturation et d'autres outils devient un fardeau opérationnel important.

C'est là que nous pouvons vous aider. Chez eesel AI, nous avons créé un coéquipier IA qui s'intègre directement à Zendesk et peut automatiser les flux de travail basés sur l'organisation.

Voici comment nos clients utilisent eesel AI avec les organisations :

• Attribution automatique de l'organisation : Lorsqu'un ticket arrive, notre IA peut rechercher le demandeur dans votre CRM, créer ou mettre à jour son organisation dans Zendesk et router le ticket vers la bonne équipe en fonction des propriétés de l'organisation.
• Escalade intelligente : Nous pouvons lire les champs personnalisés de l'organisation (comme le niveau de compte ou le niveau de SLA) et escalader automatiquement les tickets des clients entreprise.
• Réponses tenant compte de l'organisation : Notre IA rédige des réponses qui font référence à des détails spécifiques à l'organisation comme les conditions contractuelles, les responsables de compte dédiés ou les problèmes précédents.

Contrairement à la création d'intégrations API personnalisées, eesel AI apprend de vos données et flux de travail existants. Vous décrivez ce que vous voulez en langage clair (comme « Si le niveau de l'organisation est entreprise, mettez le responsable de compte en copie »), et notre IA gère les appels API, la gestion des erreurs et la logique.

Vous pouvez commencer avec notre copilote IA qui rédige des réponses pour examen par l'agent, puis passer à l'automatisation complète à mesure que vous gagnez en confiance. La plupart des équipes constatent un retour sur investissement en deux mois.

Commencez à créer avec l'API Zendesk Organizations

Vous avez maintenant tout ce dont vous avez besoin pour créer et gérer des organisations par programme dans Zendesk. Récapitulons les étapes clés :

1. Générez un jeton API à partir de votre Centre d'administration Zendesk
2. Structurez votre requête POST vers /api/v2/organizations avec les données de l'organisation
3. Gérez la réponse JSON pour obtenir l'ID de l'organisation créée
4. Utilisez des champs personnalisés pour stocker des données spécifiques à l'organisation
5. Implémentez une gestion des erreurs appropriée pour le code de production

L'API Organizations n'est que le début. Vous pouvez également mettre à jour les organisations, fusionner les doublons, gérer les adhésions à l'organisation et configurer des règles métier basées sur l'organisation.

Pour les cas d'utilisation avancés comme les importations en masse ou la synchronisation bidirectionnelle avec d'autres systèmes, déterminez si une solution basée sur l'IA pourrait faire gagner du temps à votre équipe. Essayez eesel AI gratuitement pendant 7 jours et voyez comment l'automatisation peut transformer vos opérations de support.