Plugins
Un plugin ajoute à KiwiDesk une fonction venue d’ailleurs : un onglet « Suivi transporteur » sur les tickets, un bouton « Commander chez le fournisseur », un widget du tableau de bord. Il s’installe depuis le back-office, sous forme d’un paquet .zip, sans toucher au code de KiwiDesk.
Un plugin est isolé : son interface s’affiche dans des cadres séparés de KiwiDesk, il n’agit que dans la limite des permissions et des boutiques que vous lui accordez à l’installation, et jamais au-delà des droits de l’utilisateur qui s’en sert. Un plugin en panne affiche « Plugin indisponible » sans bloquer la page.
La page Paramètres > Avancé > Plugins est réservée aux super administrateurs.

Installer un plugin
Section intitulée « Installer un plugin »- Cliquez sur Installer un plugin et choisissez le fichier
.zip(10 Mo au plus). - KiwiDesk affiche l’écran de revue Installer … ?. Lisez :
- Permissions demandées, avec la mention Sensible pour les plus délicates (réglages, sécurité, boutiques, journal d’audit, matériel, données protégées) ; chaque permission indique les routes de l’API qu’elle ouvre au plugin ;
- Événements reçus par son serveur (ticket créé, statut changé…) ;
- Serveur du plugin : l’adresse qui recevra les événements. Une adresse du réseau local est refusée. Pas de serveur signifie que le plugin n’agit que depuis l’interface ;
- Boutiques autorisées : choisissez les boutiques, ou Toutes les boutiques, y compris les futures.
- Cliquez sur Accepter et installer, ou Refuser.
- Si le plugin a un serveur, KiwiDesk affiche une seule fois le Jeton du plugin et le Secret de signature des webhooks. Copiez-les dans la configuration du serveur du plugin, puis cliquez sur J’ai copié les identifiants.
Résultat : le plugin est Activé. Ses entrées de menu, onglets, boutons et widgets apparaissent pour les utilisateurs qui ont les permissions nécessaires. Si le plugin a des réglages, ils s’affichent dans sa fiche (Réglages du plugin) ; un réglage secret est chiffré et n’est jamais réaffiché.
Un plugin ne reçoit jamais certaines permissions, même s’il les demande : clés API, webhooks, rôles, utilisateurs, modification du profil. Il ne voit jamais les codes de déverrouillage, les liens de suivi des clients ni les secrets.
Gérer un plugin installé
Section intitulée « Gérer un plugin installé »Cliquez sur sa ligne pour ouvrir sa fiche (version, auteur, empreinte SHA-256 du paquet, boutiques, webhook) :
- Désactiver / Activer : désactivé, son jeton est refusé et ses webhooks sont suspendus aussitôt ;
- Mettre à jour : installez un paquet d’une version plus récente. Si elle demande plus de droits (marqués Nouveau), une nouvelle acceptation est nécessaire. Une version égale ou plus ancienne est refusée ;
- Régénérer les identifiants : l’ancien jeton et l’ancien secret cessent immédiatement de fonctionner ;
- Désinstaller : ses emplacements disparaissent, son jeton est révoqué, ses fichiers sont supprimés. Vous pouvez conserver ses réglages et son stockage pour une réinstallation, ou les supprimer ensuite avec Supprimer les données.
Chaque étape (installation, mise à jour, droits, appels sensibles) est inscrite au journal d’audit.
Écrire un plugin
Section intitulée « Écrire un plugin »Un plugin est un dossier avec un manifeste et des pages web statiques :
mon-plugin/ manifest.json index.html app.js styles.cssLe manifeste
Section intitulée « Le manifeste »manifest.json décrit le plugin et ce qu’il demande :
{ "id": "suivi-colis", "name": "Suivi des colis", "version": "1.0.0", "author": "Atelier Exemple", "kiwidesk": "^0.2.0", "permissions": ["repair:tickets:read", "plugin:storage"], "ui": { "recordTabs": [{ "id": "colis", "record": "ticket", "label": "Colis", "entry": "index.html" }] }}| Champ | Rôle |
|---|---|
id |
Identifiant unique : minuscules, chiffres et tirets. |
name, author |
Affichés à l’installation. |
version |
Version stricte (1.2.0) ; une mise à jour doit être plus récente. |
kiwidesk |
Versions de KiwiDesk compatibles (^1.0.0, >=0.2.0 <1.0.0). |
permissions |
Permissions utilisées (codes de Rôles et permissions) et plugin:storage. |
ui.navigation |
Entrée du menu et page complète. |
ui.recordTabs |
Onglet d’une fiche : record vaut ticket, customer, invoice, refurbishedUnit ou stockItem. |
ui.recordActions |
Bouton d’une fiche, qui ouvre le plugin dans une fenêtre. |
ui.dashboardWidgets |
Widget du tableau de bord. |
events |
Événements envoyés au serveur du plugin (webhooks signés HMAC-SHA256). |
server.webhookUrl |
Adresse publique du serveur du plugin (facultatif). |
settings.schema |
Fichier JSON des réglages : text, number, boolean, select, secret. |
Le code de la page
Section intitulée « Le code de la page »Pas de script dans le HTML : le code est dans app.js, chargé en module, qui importe le SDK de KiwiDesk copié à côté.
import { connect } from "./kiwidesk-plugin-sdk.js";
const kiwidesk = await connect();const { record } = kiwidesk.context; // { type: "ticket", id: "..." } dans un onglet de ticketconst ticket = await kiwidesk.api.get(`/repair/tickets/${record.id}`);await kiwidesk.toast(`Ticket ${ticket.number}`, "success");Le SDK donne aussi kiwidesk.can(...), confirm, prompt, openRecord, print, navigate, storage et refresh. La page ne peut ni lire le jeton de l’utilisateur, ni ouvrir de fenêtres du navigateur, ni appeler une autre adresse que son propre serveur.
Empaqueter et installer
Section intitulée « Empaqueter et installer »Depuis le dépôt KiwiDesk :
pnpm --filter @kiwidesk/plugin-sdk buildnode examples/plugins/zip-plugin.mjs chemin/vers/mon-pluginLe script copie le SDK, garde les fichiers acceptés (HTML, JS, CSS, JSON, images, polices) et écrit dist/<id>-<version>.zip, à installer comme ci-dessus. L’exemple complet examples/plugins/hello-ticket ajoute un onglet aux tickets. La conception détaillée (sécurité, routes ouvertes, serveur et webhooks) est décrite dans docs/plugins.md du dépôt.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »- « Le paquet dépasse 10 Mo » : allégez les images du plugin.
- Badge Incompatible : le plugin demande une autre version de KiwiDesk que celle installée. Demandez une mise à jour à son auteur.
- « Cette adresse pointe vers le réseau local » : le serveur du plugin doit avoir une adresse publique.
- « Plugin indisponible » dans une page : le plugin n’a pas répondu en 10 secondes. Réessayer, sinon désactivez-le et contactez son auteur.
- « Plugin arrêté » : le cadre du plugin a tenté de charger une autre page ; KiwiDesk l’a fermé et l’a inscrit au journal d’audit.