Tutoriel : un onglet sur la fiche ticket
Dans ce tutoriel, vous écrivez un petit plugin, « Bonjour ticket », qui ajoute un onglet Bonjour à la fiche de chaque ticket de réparation. L’onglet affiche le numéro du ticket et un formulaire qui ajoute une note interne au ticket. Comptez 20 minutes.
Le résultat complet est dans le dépôt : examples/plugins/hello-ticket.
Il vous faut :
- une instance de KiwiDesk de développement et un compte super administrateur ;
- le dépôt de KiwiDesk et Node.js 24 (pour le script d’empaquetage) ;
- un éditeur de texte.
1. Créer le dossier
Section intitulée « 1. Créer le dossier »Répertoirehello-ticket/
- manifest.json
- index.html
- app.js
- styles.css
Pas de dossier node_modules, pas de compilation : un plugin, ce sont des fichiers statiques.
2. Écrire le manifeste
Section intitulée « 2. Écrire le manifeste »manifest.json dit à KiwiDesk qui est le plugin, de quoi il a besoin et où il s’affiche :
{ "id": "hello-ticket", "name": "Bonjour ticket", "version": "1.0.0", "author": "KiwiDesk", "description": "Exemple de plugin : un onglet sur la fiche ticket qui affiche son numéro et ajoute une note interne.", "kiwidesk": ">=0.2.0 <1.0.0", "permissions": ["repair:tickets:read", "repair:tickets:write"], "ui": { "recordTabs": [ { "id": "hello", "record": "ticket", "label": "Bonjour", "icon": "waving_hand", "entry": "index.html#tab" } ] }}repair:tickets:readouvreGET /api/repair/tickets/:idpour lire le ticket ;repair:tickets:writeouvrePOST /api/repair/tickets/:id/notespour la note ;recordTabsajoute un onglet aux fichesticket, qui afficheindex.html.
Chaque champ est expliqué dans la référence du manifeste.
3. Écrire la page
Section intitulée « 3. Écrire la page »index.html ne contient aucun script en ligne : la politique de sécurité des plugins les
refuse. Le code va dans app.js, chargé en module.
<!doctype html><html lang="fr"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Bonjour ticket</title> <link rel="stylesheet" href="styles.css" /> <script type="module" src="app.js"></script> </head> <body> <main class="panel" aria-live="polite"> <p class="label">Ticket</p> <p id="number" class="number">Chargement...</p> <p id="status" class="muted"></p> <form id="note-form" class="form" hidden> <label for="note" class="label">Note interne</label> <textarea id="note" rows="3" maxlength="5000" placeholder="Bonjour depuis le plugin"></textarea> <div class="actions"> <button id="add-note" type="submit">Ajouter une note interne</button> </div> </form> <p id="error" class="error" hidden></p> </main> </body></html>Le formulaire est caché au départ : on ne le montrera qu’aux utilisateurs qui ont le droit d’écrire.
4. Se connecter à KiwiDesk et lire le ticket
Section intitulée « 4. Se connecter à KiwiDesk et lire le ticket »Dans app.js, connect() établit le lien avec la page KiwiDesk et donne le contexte :
la fiche affichée, la boutique, l’utilisateur, le thème.
import { ApiError, connect } from "./kiwidesk-plugin-sdk.js";
const numberElement = document.getElementById("number");const statusElement = document.getElementById("status");const errorElement = document.getElementById("error");
function showError(message) { errorElement.textContent = message; errorElement.hidden = false;}
async function main() { const kiwidesk = await connect(); const record = kiwidesk.context.record; // { type: "ticket", id: "..." } const ticket = await kiwidesk.api.get(`/repair/tickets/${record.id}`); numberElement.textContent = ticket.number; statusElement.textContent = `Bonjour ${kiwidesk.context.user.displayName}, boutique ${kiwidesk.context.store.name}.`;}
main().catch((error) => showError(error instanceof Error ? error.message : "Plugin indisponible."));kiwidesk.api.get() passe par KiwiDesk : la page n’a jamais le jeton de l’utilisateur, et l’appel
se fait avec ses droits réduits à ceux du plugin.
5. Suivre le thème clair ou sombre
Section intitulée « 5. Suivre le thème clair ou sombre »function applyTheme(theme) { document.documentElement.dataset.theme = theme;}
// dans main(), juste après connect() :applyTheme(kiwidesk.context.theme);kiwidesk.onContextChange((context) => applyTheme(context.theme));styles.css définit les couleurs pour :root et :root[data-theme="dark"] (voir le fichier de
l’exemple). Gardez le fond transparent : la page de KiwiDesk est derrière.
6. Ajouter une note interne
Section intitulée « 6. Ajouter une note interne »À la fin de main() :
const form = document.getElementById("note-form");const textarea = document.getElementById("note");const button = document.getElementById("add-note");
// Le formulaire n'est montré qu'à qui peut écrire sur les tickets (et si le plugin en a le droit).form.hidden = !kiwidesk.can("repair:tickets:write");
form.addEventListener("submit", async (event) => { event.preventDefault(); const body = textarea.value.trim() || `Bonjour depuis le plugin pour ${ticket.number}`; button.disabled = true; try { await kiwidesk.api.post(`/repair/tickets/${ticket.id}/notes`, { visibility: "INTERNAL", body }); textarea.value = ""; await kiwidesk.toast("Note interne ajoutée", "success"); await kiwidesk.refresh(); // l'onglet Activité du ticket montre la nouvelle note } catch (error) { showError(error instanceof ApiError ? error.message : "La note n'a pas pu être ajoutée."); } finally { button.disabled = false; }});ApiError.message est la phrase française de l’API (« Vous n’avez pas la permission
nécessaire… »), prête à afficher. button.disabled évite d’ajouter deux notes sur un double
clic.
7. Empaqueter
Section intitulée « 7. Empaqueter »Depuis la racine du dépôt de KiwiDesk :
pnpm installpnpm --filter @kiwidesk/plugin-sdk buildnode examples/plugins/zip-plugin.mjs chemin/vers/hello-ticketzip-plugin: 5 files -> chemin/vers/hello-ticket/dist/hello-ticket-1.0.0.zipLe script ajoute kiwidesk-plugin-sdk.js au paquet : c’est le fichier qu’importe app.js.
8. Installer et essayer
Section intitulée « 8. Installer et essayer »- Dans KiwiDesk, ouvrez Paramètres > Plugins et cliquez sur Installer un plugin.
- Choisissez
hello-ticket-1.0.0.zip. L’écran de revue liste les deux permissions et les routes qu’elles ouvrent. - Choisissez la boutique de test dans Boutiques autorisées, puis Accepter et installer.
- Ouvrez un ticket de cette boutique : l’onglet Bonjour est à la suite des onglets de la fiche, avec une petite icône qui signale un onglet ajouté par un plugin.
- Tapez une note, cliquez sur Ajouter une note interne : la notification apparaît, et la note est dans l’onglet Activité.
Connectez-vous ensuite avec un compte sans repair:tickets:write (un vendeur, selon vos rôles) :
l’onglet s’affiche, sans le formulaire.
9. Faire évoluer le plugin
Section intitulée « 9. Faire évoluer le plugin »- Modifiez vos fichiers.
- Passez
versionà1.0.1dansmanifest.json(une version égale est refusée ; pendant les essais,1.0.1-dev.1,1.0.1-dev.2…). - Refaites le paquet et réinstallez-le : KiwiDesk propose Mettre à jour. Si vous avez ajouté une permission, il faut l’accepter de nouveau.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »- Plugin indisponible : ouvrez la console du navigateur (F12) et choisissez le cadre du
plugin. Une erreur « Refused to execute inline script » signale un script dans le HTML ; un
404surkiwidesk-plugin-sdk.js, un paquet fait sans le script d’empaquetage. - L’onglet n’apparaît pas : la boutique active n’est pas autorisée au plugin, ou il faut recharger la page.
PERMISSION_DENIEDen ajoutant la note : l’utilisateur n’a pasrepair:tickets:write.
D’autres cas sont dans Déboguer.
Pour aller plus loin
Section intitulée « Pour aller plus loin »- garder des données avec le stockage : exemple
customer-notes-widget; - ajouter un bouton d’action et un serveur : exemple
carrier-tracking; - tout le SDK : Référence du SDK.