Aller au contenu

Conventions de l'API

Toutes les routes de l’API suivent les mêmes règles. Les connaître évite la plupart des surprises.

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.

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.

{
"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.

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

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.

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 storeId en 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.

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

  • Les dates renvoyées sont en ISO 8601, en UTC : "2026-11-20T00:49:22.638Z". Convertissez-les dans le fuseau de la boutique (timezone de GET /api/stores, par exemple Europe/Paris).
  • Les filtres de date-heure (createdFrom, createdTo…) attendent une date ISO 8601 avec son décalage : 2026-11-01T00:00:00+01:00 ou 2026-10-31T23:00:00Z.
  • Les périodes des exports comptables (from, to) sont des jours calendaires YYYY-MM-DD, bornes incluses, dans le fuseau de la boutique, sur deux ans au plus.
  • Les exports CSV sont en UTF-8 avec BOM, lignes CRLF, séparateur ; et virgule décimale (ce qu’attend Excel en français). Ajoutez sep=comma pour , 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.

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.