Aller au contenu

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.
  • 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.

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:read ouvre GET /api/repair/tickets/:id pour lire le ticket ;
  • repair:tickets:write ouvre POST /api/repair/tickets/:id/notes pour la note ;
  • recordTabs ajoute un onglet aux fiches ticket, qui affiche index.html.

Chaque champ est expliqué dans la référence du manifeste.

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.

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.

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.

À 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.

Depuis la racine du dépôt de KiwiDesk :

Fenêtre de terminal
pnpm install
pnpm --filter @kiwidesk/plugin-sdk build
node examples/plugins/zip-plugin.mjs chemin/vers/hello-ticket
zip-plugin: 5 files -> chemin/vers/hello-ticket/dist/hello-ticket-1.0.0.zip

Le script ajoute kiwidesk-plugin-sdk.js au paquet : c’est le fichier qu’importe app.js.

  1. Dans KiwiDesk, ouvrez Paramètres > Plugins et cliquez sur Installer un plugin.
  2. Choisissez hello-ticket-1.0.0.zip. L’écran de revue liste les deux permissions et les routes qu’elles ouvrent.
  3. Choisissez la boutique de test dans Boutiques autorisées, puis Accepter et installer.
  4. 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.
  5. 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.

  1. Modifiez vos fichiers.
  2. Passez version à 1.0.1 dans manifest.json (une version égale est refusée ; pendant les essais, 1.0.1-dev.1, 1.0.1-dev.2…).
  3. Refaites le paquet et réinstallez-le : KiwiDesk propose Mettre à jour. Si vous avez ajouté une permission, il faut l’accepter de nouveau.
  • 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 404 sur kiwidesk-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_DENIED en ajoutant la note : l’utilisateur n’a pas repair:tickets:write.

D’autres cas sont dans Déboguer.

  • 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.