Aller au contenu

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.

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

Fenêtre de terminal
cd examples/api/node-client
export KIWIDESK_URL=https://kiwidesk.example.com/api
export KIWIDESK_API_KEY=sys_live_...
node src/index.ts # tickets en cours, puis création et modification d'un client
node src/index.ts status <id du ticket> DIAGNOSING # changement de statut
92 ticket(s) en cours, les 10 premiers :
REP-2026-0215 DIAGNOSING 0,00 € Camille Exemple - Galaxy S21
Client créé : Camille Exemple (01a1f672-e6a0-7574-93bd-66da55f680b9)
Client modifié : étiquettes api, exemple

Permissions de la clé : repair:tickets:read, repair:tickets:status, core:customers:read, core:customers:write.

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.

Fenêtre de terminal
cd examples/webhooks/receiver-node
KIWIDESK_WEBHOOK_SECRET=whsec_... node src/server.ts
# dans un autre terminal : un événement signé comme KiwiDesk le ferait
KIWIDESK_WEBHOOK_SECRET=whsec_... node src/send-test-event.ts
Webhook receiver listening on http://localhost:4600/kiwidesk/webhooks
[2026-11-20T00:53:17.513Z] REP-2026-0042 : statut Prêt à récupérer

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

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é).

Fenêtre de terminal
cd examples/webhooks/receiver-python
KIWIDESK_WEBHOOK_SECRET=whsec_... python receiver.py # écoute sur le port 4601

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

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

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.

Fiche client Camille Exemple ouverte sur l'onglet Notes du plugin : champ Nouvelle note avec compteur de caractères, bouton Ajouter la note et deux notes avec auteur, date et bouton Supprimer.
L’onglet Notes du plugin sur une fiche client.
Tableau de bord : sous les widgets de KiwiDesk, le widget Dernières notes clients du plugin liste les notes récentes avec le nom du client, la date et le début de la note.
Le widget Dernières notes clients, sous les widgets du tableau de bord.
Fenêtre de terminal
node examples/plugins/zip-plugin.mjs examples/plugins/customer-notes-widget
# -> examples/plugins/customer-notes-widget/dist/customer-notes-widget-1.0.0.zip

examples/plugins/carrier-tracking fait expédier l’appareil réparé au client :

  1. 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.
  2. 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.
  3. 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.
  4. 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.