Exemples
Le dossier examples/ du dépôt contient des exemples complets, chacun avec un README.md en
français. Ils ont été exécutés sur la version actuelle de KiwiDesk (plugins installés puis
désinstallés sur une instance de développement). Aucun ne contient de secret : clés, jetons et
secrets de signature se passent en variables d’environnement.
| Dossier | Ce qu’il montre | Langage |
|---|---|---|
examples/api/node-client |
Client typé de l’API avec une clé : lister, créer, modifier | TypeScript (Node.js) |
examples/webhooks/receiver-node |
Récepteur de webhooks : signature, horodatage, idempotence | TypeScript (Node.js) |
examples/webhooks/receiver-python |
Le même récepteur avec la seule bibliothèque standard | Python 3.10+ |
examples/plugins/hello-ticket |
Onglet de la fiche ticket qui ajoute une note interne | JavaScript |
examples/plugins/customer-notes-widget |
Onglet de la fiche client et widget du tableau de bord, stockage, réglages | JavaScript |
examples/plugins/carrier-tracking |
Action et onglet de ticket, serveur avec jeton et webhook | JavaScript, TypeScript |
examples/plugins/zip-plugin.mjs |
Script d’empaquetage des plugins | JavaScript |
Les exemples TypeScript s’exécutent sans compilation avec Node.js 22.18 ou plus (les types
sont effacés au chargement). npm install puis npm run typecheck vérifient les types.
Client de l’API en TypeScript
Section intitulée « Client de l’API en TypeScript »examples/api/node-client : un petit client typé (src/kiwidesk.ts, gestion des erreurs avec
code et message français, pagination) et un script (src/index.ts).
cd examples/api/node-clientexport KIWIDESK_URL=https://kiwidesk.example.com/apiexport KIWIDESK_API_KEY=sys_live_...node src/index.ts # tickets en cours, puis création et modification d'un clientnode src/index.ts status <id du ticket> DIAGNOSING # changement de statut92 ticket(s) en cours, les 10 premiers : REP-2026-0215 DIAGNOSING 0,00 € Camille Exemple - Galaxy S21Client créé : Camille Exemple (01a1f672-e6a0-7574-93bd-66da55f680b9)Client modifié : étiquettes api, exemplePermissions de la clé : repair:tickets:read, repair:tickets:status, core:customers:read,
core:customers:write.
Récepteur de webhooks Node.js
Section intitulée « Récepteur de webhooks Node.js »examples/webhooks/receiver-node : un serveur node:http sans dépendance qui vérifie la
signature et l’horodatage, refuse ce qui n’est pas signé (401), ignore les doublons (identifiants
traités gardés dans data/processed-events.json) et répond 500 en cas d’échec pour que
KiwiDesk réessaie.
cd examples/webhooks/receiver-nodeKIWIDESK_WEBHOOK_SECRET=whsec_... node src/server.ts# dans un autre terminal : un événement signé comme KiwiDesk le feraitKIWIDESK_WEBHOOK_SECRET=whsec_... node src/send-test-event.tsWebhook receiver listening on http://localhost:4600/kiwidesk/webhooks[2026-11-20T00:53:17.513Z] REP-2026-0042 : statut Prêt à récupérerRenvoyer deux fois le même événement (EVENT_ID=... node src/send-test-event.ts) répond
{"received":true,"duplicate":true} la seconde fois ; un mauvais secret répond 401.
Récepteur de webhooks Python
Section intitulée « Récepteur de webhooks Python »examples/webhooks/receiver-python/receiver.py : la même logique avec http.server, hmac et
sqlite3 (identifiants traités dans data/processed-events.sqlite3, avec une contrainte
d’unicité).
cd examples/webhooks/receiver-pythonKIWIDESK_WEBHOOK_SECRET=whsec_... python receiver.py # écoute sur le port 4601Le script d’envoi de l’exemple Node.js le teste aussi :
node src/send-test-event.ts http://localhost:4601/kiwidesk/webhooks.
Pour recevoir les vrais événements de KiwiDesk sur votre poste, voir Tester en local.
Bonjour ticket
Section intitulée « Bonjour ticket »examples/plugins/hello-ticket : le plugin du tutoriel.
Un onglet Bonjour sur la fiche ticket, qui affiche le numéro du ticket et ajoute une note
interne (permissions repair:tickets:read et repair:tickets:write).
Notes clients
Section intitulée « Notes clients »examples/plugins/customer-notes-widget ajoute :
- un onglet Notes à la fiche client : des notes libres sur le client, avec auteur et date, supprimables après confirmation ;
- un widget Dernières notes clients au tableau de bord ; un clic ouvre la fiche du client.
Il montre le stockage du plugin (customer:<id> pour les notes d’un client, recent pour le
widget, chaque valeur bornée sous la limite de 64 Ko) et les réglages : Partage des notes
(communes à toutes les boutiques ou propres à chaque boutique, c’est-à-dire scope plugin ou
store) et Notes affichées dans le widget. Permissions : core:customers:read et
plugin:storage.


node examples/plugins/zip-plugin.mjs examples/plugins/customer-notes-widget# -> examples/plugins/customer-notes-widget/dist/customer-notes-widget-1.0.0.zipSuivi transporteur (plugin avec serveur)
Section intitulée « Suivi transporteur (plugin avec serveur) »examples/plugins/carrier-tracking fait expédier l’appareil réparé au client :
- Sur la fiche ticket, le bouton d’action Expédier ouvre une fenêtre : transporteur et adresse de livraison (reprise de la fiche client). La demande est enregistrée dans le stockage du plugin et une note interne est ajoutée au ticket.
- Quand le ticket passe à Prêt à récupérer, le serveur du plugin reçoit le webhook
repair.ticket.status_changed, vérifie sa signature, crée l’étiquette chez le transporteur et ajoute une note avec le numéro de suivi. - Le serveur suit ensuite le colis (en transit, en cours de livraison, livré) et met à jour le stockage ; l’onglet Expédition du ticket affiche l’état et l’historique.
- Si le ticket est annulé, l’expédition l’est aussi. L’onglet permet aussi d’Annuler l’expédition tant que le colis n’est pas parti.
Le transporteur est simulé (server/src/carrier.ts) : le colis avance d’une étape à chaque
intervalle réglé dans Durée simulée d’une étape de livraison. Le réglage secret Clé d’API du
transporteur montre comment un serveur reçoit un secret que les pages ne voient jamais.
Le dossier sépare le paquet (ui/, à empaqueter) du serveur (server/, à héberger) ; son
README.md décrit l’installation, le lancement du serveur avec le jeton et le secret, et le test
sans exposer votre poste. L’onglet est montré dans Les plugins.