Référence du SDK
Le SDK (kiwidesk-plugin-sdk.js) est un fichier JavaScript sans dépendance, au format module. Le
script d’empaquetage le copie dans votre paquet : vos pages l’importent depuis le même dossier.
<!-- index.html : pas de script en ligne, refusé par la politique de sécurité --><script type="module" src="app.js"></script>import { ApiError, HostError, connect } from "./kiwidesk-plugin-sdk.js";
const kiwidesk = await connect();Le SDK échange des messages (postMessage) avec la page de KiwiDesk qui affiche le cadre ; c’est
elle qui appelle l’API. Le code source et ses types TypeScript sont dans packages/plugin-sdk
(pnpm --filter @kiwidesk/plugin-sdk build produit aussi kiwidesk-plugin-sdk.d.ts).
Se connecter
Section intitulée « Se connecter »connect(options?)
Section intitulée « connect(options?) »Établit le lien avec KiwiDesk et renvoie l’objet kiwidesk avec son contexte. À appeler une fois,
au chargement de la page.
const kiwidesk = await connect(); // options : { autoResize?: boolean, timeoutMs?: number }autoResize(vrai par défaut) : la hauteur du cadre suit celle du document, dans les onglets, les actions et les widgets (pas sur une page complète, qui occupe tout l’espace).- Si KiwiDesk ne reçoit pas la connexion dans les 10 secondes, il affiche Plugin indisponible avec un bouton Réessayer, sans bloquer la page.
- Ouverte hors de KiwiDesk (directement dans le navigateur), la page reçoit
HostError("UNSUPPORTED"): « This page must be opened inside KiwiDesk ».
Le contexte
Section intitulée « Le contexte »kiwidesk.context
Section intitulée « kiwidesk.context »const { plugin, slot, record, path, store, user, locale, theme, permissions } = kiwidesk.context;| Propriété | Contenu |
|---|---|
plugin |
{ id, version } du plugin |
slot |
{ kind, id } : kind vaut page, recordTab, recordAction ou dashboardWidget |
record |
{ type, id } de la fiche affichée (onglets et actions), null ailleurs |
path |
Sous-chemin d’une page complète ("commandes/42"), "" ailleurs |
store |
{ id, name } de la boutique active |
user |
{ displayName } de l’utilisateur (ni e-mail ni identifiant) |
locale |
Langue de l’interface (fr) |
theme |
light ou dark |
permissions |
Les permissions utilisables ici : celles de l’utilisateur et accordées au plugin |
kiwidesk.can(permission)
Section intitulée « kiwidesk.can(permission) »Vrai si la permission est utilisable ici. Servez-vous-en pour cacher un bouton, sans compter dessus pour la sécurité (l’API vérifie de toute façon).
form.hidden = !kiwidesk.can("repair:tickets:write");kiwidesk.onContextChange(listener)
Section intitulée « kiwidesk.onContextChange(listener) »Appelé quand KiwiDesk change le contexte : thème, boutique active, sous-chemin d’une page. Renvoie la fonction de désabonnement.
kiwidesk.onContextChange((context) => { document.documentElement.dataset.theme = context.theme;});kiwidesk.refreshContext()
Section intitulée « kiwidesk.refreshContext() »Redemande le contexte complet à KiwiDesk et le renvoie.
const context = await kiwidesk.refreshContext();Appeler l’API
Section intitulée « Appeler l’API »Les appels partent de la page KiwiDesk, au nom de l’utilisateur, avec ses droits réduits à ceux
du plugin. Les chemins sont ceux de l’API sans le préfixe /api.
kiwidesk.api.get(path, query?)
Section intitulée « kiwidesk.api.get(path, query?) »const page = await kiwidesk.api.get("/repair/tickets", { openOnly: true, pageSize: 20 });const ticket = await kiwidesk.api.get(`/repair/tickets/${kiwidesk.context.record.id}`);query accepte des chaînes, nombres, booléens ou tableaux de chaînes (paramètre répété).
kiwidesk.api.post(path, body?), put, patch, delete(path)
Section intitulée « kiwidesk.api.post(path, body?), put, patch, delete(path) »await kiwidesk.api.post(`/repair/tickets/${id}/notes`, { visibility: "INTERNAL", body: "Colis expédié" });await kiwidesk.api.patch(`/customers/${customerId}`, { tags: ["vip"] });Elles renvoient les données de la réponse, et lèvent ApiError si l’API répond une erreur.
kiwidesk.api.request({ method, path, query?, body? })
Section intitulée « kiwidesk.api.request({ method, path, query?, body? }) »La forme générale des fonctions ci-dessus.
const items = await kiwidesk.api.request({ method: "GET", path: "/inventory/items", query: { search: "écran" } });kiwidesk.api.raw(request)
Section intitulée « kiwidesk.api.raw(request) »Même chose, sans lever d’erreur : renvoie { status, ok, data }. Pratique pour traiter un 404
comme un cas normal.
const result = await kiwidesk.api.raw({ method: "GET", path: `/customers/${id}` });if (result.status === 404) { showMessage("Client introuvable");}Une réponse réussie a toujours status: 200 (même pour une création) ; une erreur a le statut de
l’API et data: { code, message, details }.
Stockage
Section intitulée « Stockage »Il faut la permission plugin:storage dans le manifeste. Chaque fonction prend un scope :
"plugin"(défaut) : un espace commun à toutes les boutiques du plugin ;"store": un espace propre à la boutique active ; une autre boutique ne le voit jamais.
Les clés font 1 à 200 caractères parmi A-Z a-z 0-9 . _ : / - ; une valeur est un JSON de
64 Ko au plus ; un plugin a 1 000 clés au plus.
kiwidesk.storage.get(key, scope?)
Section intitulée « kiwidesk.storage.get(key, scope?) »La valeur, ou null si la clé n’existe pas.
const notes = (await kiwidesk.storage.get(`customer:${customerId}`)) ?? { notes: [] };kiwidesk.storage.set(key, value, scope?)
Section intitulée « kiwidesk.storage.set(key, value, scope?) »Crée ou remplace la valeur. Renvoie l’entrée { key, scope, value, updatedAt }.
await kiwidesk.storage.set("preferences", { compact: true }, "store");kiwidesk.storage.remove(key, scope?)
Section intitulée « kiwidesk.storage.remove(key, scope?) »await kiwidesk.storage.remove(`customer:${customerId}`);kiwidesk.storage.list({ prefix?, cursor?, limit?, scope? })
Section intitulée « kiwidesk.storage.list({ prefix?, cursor?, limit?, scope? }) »Une page d’entrées triées par clé (limit jusqu’à 200, 100 par défaut) :
{ items, nextCursor }. Repassez nextCursor en cursor pour la page suivante ; il vaut null
à la fin.
let cursor;do { const page = await kiwidesk.storage.list({ prefix: "shipment:", cursor, limit: 200 }); for (const entry of page.items) { console.log(entry.key, entry.value); } cursor = page.nextCursor ?? undefined;} while (cursor);Agir sur la page KiwiDesk
Section intitulée « Agir sur la page KiwiDesk »kiwidesk.openRecord(type, id)
Section intitulée « kiwidesk.openRecord(type, id) »Ouvre une fiche de KiwiDesk : ticket, customer, invoice, refurbishedUnit ou stockItem.
await kiwidesk.openRecord("customer", entry.customerId);kiwidesk.toast(message, tone?)
Section intitulée « kiwidesk.toast(message, tone?) »Affiche une notification (300 caractères au plus), avec le nom du plugin. tone : "info"
(défaut), "success" ou "error".
await kiwidesk.toast("Note ajoutée", "success");kiwidesk.confirm({ title, message, confirmLabel?, destructive? })
Section intitulée « kiwidesk.confirm({ title, message, confirmLabel?, destructive? }) »Fenêtre de confirmation de KiwiDesk, avec « Demandé par le plugin ». Renvoie true si
l’utilisateur confirme. Une seule fenêtre à la fois.
const ok = await kiwidesk.confirm({ title: "Annuler l'expédition", message: "L'étiquette sera annulée.", confirmLabel: "Annuler l'expédition", destructive: true,});kiwidesk.prompt({ title, message?, label?, placeholder?, defaultValue?, maxLength?, multiline?, required?, confirmLabel? })
Section intitulée « kiwidesk.prompt({ title, message?, label?, placeholder?, defaultValue?, maxLength?, multiline?, required?, confirmLabel? }) »Demande un texte dans une fenêtre de KiwiDesk. Renvoie le texte, ou null si l’utilisateur
annule. maxLength vaut au plus 2 000.
const tracking = await kiwidesk.prompt({ title: "Numéro de suivi", label: "N° de suivi", placeholder: "6A12345678901", required: true,});kiwidesk.print()
Section intitulée « kiwidesk.print() »KiwiDesk imprime le cadre du plugin (la page n’a pas le droit d’ouvrir la boîte d’impression
elle-même). Renvoie false dans un widget du tableau de bord, où l’impression n’est pas proposée.
await kiwidesk.print();kiwidesk.refresh()
Section intitulée « kiwidesk.refresh() »Recharge les données de la page KiwiDesk autour du plugin, après une modification (au plus une fois toutes les 2 secondes).
await kiwidesk.api.post(`/repair/tickets/${id}/notes`, { visibility: "INTERNAL", body });await kiwidesk.refresh(); // l'onglet Activité du ticket montre la notekiwidesk.navigate(path)
Section intitulée « kiwidesk.navigate(path) »Sur une page complète, change le sous-chemin dans la barre d’adresse
(/plugins/<id>/<page>/<path>) ; le nouveau chemin arrive par onContextChange. Renvoie false
ailleurs. Segments de lettres, chiffres, ., _, ~, -, 10 au plus.
await kiwidesk.navigate(`commandes/${order.id}`);kiwidesk.close()
Section intitulée « kiwidesk.close() »Ferme la fenêtre d’une action de fiche (sans effet ailleurs).
await kiwidesk.close();kiwidesk.resize(height) et kiwidesk.autoResize()
Section intitulée « kiwidesk.resize(height) et kiwidesk.autoResize() »Demande une hauteur en pixels ; KiwiDesk la garde entre 60 et 4 000. autoResize() suit
la hauteur du document (déjà actif par défaut) et renvoie la fonction qui l’arrête.
await kiwidesk.resize(320);kiwidesk.disconnect()
Section intitulée « kiwidesk.disconnect() »Coupe le lien : les requêtes en cours sont rejetées (HostError("CANCELLED")).
Les erreurs
Section intitulée « Les erreurs »| Erreur | Quand | Propriétés |
|---|---|---|
ApiError |
L’API a répondu une erreur (api.get, post… et storage) |
status, code (PERMISSION_DENIED, NOT_FOUND, PLUGIN_SCOPE…), body, message en français |
HostError |
KiwiDesk a refusé ou n’a pas pu répondre | code, message |
Codes de HostError :
code |
Cause |
|---|---|
NOT_ALLOWED |
Chemin d’API interdit aux plugins (/auth, /account, /api-keys, /webhooks, /plugins, /public…) |
TOO_MANY_REQUESTS |
Trop d’actions visibles, trop de requêtes en cours, ou une fenêtre déjà ouverte |
INVALID_REQUEST |
Message invalide, corps de requête de plus de 256 Ko |
TIMEOUT |
Pas de réponse dans le délai (30 s ; 10 min pour une confirmation ou une saisie) |
NETWORK_ERROR |
Le serveur KiwiDesk ne répond pas |
UNSUPPORTED |
Page ouverte hors de KiwiDesk |
CANCELLED |
Le plugin a été déconnecté |
try { await kiwidesk.api.post(`/repair/tickets/${id}/notes`, { visibility: "INTERNAL", body });} catch (error) { if (error instanceof ApiError && error.code === "PERMISSION_DENIED") { showMessage("Vous n'avez pas le droit d'ajouter une note."); } else { showMessage(error instanceof Error ? error.message : "Erreur"); }}Les limites
Section intitulée « Les limites »| Limite | Valeur |
|---|---|
| Actions visibles (notification, fiche ouverte, navigation, impression) | 3 par 10 secondes et par cadre |
| Requêtes en cours en même temps | 20 par cadre |
| Corps d’une requête d’API | 256 Ko |
| Taille d’un message | 300 Ko |
| Délai d’une requête | 30 secondes (10 minutes pour confirm et prompt) |
| Délai de connexion | 10 secondes |
| Hauteur d’un cadre | 60 à 4 000 pixels |