Aller au contenu

L'API REST

Tout ce que fait l’interface de KiwiDesk passe par son API REST : l’application web n’a aucun accès privilégié. Votre programme peut donc lire et modifier les mêmes données (tickets, clients, appareils, factures, stock, reconditionnement…), dans la limite des permissions qu’on lui donne.

L’API répond sous le chemin /api du serveur de KiwiDesk :

Installation Adresse de l’API
Derrière votre reverse proxy (cas habituel) https://kiwidesk.example.com/api
Depuis le serveur lui-même (port de l’API) http://127.0.0.1:4000/api

Les exemples de cette documentation utilisent https://kiwidesk.example.com/api : remplacez-la par l’adresse de votre instance. Les corps de requête et de réponse sont en JSON (UTF-8), sauf les exports (CSV, PDF, fichiers FEC) qui renvoient un fichier.

KiwiDesk génère lui-même la documentation de chaque route à partir de son code. Elle est donc toujours à jour avec la version installée.

Adresse Contenu
/api/docs Swagger UI : toutes les routes, leurs paramètres et leurs schémas, avec un bouton pour les essayer
/api/docs/openapi.json Le document OpenAPI 3 brut, à importer dans Postman, Insomnia, Bruno ou un générateur de client
  1. Ouvrez https://kiwidesk.example.com/api/docs dans un navigateur.
  2. Cliquez sur Authorize, collez votre clé API dans le champ bearer (ou dans api-key), puis Authorize.
  3. Dépliez une route, par exemple GET /api/repair/tickets, cliquez sur Try it out, puis Execute : la réponse réelle de votre instance s’affiche.

Dans le document OpenAPI, l’extension x-kiwidesk-plugin-access (read ou write) signale les routes ouvertes aux plugins.

Chaque requête porte une clé API dans l’en-tête Authorization :

Fenêtre de terminal
curl https://kiwidesk.example.com/api/repair/tickets?pageSize=5 \
-H "Authorization: Bearer sys_live_xxxxxxxx_..."

Les clés, leurs permissions et leurs limites sont décrites dans Authentification et clés API.

  • Pas de compte client : l’API sert l’équipe de la boutique et ses outils. La page de suivi des clients (/track/...) a ses propres routes publiques, protégées autrement.
  • Pas de version d’API séparée : l’API suit la version de KiwiDesk. Lisez les notes de version avant une mise à jour (voir Mises à jour) et testez vos intégrations sur une copie.
  • Certaines opérations exigent une personne : la prise en charge d’un appareil, l’encaissement en caisse ou la gestion des clés sont réservées à une session utilisateur. Voir Ce qu’une clé ne peut pas faire.
  • /api/docs répond 404 : Swagger UI est désactivé (SWAGGER_ENABLED). Le document /api/docs/openapi.json est désactivé avec lui.
  • Une page HTML « Cannot GET » au lieu d’un JSON : l’adresse ne commence pas par /api, ou votre reverse proxy n’envoie pas /api vers le conteneur de l’API.
  • 401 UNAUTHENTICATED : l’en-tête Authorization manque ou n’est pas de la forme Bearer <clé>.