Conventions de l'API
Toutes les routes de l’API suivent les mêmes règles. Les connaître évite la plupart des surprises.
Les erreurs
Section intitulée « Les erreurs »Une erreur a toujours le même format, quelle que soit la route :
{ "statusCode": 409, "code": "USE_HAND_BACK", "message": "Le ticket REP-2026-0215 se clôture avec « Restituer » (accessoires, signature, encaissement)", "details": { "status": "DIAGNOSING" }, "requestId": "cc1476fa-d961-426e-9318-3fdd43322edb", "path": "/api/repair/tickets/01a1f66e-8ee0-71d2-92fb-a88b1629ab6a/status", "timestamp": "2026-11-20T00:50:08.584Z"}| Champ | Rôle |
|---|---|
statusCode |
Le statut HTTP, répété |
code |
Code stable, à tester dans votre programme (NOT_FOUND, VALIDATION_FAILED…) |
message |
Phrase en français, compréhensible par un utilisateur, qui peut être affichée telle quelle |
details |
Facultatif : précisions propres au code (champs invalides, montant restant dû…) |
requestId |
Identifiant de la requête, aussi renvoyé dans l’en-tête x-request-id : donnez-le quand vous signalez un problème |
Testez toujours code, jamais message : le texte peut être reformulé d’une version à l’autre,
le code ne change pas.
Les codes les plus courants
Section intitulée « Les codes les plus courants »| Statut | code |
Signification |
|---|---|---|
| 400 | VALIDATION_FAILED |
Corps ou paramètres invalides ; details liste chaque champ |
| 400 | BAD_REQUEST |
Requête incohérente (paramètre inconnu, boutique manquante…) |
| 401 | UNAUTHENTICATED |
Pas d’en-tête Authorization, ou jeton expiré |
| 401 | INVALID_API_KEY |
Clé inconnue, révoquée ou expirée |
| 403 | PERMISSION_DENIED |
Permission manquante (details.required) ou route réservée aux sessions |
| 403 | STORE_ACCESS_DENIED |
Boutique hors de portée |
| 403 | PLUGIN_SCOPE |
Route non ouverte aux plugins |
| 404 | NOT_FOUND |
Ressource introuvable, ou invisible avec vos droits |
| 409 | CONFLICT |
Valeur déjà utilisée, ou donnée modifiée entre-temps par quelqu’un d’autre |
| 409 | INVALID_STATUS_TRANSITION |
Passage de statut interdit par le workflow |
| 409 | REQUEST_KEY_REUSED |
Clé d’idempotence déjà utilisée pour une autre opération |
| 409 | STORE_CLOSED |
Écriture dans une boutique fermée |
| 413 | PAYLOAD_TOO_LARGE |
Corps de plus de 1 Mo |
| 429 | RATE_LIMITED |
Trop de requêtes |
| 500 | INTERNAL_ERROR |
Erreur du serveur : réessayez, puis signalez-la avec le requestId |
Les autres codes sont métier et parlants : USE_HAND_BACK, BALANCE_DUE, DEVICE_IN_WORKSHOP,
INSUFFICIENT_STOCK, DOCUMENT_LOCKED… La liste complète est dans
Messages d’erreur.
Les erreurs de validation
Section intitulée « Les erreurs de validation »{ "statusCode": 400, "code": "VALIDATION_FAILED", "message": "E-mail : adresse e-mail invalide", "details": [ { "path": "email", "field": "E-mail", "message": "Adresse e-mail invalide", "code": "custom" } ]}Chaque élément de details donne le chemin du champ (path, par exemple device.data.imei), son
libellé français (field) et le message. Sur la liste des tickets, un paramètre inconnu est
refusé (« Champ(s) non reconnu(s) : q ») : un filtre mal orthographié ne renvoie pas toute la
liste par erreur. Ailleurs, un paramètre inconnu est ignoré : vérifiez son nom dans la référence.
Pagination, recherche et tri
Section intitulée « Pagination, recherche et tri »Les listes répondent par pages :
{ "items": [ ... ], "page": 1, "pageSize": 50, "total": 236, "pageCount": 5 }| Paramètre | Valeur par défaut | Rôle |
|---|---|---|
page |
1 |
Numéro de page, à partir de 1 |
pageSize |
50 |
Taille de page, 200 au plus |
search |
Recherche libre (200 caractères au plus) | |
sortBy |
selon la liste | Champ de tri ; une valeur inconnue revient au tri par défaut |
sortOrder |
desc |
asc ou desc |
Chaque liste ajoute ses filtres, décrits dans la référence interactive.
Un filtre répété accepte plusieurs valeurs : ?status=RECEIVED&status=DIAGNOSING.
Pour tout lire, demandez les pages une à une jusqu’à page >= pageCount. Quelques listes
techniques (le stockage des plugins) utilisent à la place un curseur : { items, nextCursor }.
Idempotence : clientRequestId
Section intitulée « Idempotence : clientRequestId »Les opérations qui déplacent de l’argent ou du stock acceptent, et souvent exigent, une clé
d’idempotence dans le corps : clientRequestId, un UUID que vous générez (de préférence un
UUID v7 ou v4), une fois par opération.
- Si la réponse se perd (coupure réseau, délai dépassé), renvoyez exactement la même requête avec la même clé : KiwiDesk renvoie le résultat de la première exécution au lieu de recommencer. Un double clic ou une nouvelle tentative n’encaisse jamais deux fois.
- La même clé envoyée avec une autre opération, une autre cible ou un autre contenu est refusée :
409 REQUEST_KEY_REUSED. - Si la première tentative est encore en cours, la seconde attend puis peut répondre
409 REQUEST_IN_PROGRESS: réessayez un peu plus tard avec la même clé.
import { randomUUID } from "node:crypto";
const body = { clientRequestId: randomUUID(), // généré une fois, gardé pour les nouvelles tentatives // ...};Routes concernées notamment : règlements et remboursements de factures, acomptes et facture de solde d’un ticket, ventes en caisse, mouvements et déplacements de stock, réceptions de commandes fournisseurs, transferts entre boutiques.
La boutique de la requête
Section intitulée « La boutique de la requête »KiwiDesk gère plusieurs boutiques dans une même instance. Une requête travaille dans une boutique :
- une clé liée à une boutique agit toujours dans sa boutique ;
- une clé valable pour toutes les boutiques et un jeton de plugin à plusieurs boutiques
choisissent la boutique avec l’en-tête
X-Store-Id: <id de la boutique>; - une session utilisateur agit dans la boutique active du compte. Quelques routes acceptent
aussi
storeIden paramètre ou dans le corps pour viser une autre boutique accessible.
La base de clients, d’appareils et le catalogue sont communs à toutes les boutiques ; les tickets, factures, caisses et stocks appartiennent chacun à une boutique.
L’application web envoie en plus l’en-tête X-KiwiDesk-Store avec la boutique affichée dans
l’onglet du navigateur : si l’utilisateur a changé de boutique dans un autre onglet, une écriture
répond 409 STORE_CHANGED au lieu de partir dans la mauvaise boutique. Les clés API ne sont pas
concernées ; une intégration qui agit au nom d’une session peut s’en servir de la même façon.
Montants, taux et quantités
Section intitulée « Montants, taux et quantités »| Donnée | Format | Exemple |
|---|---|---|
| Montant | Entier en centimes, suffixe Cents |
totalCents: 12000 = 120,00 € |
| Taux (TVA, remise) | Entier en points de base, suffixe Bps |
taxRateBps: 2000 = 20 %, 550 = 5,5 % |
| Devise | Code ISO 4217 de la boutique | "currency": "EUR" |
| Quantité | Entier | quantity: 2 |
Il n’y a jamais de nombre à virgule pour l’argent : convertissez à l’affichage seulement
(cents / 100). Les champs ...Cents peuvent valoir null quand la permission qui les ouvre
manque (coûts et marges sans repair:pricing:view_cost, par exemple).
Dates et heures
Section intitulée « Dates et heures »- Les dates renvoyées sont en ISO 8601, en UTC :
"2026-11-20T00:49:22.638Z". Convertissez-les dans le fuseau de la boutique (timezonedeGET /api/stores, par exempleEurope/Paris). - Les filtres de date-heure (
createdFrom,createdTo…) attendent une date ISO 8601 avec son décalage :2026-11-01T00:00:00+01:00ou2026-10-31T23:00:00Z. - Les périodes des exports comptables (
from,to) sont des jours calendairesYYYY-MM-DD, bornes incluses, dans le fuseau de la boutique, sur deux ans au plus.
Exports et fichiers
Section intitulée « Exports et fichiers »- Les exports CSV sont en UTF-8 avec BOM, lignes CRLF, séparateur
;et virgule décimale (ce qu’attend Excel en français). Ajoutezsep=commapour,et le point décimal. Ils contiennent au plus 50 000 lignes : resserrez les filtres au-delà. Chaque export est tracé dans le journal d’audit. - Le FEC (
/api/billing/exports/fec) est un fichier texte séparé par|, encodé en ISO-8859-15 comme le veut l’administration fiscale. - Les PDF (facture, bon de prise en charge) se téléchargent sur leurs routes
.../pdf.
Identifiants
Section intitulée « Identifiants »Les identifiants sont des UUID (version 7, triables par date de création). Les numéros lisibles
(REP-2026-0215, FAC-2026-0150) sont des champs à part (number) : ne les utilisez pas comme
identifiant dans les URL.