Aller au contenu

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>
app.js
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).

É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 ».
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

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");

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;
});

Redemande le contexte complet à KiwiDesk et le renvoie.

const context = await kiwidesk.refreshContext();

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.

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" } });

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

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.

La valeur, ou null si la clé n’existe pas.

const notes = (await kiwidesk.storage.get(`customer:${customerId}`)) ?? { notes: [] };

Crée ou remplace la valeur. Renvoie l’entrée { key, scope, value, updatedAt }.

await kiwidesk.storage.set("preferences", { compact: true }, "store");
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);

Ouvre une fiche de KiwiDesk : ticket, customer, invoice, refurbishedUnit ou stockItem.

await kiwidesk.openRecord("customer", entry.customerId);

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 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();

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 note

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}`);

Ferme la fenêtre d’une action de fiche (sans effet ailleurs).

await kiwidesk.close();

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);

Coupe le lien : les requêtes en cours sont rejetées (HostError("CANCELLED")).

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");
}
}
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