Aller au contenu

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.

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

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.

Fenêtre de terminal
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 le storeId de 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.
{
"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.

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 de X-Store-Id (ou de l’unique boutique du plugin). Sans boutique déterminée, la réponse est 400 (« 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). cursor est 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 }
  1. Vérifiez chaque webhook (signature et horodatage) avant de lire son contenu ; répondez 401 sinon.
  2. Répondez vite (moins de 10 secondes) ; faites les appels longs ensuite.
  3. Soyez idempotent : retenez les X-KiwiDesk-Event-Id traité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 »).
  4. Répondez 5xx en cas d’échec pour que KiwiDesk réessaie, et 2xx seulement quand le travail est fait ou inutile.
  5. 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.

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