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.
Exemple complet
Section intitulée « Exemple complet »{ "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" }}Champs généraux
Section intitulée « Champs généraux »| 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
Section intitulée « Permissions »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.
Emplacements
Section intitulée « Emplacements »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).
Événements et serveur
Section intitulée « Événements et serveur »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_changeddemande une permissionrepair:...) ; - 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).
Schéma des réglages
Section intitulée « Schéma des réglages »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).
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »L’erreur PLUGIN_PACKAGE_INVALID (ou VALIDATION_FAILED avec le chemin du champ) dit ce qui
est refusé. Les causes fréquentes :
idavec une majuscule ou un_;versionnon semver (1.0) ;entryqui 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
permissionsdu manifeste ; - un
defaultdeselectqui n’est pas dansoptions, ou undefaultsur unsecret.