Recettes pas à pas
Chaque recette a été exécutée sur une instance de KiwiDesk : les réponses montrées sont réelles,
raccourcies, avec des données de démonstration. Les exemples Node.js utilisent fetch, intégré à Node.js 18 et plus, sans
dépendance. Un client complet et typé se trouve dans
examples/api/node-client.
Préparer
Section intitulée « Préparer »-
Créez une clé de boutique dans Paramètres > API & Webhooks, onglet Clés API (voir Authentification et clés API), avec les permissions des recettes que vous suivez :
Recette Permissions Lister les tickets repair:tickets:readCréer et modifier un client core:customers:read,core:customers:writeChanger le statut d’un ticket repair:tickets:statusLire les factures billing:invoices:readExports comptables billing:export:fec -
Mettez l’adresse de l’API et la clé dans des variables d’environnement, jamais dans le code :
Fenêtre de terminal export KIWIDESK_URL=https://kiwidesk.example.com/apiexport KIWIDESK_API_KEY=sys_live_ab12cd34_...Fenêtre de terminal $env:KIWIDESK_URL = "https://kiwidesk.example.com/api"$env:KIWIDESK_API_KEY = "sys_live_ab12cd34_..."Sous PowerShell, appelez
curl.exe(et non l’aliascurl) pour les commandes ci-dessous. -
Pour Node.js, ce petit assistant sert à toutes les recettes (
kiwidesk.mjs) :kiwidesk.mjs export async function kiwidesk(method, path, body) {const response = await fetch(`${process.env.KIWIDESK_URL}${path}`, {method,headers: {authorization: `Bearer ${process.env.KIWIDESK_API_KEY}`,...(body === undefined ? {} : { "content-type": "application/json" }),},body: body === undefined ? undefined : JSON.stringify(body),});const data = response.status === 204 ? null : await response.json();if (!response.ok) {// data.code est stable, data.message est une phrase en françaisthrow new Error(`${response.status} ${data.code} : ${data.message}`);}return data;}
Lister les tickets en cours
Section intitulée « Lister les tickets en cours »curl "$KIWIDESK_URL/repair/tickets?openOnly=true&pageSize=2" \ -H "Authorization: Bearer $KIWIDESK_API_KEY"import { kiwidesk } from "./kiwidesk.mjs";
const page = await kiwidesk("GET", "/repair/tickets?openOnly=true&pageSize=2");for (const ticket of page.items) { console.log(ticket.number, ticket.status, ticket.customer.displayName, ticket.totalCents / 100);}console.log(`${page.total} tickets en cours`);{ "items": [ { "id": "01a1f310-77ee-71e2-a913-e7fc553e365e", "storeId": "01a1bafb-6510-738f-98da-85c97912cce8", "number": "REP-2026-0214", "status": "READY_FOR_PICKUP", "priority": "NORMAL", "reportedIssue": "Écran cassé", "passcodeType": "NONE", "netCents": 10000, "taxCents": 2000, "totalCents": 12000, "receivedAt": "2026-11-19T08:08:25.195Z", "dueAt": "2026-11-21T08:08:25.198Z", "customer": { "id": "01a1f310-...", "displayName": "Camille Exemple", "phone": "06 12 34 56 78" }, "device": { "id": "01a1f310-...", "serialNumber": "R58N12ABCDE", "category": { "slug": "smartphone" } }, "deviceLabel": "Galaxy S21" } ], "page": 1, "pageSize": 2, "total": 92, "pageCount": 46}Filtres utiles : status (répétable), search (numéro, client, IMEI…), customerId,
assignedTechnicianId, createdFrom / createdTo (ISO 8601 avec décalage), overdueOnly=true,
staleDays=14. Les statuts possibles sont expliqués dans
Statuts et leur signification.
Créer un client
Section intitulée « Créer un client »curl -X POST "$KIWIDESK_URL/customers" \ -H "Authorization: Bearer $KIWIDESK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type":"INDIVIDUAL","firstName":"Camille","lastName":"Exemple","phone":"06 12 34 56 78","email":"camille.exemple@example.test"}'import { kiwidesk } from "./kiwidesk.mjs";
const customer = await kiwidesk("POST", "/customers", { type: "INDIVIDUAL", // ou "BUSINESS" avec companyName, legalIdentifier (SIRET), vatNumber firstName: "Camille", lastName: "Exemple", phone: "06 12 34 56 78", email: "camille.exemple@example.test",});console.log(customer.id, customer.displayName);Réponse 201 : le client complet, avec son id ("01a1f66d-f0ce-7051-8be1-2b9967d3e9b2") et son
displayName ("Camille Exemple"). Pour le modifier, envoyez seulement les champs qui changent :
curl -X PATCH "$KIWIDESK_URL/customers/01a1f66d-f0ce-7051-8be1-2b9967d3e9b2" \ -H "Authorization: Bearer $KIWIDESK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"tags":["api","exemple"],"notes":"Client créé par l intégration"}'Créer un ticket
Section intitulée « Créer un ticket »La prise en charge est réservée à une session utilisateur : une clé API reçoit
403 PERMISSION_DENIED (« Cette opération nécessite une session utilisateur »). Connectez un
compte dédié (voir Utiliser une session),
puis :
curl -X POST "$KIWIDESK_URL/repair/tickets" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "storeId": "01a1bafb-6510-738f-98da-85c97912cce8", "customer": { "mode": "existing", "customerId": "01a1f66d-f0ce-7051-8be1-2b9967d3e9b2" }, "device": { "mode": "new", "data": { "categoryId": "01a1bafb-5d79-758b-83f0-fe4c9d33ae3c", "customModelName": "Galaxy S21", "serialNumber": "R58N12ABCDE" } }, "reportedIssue": "Écran fissuré, tactile OK", "passcode": { "type": "REFUSED" } }'Réponse 201 : le ticket complet, numéroté ("number": "REP-2026-0215", "status": "RECEIVED").
| Champ | Valeurs |
|---|---|
customer |
{ "mode": "existing", "customerId" } ou { "mode": "new", "data": { ...client } } |
device |
{ "mode": "existing", "deviceId" } ou { "mode": "new", "data": { "categoryId", ... } } |
passcode |
{ "type": "NONE" }, { "type": "REFUSED" }, { "type": "PIN", "value": "1234" }, PASSWORD, ou PATTERN avec value: [1,5,9] |
priority |
LOW, NORMAL (défaut), HIGH, URGENT |
status |
RECEIVED (défaut) ou WAITING_DEVICE_DROP_OFF (appareil pas encore déposé) |
Les catégories d’appareils se lisent avec GET /api/catalog/categories (permission
core:catalog:read). Le code de déverrouillage est chiffré dès sa réception ; il n’est jamais
renvoyé par les listes.
Changer le statut d’un ticket
Section intitulée « Changer le statut d’un ticket »curl -X POST "$KIWIDESK_URL/repair/tickets/01a1f66e-8ee0-71d2-92fb-a88b1629ab6a/status" \ -H "Authorization: Bearer $KIWIDESK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status":"DIAGNOSING","expectedStatus":"RECEIVED","comment":"Pris en charge par l atelier"}'import { kiwidesk } from "./kiwidesk.mjs";
const ticket = await kiwidesk("POST", `/repair/tickets/${ticketId}/status`, { status: "DIAGNOSING", expectedStatus: "RECEIVED", // refusé si quelqu'un a changé le statut entre-temps comment: "Pris en charge par l'atelier", notifyCustomer: false,});console.log(ticket.number, ticket.status, ticket.allowedTransitions);La réponse est le ticket complet ; allowedTransitions liste les statuts possibles ensuite. Le
changement est tracé, déclenche le webhook repair.ticket.status_changed et, selon les réglages,
les messages automatiques au client (suppressAutoMessages: true pour les éviter).
Les refus à prévoir :
{ "statusCode": 409, "code": "USE_HAND_BACK", "message": "Le ticket REP-2026-0215 se clôture avec « Restituer » (accessoires, signature, encaissement)"}code |
Ce qu’il faut faire |
|---|---|
CONFLICT (avec expectedStatus) |
Relire le ticket : quelqu’un l’a changé |
INVALID_STATUS_TRANSITION |
Ce passage n’est pas permis par le workflow : voir allowedTransitions |
USE_HAND_BACK |
COMPLETED (restitué) ne s’obtient que par la restitution, au comptoir |
APPROVAL_CHANNEL_REQUIRED |
Le devis est accepté par ce changement : précisez approvalChannel (IN_PERSON, PHONE, WRITTEN) |
DEPOSIT_HELD |
Annulation avec un acompte encore détenu : préciser depositRefund |
Une note interne s’ajoute avec POST /api/repair/tickets/{id}/notes et
{"visibility":"INTERNAL","body":"..."} (permission repair:tickets:write).
Lire les factures
Section intitulée « Lire les factures »curl "$KIWIDESK_URL/billing/invoices?from=2026-11-01&to=2026-11-07&type=FINAL&status=PAID&pageSize=100" \ -H "Authorization: Bearer $KIWIDESK_API_KEY"import { kiwidesk } from "./kiwidesk.mjs";
const page = await kiwidesk("GET", "/billing/invoices?from=2026-11-01&to=2026-11-07&pageSize=100");for (const invoice of page.items) { console.log(invoice.number, invoice.type, invoice.status, invoice.totalCents / 100, invoice.amountDueCents / 100);}Les filtres : type (STANDARD, DEPOSIT acompte, FINAL solde de réparation, POS_RECEIPT
ticket de caisse), status (DRAFT, ISSUED, PARTIALLY_PAID, PAID, OVERDUE,
CANCELLED_BY_CREDIT_NOTE), customerId, repairTicketId, unpaid=true, overdue=true, from et
to (jours YYYY-MM-DD).
Le détail (GET /api/billing/invoices/{id}) ajoute les lignes (lineItems, avec taxRateBps,
taxRegime, netCents, taxCents), les règlements, les acomptes déduits, les avoirs, les
mentions légales et le chaînage (signatureHash, previousHash). Le PDF se télécharge avec :
curl -o FAC-2026-0150.pdf "$KIWIDESK_URL/billing/invoices/01a19bac-4200-72f8-8904-558ba3df94bd/pdf" \ -H "Authorization: Bearer $KIWIDESK_API_KEY"Une facture émise est inaltérable : la corriger passe par un avoir, jamais par une modification (voir Avoirs).
Exporter
Section intitulée « Exporter »| Export | Route | Permission |
|---|---|---|
| Tickets (CSV, filtres de la liste) | GET /api/repair/tickets/export |
repair:tickets:read |
| Journal des ventes (CSV) | GET /api/billing/exports/sales-journal?from=&to= |
billing:export:fec |
FEC (texte, |, ISO-8859-15) |
GET /api/billing/exports/fec?from=&to= |
billing:export:fec |
| Factur-X de la période (zip) | GET /api/billing/exports/facturx?from=&to= |
billing:export:fec |
| Journal des clôtures Z (CSV) | GET /api/billing/exports/z-reports?from=&to= |
billing:export:fec |
| Clients (CSV) | GET /api/customers/export |
core:customers:read et core:customers:gdpr |
curl -o journal-ventes.csv \ "$KIWIDESK_URL/billing/exports/sales-journal?from=2026-11-01&to=2026-11-30" \ -H "Authorization: Bearer $KIWIDESK_API_KEY"Date;Type;Numéro;Client;Total HT;TVA collectée;Total TTC;Acomptes déduits;Statut;Facture d'origine;Signature SHA-2562026-11-02 09:52;Facture de solde;FAC-2026-0150;Hôtel Le Saint-Aignan SAS (Emma BLANC);119,00;23,80;142,80;30,00;Réglée;;199c4469...En Node.js, lisez le corps en texte (await response.text()) ou en binaire
(await response.arrayBuffer()) au lieu de json(). Les dates du CSV sont dans le fuseau de la
boutique ; ajoutez sep=comma pour un séparateur ,.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »403 PERMISSION_DENIED:details.requireddonne les permissions attendues ; ajoutez-les à une nouvelle clé (une clé ne se modifie pas : créez-en une autre puis révoquez l’ancienne).404 NOT_FOUNDsur un ticket qui existe : il appartient à une autre boutique que celle de la clé.- Accents illisibles dans le FEC : il est en ISO-8859-15, ouvrez-le avec cet encodage.