YusralAPI et MCP
Faire travailler vos propres logiciels avec vos données, ou connecter un assistant IA.
L'API et MCP font partie de l'abonnement Professional.
Il existe deux façons de faire travailler d'autres logiciels avec Yusral :
- L'API : pour vos propres logiciels ou une connexion développée par un développeur, par exemple pour créer des dossiers depuis votre site web ou mettre à jour des relations depuis un logiciel comptable.
- MCP : pour les assistants IA comme Claude ou ChatGPT. Ils peuvent alors lire et mettre à jour vos dossiers, tâches et clients quand vous le demandez, et préparer des réponses que vous relisez et envoyez vous-même.
Tout se trouve sous Paramètres > Intégrations > API.
Connecter un assistant IA (MCP)
- Copiez l'Adresse MCP sous Connecter un assistant IA. Il s'agit de
https://app.yusral.com/mcp. - Ajoutez l'adresse comme connecteur dans votre assistant IA.
- L'assistant vous demande de vous connecter à Yusral et de donner l'accès. L'écran indique ce que l'app peut faire : lire, créer et modifier vos dossiers, tâches, notes, relations et contacts, et proposer une réponse que vous relisez et envoyez vous-même. Lisez-le, puis cliquez sur Accorder l'accès.
Vous n'avez pas besoin de clé API pour cela. La connexion est au nom de la personne qui l'approuve et fonctionne avec ses droits : ce que vous ne pouvez pas voir ou faire, l'assistant ne le peut pas non plus. Si vous êtes membre de plusieurs organisations, l'accès vaut pour toutes vos organisations, et l'assistant vous demande d'abord dans laquelle il doit travailler.
Ce qu'un assistant peut faire
| Outil | Ce qu'il fait |
|---|---|
find_cases | Rechercher des dossiers, avec du texte libre et des filtres comme le statut ou le responsable |
get_case | Lire un dossier, avec les notes et messages les plus récents et toutes les tâches |
find_tasks | Rechercher des tâches dans toute l'organisation |
search_everything | Rechercher à la fois dans les dossiers, relations, contacts et tâches, y compris dans le texte des notes et des messages |
get_customer | Lire une relation avec ses contacts et ses dossiers les plus récents, ou un contact avec ses relations |
get_vocabulary | Les statuts, priorités, types, catégories, sources et membres de votre organisation |
create_case | Ouvrir un dossier |
update_case | Modifier un dossier ; chaque modification figure dans l'historique à votre nom |
add_case_note | Ajouter une note interne, visible uniquement par vos collègues |
draft_reply | Préparer une réponse au client, voir ci-dessous |
create_task | Créer une tâche, liée à un dossier ou autonome |
update_task | Modifier une tâche ou la cocher comme terminée |
save_relation | Ajouter ou modifier une relation |
save_contact | Ajouter ou modifier un contact, et le lier à des relations |
list_organisations | Afficher vos organisations, seulement si vous êtes membre de plusieurs |
Ce qu'un assistant ne peut pas faire : supprimer, fusionner, modifier les paramètres, les membres ou la facturation, ou envoyer lui-même un e-mail.
Réponses préparées par l'assistant
Si vous demandez à l'assistant de répondre à un client, il rédige un brouillon. Rien ne part vers le client. Le brouillon attend dans le dossier, sous Rédiger, en tant que Brouillon de votre assistant IA. Lisez-le, choisissez Utiliser pour le placer dans l'éditeur, adaptez-le si nécessaire et envoyez-le vous-même. Rejeter le supprime. Un nouveau brouillon pour le même dossier remplace le précédent.
Vous retirez l'accès dans Profil > Apps connectées, voir Agenda Outlook et apps connectées.
Créer une clé API
Vous créez une clé en tant que Propriétaire ou Administrateur.
- Sous Clés API, cliquez sur Nouvelle clé.
- Donnez à la clé un Nom qui indique à quoi elle sert, comme Connexion avec Exact.
- Choisissez la Validité : Après 30 jours, Après 90 jours (par défaut), Après un an ou N'expire jamais. Ne choisissez N'expire jamais que pour une intégration qui doit vraiment fonctionner en permanence.
- Sous Autorisations, cochez ce que la clé peut faire. Ne donnez pas plus que nécessaire.
- Cliquez sur Créer une clé et copiez la clé tout de suite. Vous ne la voyez que maintenant. Perdue ? Créez-en une nouvelle et révoquez l'ancienne.
Voici les autorisations que vous pouvez donner à une clé :
| Élément | Autorisations | Dans l'API |
|---|---|---|
| Dossiers | Consulter, Voir aussi les dossiers des collègues, Créer, Modifier | ticket:read, ticket:readAll, ticket:create, ticket:update |
| Tâches | Consulter, Voir aussi les tâches des collègues, Créer, Modifier | task:read, task:readAll, task:create, task:update |
| Notes | Consulter, Créer | note:read, note:create |
| Relations | Consulter, Créer, Modifier | company:read, company:create, company:update |
| Contacts | Consulter, Créer, Modifier | contact:read, contact:create, contact:update |
Une clé fonctionne avec les droits de la personne qui l'a créée
Une clé ne peut jamais faire plus que le collègue qui l'a créée. Si cette personne reçoit moins de droits, la clé fonctionne elle aussi avec moins de droits dès la requête suivante. Si elle quitte l'organisation, Créée par affiche Ancien membre. Créez donc les clés des connexions permanentes avec un compte qui reste.
Gérer vos clés
Dans la liste, vous voyez pour chaque clé la Clé, l'Accès, qui l'a créée (Créée par), sa Dernière utilisation et le Statut : Active, Révoquée ou Expiré.
- Révoquer : la clé ne fonctionne plus dès la requête suivante. Vous ne pouvez pas l'annuler. Elle reste dans la liste, pour que vous voyiez encore quand elle a été utilisée pour la dernière fois.
- Supprimer : la clé disparaît de la liste, avec la date de sa dernière utilisation. Il n'est alors plus possible de vérifier après coup ce qu'elle a fait.
Pour les développeurs
La référence complète, avec chaque endpoint et chaque champ, se trouve dans la documentation de l'API. Vous pouvez aussi y tester tout de suite une requête. Vous importez la spécification OpenAPI dans Postman ou Insomnia, ou vous l'utilisez pour générer un client. Vous trouvez aussi les deux sous Utiliser l'API, avec l'URL de base : https://app.yusral.com/api/v1.
| Endpoint | Ce qu'il fait |
|---|---|
GET /me | L'organisation, l'abonnement et les droits dont votre clé dispose réellement |
GET /vocabulary | Tous les statuts, priorités, types, catégories, sources et membres valides |
GET, POST /cases | Récupérer ou créer des dossiers |
GET, PATCH /cases/{id} | Lire ou modifier un dossier |
GET /cases/{id}/messages | Les e-mails d'un dossier |
GET, POST /cases/{id}/notes | Lire les notes d'un dossier ou en ajouter une |
GET /cases/{id}/tasks | Les tâches d'un dossier |
GET, POST /tasks | Récupérer ou créer des tâches |
GET, PATCH /tasks/{id} | Lire ou modifier une tâche |
GET, POST /relations | Récupérer ou créer des relations |
GET, PATCH /relations/{id} | Lire ou modifier une relation |
GET, POST /contacts | Récupérer ou créer des contacts |
GET, PATCH /contacts/{id} | Lire ou modifier un contact |
Quelques points à connaître à l'avance :
Authentification. Envoyez la clé sous la forme Authorization: Bearer <clé> ou x-api-key: <clé>. Commencez par GET /api/v1/me : cela montre ce que votre clé peut réellement faire.
Une liste courte sans message d'erreur. Une clé sans ticket:readAll ne voit que les dossiers attribués au collègue qui l'a créée. C'est aussi le cas si ce collègue a un rôle sans Voir aussi les dossiers des collègues, voir Uniquement son propre travail. Il en va de même pour les tâches avec task:readAll. restrictedToOwnCases dans GET /api/v1/me indique si c'est le cas.
Relations et contacts. Une nouvelle relation passe par les mêmes contrôles que dans l'app : un nom et un domaine e-mail n'apparaissent qu'une fois dans votre organisation, et un particulier n'a pas de numéro de TVA ni de domaine e-mail. Voir Relations et contacts.
Des noms au lieu d'ids. À l'écriture, vous pouvez indiquer un statut, une priorité ou un type tel qu'une personne le voit, comme "status": "In afwachting". GET /api/v1/vocabulary renvoie toutes les valeurs valides en une fois.
Pagination. Chaque liste fonctionne avec un curseur : renvoyez nextCursor en tant que cursor jusqu'à ce qu'il soit null.
Réessayer sans risque. Envoyez un Idempotency-Key avec un POST. Si vous réessayez après un délai d'attente dépassé, rien n'est créé en double.
Pas trop vite. Si vous envoyez trop de requêtes à la suite, vous recevez un 429 avec, dans Retry-After, le nombre de secondes à attendre.
Importer sans notifications. Si vous attribuez des milliers de dossiers ou de tâches lors d'une importation, envoyez "notify": false. Sinon, le responsable reçoit une notification et un e-mail pour chaque dossier.