API externe — documentation et jetons d'accès au Répertoire

Où trouver la documentation des API externes ? #

Ouvrez Paramètres → API externe. Deux pages y sont réunies :

• API externe (Répertoire) — la référence des opérations de lecture et d'écriture sur les contacts et les organisations.
• API Guest — la référence des opérations du portail invité Tickets.

Ces pages sont consultables sans compte : vous pouvez en transmettre l'adresse à votre intégrateur. Elles indiquent l'URL de base de votre installation, la liste des opérations, les paramètres attendus, les réponses possibles et les codes d'erreur. Un panneau d'essai permet même de jouer un appel réel en collant un jeton.

💡 Vous n'avez rien à rédiger : cette documentation est celle de votre propre installation, et elle affiche les champs de votre organisation, pas une liste générique.

Comment générer un jeton d'API pour mon intégrateur ? #

Le jeton du Répertoire est le seul moyen d'ouvrir vos contacts et vos organisations à une application tierce. Il se génère depuis Administration → Jetons d'API.

1. Ouvrez Administration → Jetons d'API. La page s'intitule Jetons d'API du Répertoire.
2. Cliquez Nouveau jeton.
3. Donnez-lui un nom parlant, par exemple « ERP Sage ». C'est ce nom qui identifiera le jeton dans la liste — et dans l'historique des fiches, des mois plus tard.
4. Cochez les portées, une par une : Lire les contacts, Écrire les contacts, Lire les organisations, Écrire les organisations.
5. Renseignez une expiration en jours (par exemple 365), ou laissez vide pour la durée par défaut. Un jeton expire toujours.
6. Cliquez Créer le jeton.
7. Copiez-le immédiatement : il ne s'affiche qu'une seule fois et ne pourra plus jamais être récupéré. Transmettez-le à votre intégrateur par un canal sûr.

Que veulent dire les portées d'un jeton ? #

Une portée est une autorisation, pas un réglage d'affichage : chaque appel est vérifié contre les portées cochées. Elles sont indépendantes — la lecture n'ouvre aucune écriture, et une portée sur les contacts n'accorde rien sur les organisations.

Il n'existe pas de portée « globale ». Tout ce qui n'a pas été coché est refusé, y compris ce que la plateforme ajoutera demain : les autres familles de données (messages, appels, fichiers, tickets, utilisateurs, réseaux sociaux) restent hors de portée, même en lecture, même avec les quatre portées accordées.

Choisissez donc le strict nécessaire : un intégrateur qui ne fait que remonter des contacts n'a besoin que de Lire les contacts.

Comment suivre l'usage d'un jeton ? #

La liste des jetons affiche, pour chacun : son nom, ses portées, sa date de création, son expiration, sa dernière utilisation (ou « Jamais utilisé ») et son état — Actif, Expiré ou Révoqué.

Un champ Rechercher un jeton… vous aide quand la liste s'allonge. Par ailleurs, toute écriture aboutie faite avec un jeton est journalisée côté serveur : on sait quelle opération, sur quelle fiche, depuis quelle adresse et avec quel jeton.

Comment révoquer un jeton ? #

1. Ouvrez Administration → Jetons d'API.
2. Sur la ligne du jeton, cliquez Révoquer, puis confirmez.

La révocation prend effet immédiatement : toutes les intégrations qui utilisent ce jeton seront coupées dès leur prochain appel. L'action est irréversible — rétablir l'accès demandera de créer un nouveau jeton.

Demandez la révocation dès qu'une intégration est arrêtée, ou au moindre doute sur la confidentialité du jeton.

⚠️ Si le message « La révocation n'a pas pu être confirmée » s'affiche, le jeton n'a PAS été révoqué. Réessayez plutôt que de supposer.

Mon jeton est perdu : puis-je le retrouver ? #

Non. Le jeton n'est affiché qu'une fois, à sa création, et rien dans la plateforme ne peut le redonner ensuite. La marche à suivre est toujours la même : créez-en un nouveau, transmettez-le, puis révoquez l'ancien.

Combien de jetons puis-je créer ? #

Un nombre maximum de jetons actifs est appliqué. Quand il est atteint, le message « Le nombre maximum de jetons actifs est atteint » s'affiche : révoquez un jeton devenu inutile avant d'en créer un autre. Réviser régulièrement cette liste est une bonne hygiène — un jeton actif est une porte ouverte.

Et le jeton d'un invité, c'est la même chose ? #

Non, ce sont deux mécanismes différents :

• le jeton d'API du Répertoire ouvre vos contacts et organisations à une application tierce, avec les portées que vous cochez, pour une longue durée ;
• le jeton d'API de test d'un invité agit au nom d'une personne invitée, pour essayer les opérations du portail invité Tickets. Il est de courte durée et l'invité en est notifié par e-mail. Voir Créer et gérer les invités (accès externes).