Intégrez Kiosk avec votre comptabilité, ERP, BI, automatisations Zapier/Make/n8n. Endpoints REST JSON, webhooks signés HMAC-SHA256, idempotence native.
bashcurl https://kiosk.skrsol.com/api/v1/orders?limit=5 \
-H "Authorization: Bearer kiosk_xxxxxxxxxxxx"Toutes les requêtes nécessitent un Bearer token dans le header Authorization. Les tokens sont liés à une organisation et à un ensemble de scopes.
Authorization: Bearer kiosk_xxxxxxxxxxxxxxxxxxxxxxxxLe token est révocable à tout moment depuis le dashboard. Les requêtes envoyées avec un token révoqué retournent 401 Unauthorized.
Chaque token a des scopes qui limitent les actions possibles. Demandez le minimum nécessaire.
| Scope | Permet |
|---|---|
| orders:read | Lister et lire les commandes |
| orders:write | Créer, modifier, rembourser les commandes |
| products:read | Lister et lire le catalogue |
| products:write | Créer, modifier, supprimer des produits |
| customers:read | Lister et lire les clients |
| customers:write | Créer ou modifier des clients |
| inventory:read | Consulter le stock |
| inventory:write | Ajuster le stock |
1000 requêtes par heure par token. Au-delà : 429 Too Many Requests avec un header Retry-After en secondes.
Sur les endpoints POST, envoyez un header Idempotency-Key (UUID v4) pour rejouer la même requête sans doublon. Conservé 24 h.
Lister les commandes ou en créer programmatiquement (ex : ingestion depuis un site web tiers).
/api/v1/ordersorders:readListe les commandes de votre organisation, triées par date décroissante.
| Paramètre | Type | Description |
|---|---|---|
| limit | integer | Max 200 (défaut 50) |
| status | string | paid · preparing · ready · completed · refunded · cancelled |
| since | ISO 8601 | Ex : 2026-04-30T00:00:00Z |
| location_id | uuid | Filtre par magasin |
bashcurl https://kiosk.skrsol.com/api/v1/orders?limit=10&status=paid \
-H "Authorization: Bearer kiosk_..."json{
"data": [
{
"id": "uuid",
"order_number": "A042",
"status": "paid",
"channel": "self_order",
"location_id": "uuid",
"customer_name": "Jean Dupont",
"customer_phone": null,
"subtotal": "23.99",
"tax_total": "3.59",
"tip_total": "0.00",
"total": "27.58",
"notes": null,
"created_at": "2026-04-30T15:30:54.306Z",
"updated_at": "2026-04-30T15:30:54.306Z"
}
],
"count": 1
}/api/v1/ordersorders:writeCrée une commande avec ses items. Header `Idempotency-Key` recommandé pour rejouer la requête sans dupliquer.
json{
"channel": "online",
"location_id": "uuid",
"customer_name": "Jean Dupont",
"customer_phone": "+15145551234",
"items": [
{ "product_id": "uuid", "quantity": 2, "unit_price": "12.50" },
{ "product_id": "uuid", "quantity": 1, "unit_price": "5.00" }
],
"notes": "Sans oignons"
}bashcurl -X POST https://kiosk.skrsol.com/api/v1/orders \
-H "Authorization: Bearer kiosk_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @order.jsonSynchroniser le catalogue avec un ERP, e-commerce ou outil interne.
/api/v1/productsproducts:readListe les produits du catalogue (recherche accent-insensible sur name/sku/barcode).
| Paramètre | Type | Description |
|---|---|---|
| search | string | Recherche dans name/sku/barcode |
| active | boolean | Défaut true |
| location_id | uuid | Filtre par magasin |
| updated_after | ISO 8601 | Sync incrémentale |
| limit | integer | Max 500 (défaut 100) |
/api/v1/productsproducts:writeCrée un produit. Émet le webhook product.created.
json{
"name": "Latte large",
"base_price": "5.50",
"sku": "LATTE-L",
"category_id": "uuid",
"location_id": "uuid",
"active": true,
"taxable": true
}/api/v1/products/:idproducts:writeModifie un produit. Émet product.updated.
/api/v1/products/:idproducts:writeSupprime un produit. Émet product.deleted.
Synchroniser un CRM ou outil d'emailing.
/api/v1/customerscustomers:readListe les clients avec LTV, points de fidélité et opt-in marketing.
/api/v1/customerscustomers:writeCrée un client.
Lire et ajuster les niveaux de stock par magasin.
/api/v1/inventoryinventory:readNiveaux de stock par produit/magasin.
/api/v1/inventory/adjustinventory:writeAjuste le stock (delta positif ou négatif). Émet inventory.adjusted.
Recevez des événements en temps réel sur votre serveur. Configuration dans Paramètres → Webhooks.
Chaque livraison inclut un header X-Kiosk-Signature (HMAC-SHA256 du body avec la clé secrète du webhook). Vérifiez-le pour rejeter les livraisons forgées.
javascriptimport crypto from "node:crypto";
const expected = crypto
.createHmac("sha256", process.env.KIOSK_WEBHOOK_SECRET)
.update(rawBody) // body brut, AVANT JSON.parse
.digest("hex");
const received = req.headers["x-kiosk-signature"];
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
return res.status(401).end();
}Si votre endpoint répond non-2xx ou timeout (5 s), Kiosk re-tente avec backoff exponentiel pendant 24 h max. Les livraisons sont visibles dans Paramètres → Webhooks → Historique.
| Code | Statut | Description |
|---|---|---|
| 200 | OK | Requête réussie |
| 201 | Created | Ressource créée |
| 400 | Bad Request | Payload invalide |
| 401 | Unauthorized | Token absent ou invalide |
| 403 | Forbidden | Scope insuffisant pour ce token |
| 404 | Not Found | Ressource inexistante |
| 409 | Conflict | Idempotency-Key déjà utilisée avec un autre payload |
| 429 | Too Many Requests | Rate limit dépassé. Header Retry-After indique l'attente. |
| 500 | Internal Server Error | Erreur serveur — réessayer après quelques secondes |
json{ "error": "Missing scope orders:write" }L'API est versionnée par préfixe (/api/v1/...). Aucun changement breaking ne sera introduit dans v1 sans préavis de 90 jours, annoncé sur cette page et par email aux propriétaires de tokens actifs.
Bug, intégration custom, demande de scope ou format ? [email protected]
Réponse sous 24 h ouvrables. Joignez l'ID de requête (header X-Request-Id) si l'erreur est intermittente.