Aller au contenu

Référence du manifeste

Le fichier manifest.json, à la racine du paquet, décrit le plugin. KiwiDesk le valide à l’installation : une erreur refuse le paquet avec un message qui désigne le champ en cause.

{
"id": "carrier-tracking",
"name": "Suivi transporteur",
"version": "1.0.0",
"author": "Exemple SAS",
"description": "Expédier l'appareil réparé et suivre le colis depuis la fiche ticket.",
"homepage": "https://plugins.example.com/carrier-tracking",
"kiwidesk": ">=0.2.0 <1.0.0",
"permissions": ["repair:tickets:read", "repair:tickets:write", "core:customers:read", "plugin:storage"],
"ui": {
"navigation": [
{ "id": "shipments", "label": "Expéditions", "icon": "local_shipping", "entry": "index.html#list" }
],
"recordTabs": [
{ "id": "shipment", "record": "ticket", "label": "Expédition", "icon": "local_shipping", "entry": "shipment.html" }
],
"recordActions": [
{
"id": "ship",
"record": "ticket",
"label": "Expédier",
"icon": "local_shipping",
"entry": "ship.html",
"permissions": ["repair:tickets:write"]
}
],
"dashboardWidgets": [
{ "id": "today", "label": "Colis du jour", "icon": "inventory_2", "entry": "widget.html", "height": 240 }
]
},
"events": ["repair.ticket.status_changed"],
"server": { "webhookUrl": "https://plugins.example.com/carrier-tracking/webhooks" },
"settings": { "schema": "settings.schema.json" }
}
Champ Obligatoire Règle
id oui Identifiant unique : minuscules, chiffres et tirets, commence par une lettre, 3 à 50 caractères (suivi-colis). Il ne change jamais : c’est lui qui relie une mise à jour à la version installée
name oui Nom affiché, 80 caractères au plus
version oui Version semver stricte (1.2.0, 2.0.0-beta.1). Une mise à jour doit être plus récente
author oui Auteur affiché à l’installation, 120 caractères au plus
description non 500 caractères au plus
homepage non Adresse https:// du site du plugin
kiwidesk oui Versions de KiwiDesk compatibles : >=0.2.0 <1.0.0, ^0.2.0, ~0.2.1… Hors de la plage, l’installation est refusée et un plugin déjà installé ne peut plus être réactivé
permissions non Permissions utilisées, voir ci-dessous (200 au plus)
ui non Les emplacements d’interface
events non Événements reçus par le serveur (100 au plus)
server si events { "webhookUrl": "https://..." } : adresse du serveur du plugin
settings non { "schema": "settings.schema.json" } : chemin du fichier des réglages dans le paquet

La version de votre instance s’affiche dans Paramètres > À propos / Système ; l’écran de revue de l’installation la rappelle.

permissions liste les permissions KiwiDesk dont le plugin a besoin (repair:tickets:read, core:customers:write…), plus la capacité plugin:storage pour son espace de stockage. Les codes sont ceux de Rôles et permissions, et sont aussi affichés à droite de chaque case dans la création d’une clé API.

  • Une permission inconnue refuse le paquet.
  • Ces permissions ne sont jamais accordées à un plugin : core:api_keys:manage, core:api_keys:personal, core:webhooks:manage, core:roles:manage, core:users:manage, core:profile:edit_email, core:profile:edit_name, core:profile:edit_phone.
  • Certaines sont sensibles (codes de déverrouillage, coûts, réglages, journal d’audit, RGPD) : l’écran de revue les signale par un badge Sensible et un avertissement.

Une permission ne sert que si une route ouverte aux plugins l’exige, ou pour montrer un emplacement à qui la détient. L’écran de revue montre, pour chaque permission, les routes qu’elle ouvre.

Chaque emplacement a un id (minuscules, chiffres et tirets, 40 caractères au plus, unique dans son type), un label (40 caractères au plus) et une entry : le fichier .html du paquet à afficher, avec une ancre facultative (index.html#list). Les icônes sont des noms de Material Symbols (local_shipping, sticky_note_2).

Chaque emplacement accepte permissions (10 au plus) : il n’est montré qu’aux utilisateurs qui détiennent toutes ces permissions dans la boutique active. Elles doivent figurer dans les permissions du manifeste.

Type Max Champs Affichage
navigation 5 id, label, icon (obligatoire), entry, permissions Entrée du groupe Plugins de la barre latérale ; page complète /plugins/<id du plugin>/<id de la page>/<sous-chemin>
recordTabs 10 id, record, label, icon, entry, permissions Onglet d’une fiche, à la suite des onglets de KiwiDesk ; hauteur ajustée au contenu
recordActions 10 id, record, label, icon (obligatoire), entry, permissions Bouton dans l’en-tête de la fiche, qui ouvre entry dans une fenêtre
dashboardWidgets 5 id, label, icon, entry, height (80 à 800, défaut 240), permissions Carte sous les widgets du tableau de bord d’accueil

record désigne la fiche : ticket (réparation), customer (client), invoice (facture), refurbishedUnit (appareil reconditionné), stockItem (article en stock). Dans la page, la fiche affichée arrive dans context.record ({ type, id }).

Chaque entry doit exister dans le paquet. Une page complète reçoit son sous-chemin dans context.path : une seule page HTML peut ainsi servir plusieurs écrans (commandes/42).

events liste les événements que le serveur du plugin reçoit par webhook signé. Seuls les événements disponibles en webhook sont acceptés (voir le catalogue), et :

  • chaque événement exige au moins une permission de son domaine (repair.ticket.status_changed demande une permission repair:...) ;
  • des événements exigent server.webhookUrl.

server.webhookUrl est une adresse http:// ou https:// (préférez https://). Elle doit être publique : une adresse locale ou privée est refusée à l’installation, sauf si l’instance l’autorise dans WEBHOOK_ALLOWED_PRIVATE_TARGETS (voir Tester en local). Son origine (https://plugins.example.com) est aussi la seule adresse que les pages du plugin peuvent appeler directement.

Un plugin avec server reçoit à l’installation un jeton et, s’il a des événements, un secret de signature (voir Serveur du plugin).

settings.schema désigne un fichier JSON du paquet qui décrit les réglages proposés dans Paramètres > Plugins, fiche du plugin, Réglages du plugin :

{
"fields": [
{
"key": "defaultCarrier",
"label": "Transporteur par défaut",
"type": "select",
"required": true,
"default": "colissimo",
"options": [
{ "value": "colissimo", "label": "Colissimo" },
{ "value": "ups", "label": "UPS" }
]
},
{ "key": "addNotes", "label": "Ajouter une note interne", "type": "boolean", "default": true },
{ "key": "delay", "label": "Délai (minutes)", "type": "number", "default": 2, "min": 1, "max": 1440 },
{ "key": "carrierApiKey", "label": "Clé d'API du transporteur", "type": "secret" }
]
}
Champ Règle
key Lettre puis lettres, chiffres ou _, 40 caractères au plus, unique (30 champs au plus)
label Libellé, 80 caractères au plus
help Aide sous le champ, 300 caractères au plus
type text, number, boolean, select ou secret
required false par défaut ; un text obligatoire ne peut pas être vide
default Valeur par défaut, du type du champ (une option existante pour select, entre min et max pour number)
options Pour select (obligatoire) : [{ "value", "label" }], 50 au plus
min, max Pour number
maxLength Pour text et secret : longueur maximale (500 par défaut, 2000 au plus)

Un champ secret (clé d’API d’un service tiers) n’a pas de valeur par défaut : il est chiffré (AES-256-GCM), en écriture seule dans Paramètres (Enregistré : laissez vide pour le conserver), et transmis au seul serveur du plugin, jamais à ses pages.

Les pages et le serveur lisent les réglages avec GET /api/plugin-runtime/me (champ settings, valeurs par défaut appliquées, null pour un champ facultatif vide).

L’erreur PLUGIN_PACKAGE_INVALID (ou VALIDATION_FAILED avec le chemin du champ) dit ce qui est refusé. Les causes fréquentes :

  • id avec une majuscule ou un _ ; version non semver (1.0) ;
  • entry qui ne finit pas par .html, qui contient .. ou dont le fichier manque au paquet ;
  • un événement sans permission de son domaine, ou des événements sans server ;
  • une permission d’emplacement absente des permissions du manifeste ;
  • un default de select qui n’est pas dans options, ou un default sur un secret.