Aller au contenu

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.

  1. 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:read
    Créer et modifier un client core:customers:read, core:customers:write
    Changer le statut d’un ticket repair:tickets:status
    Lire les factures billing:invoices:read
    Exports comptables billing:export:fec
  2. 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/api
    export KIWIDESK_API_KEY=sys_live_ab12cd34_...
  3. 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çais
    throw new Error(`${response.status} ${data.code} : ${data.message}`);
    }
    return data;
    }
Fenêtre de terminal
curl "$KIWIDESK_URL/repair/tickets?openOnly=true&pageSize=2" \
-H "Authorization: Bearer $KIWIDESK_API_KEY"
{
"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.

Fenêtre de terminal
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"}'

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 :

Fenêtre de terminal
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"}'

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 :

Fenêtre de terminal
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.

Fenêtre de terminal
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"}'

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

Fenêtre de terminal
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"

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 :

Fenêtre de terminal
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).

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
Fenêtre de terminal
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-256
2026-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 ,.

  • 403 PERMISSION_DENIED : details.required donne 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_FOUND sur 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.