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’adresse de l’API
Section intitulée « L’adresse de l’API »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.
La référence interactive
Section intitulée « La référence interactive »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 |
- Ouvrez
https://kiwidesk.example.com/api/docsdans un navigateur. - Cliquez sur Authorize, collez votre clé API dans le champ bearer (ou dans api-key), puis Authorize.
- 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.
S’authentifier
Section intitulée « S’authentifier »Chaque requête porte une clé API dans l’en-tête Authorization :
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.
Ce que l’API ne fait pas
Section intitulée « Ce que l’API ne fait pas »- 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.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »/api/docsrépond 404 : Swagger UI est désactivé (SWAGGER_ENABLED). Le document/api/docs/openapi.jsonest 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/apivers le conteneur de l’API. 401 UNAUTHENTICATED: l’en-têteAuthorizationmanque ou n’est pas de la formeBearer <clé>.