Serveur du plugin
Les pages d’un plugin n’agissent que quand quelqu’un les ouvre. Pour réagir à un événement (un
ticket devient prêt), travailler en tâche de fond (suivre un colis) ou parler à un service tiers
avec une clé secrète, un plugin a besoin d’un serveur : un service à vous, hébergé où vous
voulez, déclaré dans le manifeste par server.webhookUrl.
Les identifiants du serveur
Section intitulée « Les identifiants du serveur »À l’installation d’un plugin avec serveur, KiwiDesk affiche une seule fois la fenêtre Identifiants de <nom du plugin> :
| Valeur | Usage |
|---|---|
Jeton du plugin (plg_live_...) |
Appeler l’API : Authorization: Bearer plg_live_... |
Secret de signature des webhooks (whsec_...) |
Vérifier les événements reçus (seulement si events n’est pas vide) |
Copiez-les dans la configuration de votre serveur (variables d’environnement, gestionnaire de secrets), puis cliquez sur J’ai copié les identifiants. En cas de perte ou de fuite, ouvrez la fiche du plugin dans Paramètres > Plugins et cliquez sur Régénérer les identifiants : les anciens cessent aussitôt de fonctionner.
Recevoir les événements
Section intitulée « Recevoir les événements »Le serveur reçoit les événements du manifeste exactement comme un
webhook : POST JSON sur server.webhookUrl, mêmes en-têtes
(X-KiwiDesk-Event, X-KiwiDesk-Event-Id, X-KiwiDesk-Timestamp, X-KiwiDesk-Signature), même
signature HMAC-SHA256, mêmes nouvelles tentatives et même désactivation après 10 envois en échec.
Il ne reçoit que les événements :
- des boutiques autorisées au plugin ;
- pendant que le plugin est activé (désactivé : les envois sont suspendus).
L’état du webhook (Actif, En pause, nombre de livraisons en échec) est affiché dans la fiche du plugin.
Appeler l’API avec le jeton
Section intitulée « Appeler l’API avec le jeton »curl https://kiwidesk.example.com/api/repair/tickets/01a1f66e-8ee0-71d2-92fb-a88b1629ab6a \ -H "Authorization: Bearer plg_live_ab12cd34_..." \ -H "X-Store-Id: 01a1bafb-6510-738f-98da-85c97912cce8"- Le jeton a les permissions accordées au plugin, dans ses boutiques autorisées, et n’atteint que les routes ouvertes aux plugins.
- Un plugin autorisé dans plusieurs boutiques précise la boutique avec
X-Store-Id(prenez lestoreIdde l’événement reçu). Avec une seule boutique, c’est inutile. - Les écritures faites avec le jeton sont tracées au journal d’audit.
L’API d’exécution
Section intitulée « L’API d’exécution »GET /api/plugin-runtime/me
Section intitulée « GET /api/plugin-runtime/me »{ "id": "01a1f676-90cc-729c-8a06-b827890e9159", "pluginKey": "carrier-tracking", "version": "1.0.0", "grantedPermissions": ["repair:tickets:read", "repair:tickets:write", "core:customers:read", "plugin:storage"], "allStores": false, "storeIds": ["01a1bafb-6510-738f-98da-85c97912cce8"], "settings": { "defaultCarrier": "colissimo", "addNotes": true, "simulationMinutes": 2 }, "secrets": { "carrierApiKey": "..." }}settings contient les réglages non secrets, valeurs par défaut appliquées. secrets n’est
rempli que pour le jeton (le serveur) ; appelé depuis une page, il est vide. Relisez ces
réglages régulièrement (toutes les minutes, par exemple) : l’administrateur peut les changer à tout
moment.
Le stockage
Section intitulée « Le stockage »Il faut plugin:storage dans le manifeste. Les mêmes données sont accessibles aux pages par
kiwidesk.storage : c’est le moyen simple de partager un état entre les pages et le serveur.
| Requête | Rôle |
|---|---|
GET /api/plugin-runtime/storage/item?key=<clé>&scope=plugin |
Lire une entrée (404 si absente) |
PUT /api/plugin-runtime/storage/item?key=<clé>&scope=plugin avec { "value": ... } |
Créer ou remplacer |
DELETE /api/plugin-runtime/storage/item?key=<clé>&scope=plugin |
Supprimer |
GET /api/plugin-runtime/storage?prefix=&cursor=&limit=&scope= |
Lister par page : { items, nextCursor } |
scope=plugin(défaut) : espace commun à toutes les boutiques du plugin ;scope=store: espace de la boutique deX-Store-Id(ou de l’unique boutique du plugin). Sans boutique déterminée, la réponse est400(« Indiquez la boutique de cette entrée de stockage (en-tête X-Store-Id) »).- Clés de 1 à 200 caractères
A-Z a-z 0-9 . _ : / -, valeurs JSON de 64 Ko au plus, 1 000 clés au plus, pages de 200 entrées au plus (100 par défaut).cursorest la dernière clé de la page précédente.
const headers = { authorization: `Bearer ${process.env.KIWIDESK_PLUGIN_TOKEN}`, "content-type": "application/json" };const url = `${process.env.KIWIDESK_URL}/plugin-runtime/storage/item?scope=plugin&key=shipment:${ticketId}`;
await fetch(url, { method: "PUT", headers, body: JSON.stringify({ value: shipment }) });const entry = await (await fetch(url, { headers })).json(); // { key, scope, value, updatedAt }Un serveur fiable
Section intitulée « Un serveur fiable »- Vérifiez chaque webhook (signature et horodatage) avant de lire son contenu ; répondez
401sinon. - Répondez vite (moins de 10 secondes) ; faites les appels longs ensuite.
- Soyez idempotent : retenez les
X-KiwiDesk-Event-Idtraités, et écrivez des traitements qui supportent la répétition (ne créez l’étiquette que si l’expédition est encore « demandée »). - Répondez 5xx en cas d’échec pour que KiwiDesk réessaie, et 2xx seulement quand le travail est fait ou inutile.
- Gardez les secrets hors du code : jeton, secret de signature et clés tierces en variables d’environnement.
L’exemple examples/plugins/carrier-tracking
met tout cela en œuvre : webhook vérifié, stockage partagé avec les pages, notes internes sur le
ticket et suivi en tâche de fond.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »| Symptôme | Cause probable |
|---|---|
401 INVALID_API_KEY avec le jeton |
Plugin désactivé ou désinstallé, identifiants régénérés, jeton mal copié |
403 PLUGIN_SCOPE |
Route non ouverte aux plugins |
403 PERMISSION_DENIED |
Permission non demandée dans le manifeste (mettez à jour le plugin) |
403 STORE_ACCESS_DENIED |
X-Store-Id d’une boutique non autorisée au plugin |
| Aucun événement reçu | Plugin désactivé, boutique non autorisée, adresse injoignable : voir l’état du webhook dans la fiche du plugin |