Aller au contenu principal

Construire une application kiosque

Construisez une application dédiée de scan et de check-in/check-out en utilisant l'API Kiosque de Stockaj.

Vue d'ensemble​

Une application kiosque est une station dédiée — typiquement une tablette ou un ordinateur à l'entrée d'un entrepôt — où les utilisateurs scannent des QR codes pour identifier rapidement les articles, vérifier le statut des locations et effectuer des actions.

Prérequis​

  • Compte Stockaj avec un forfait Starter ou supérieur (accès API requis)
  • Token API avec la capacité kiosk:scan
  • Appareil avec caméra (pour le scan QR) ou lecteur de codes-barres

Architecture​

┌──────────────────────────────┐
│      Appareil kiosque        │
│  ┌────────────────────────┐  │
│  │   Caméra / Scanner     │  │
│  │   (lit le QR code)     │  │
│  └──────────┬─────────────┘  │
│             │                │
│  ┌──────────▼─────────────┐  │
│  │   Application kiosque  │  │
│  │   (web ou native)      │  │
│  └──────────┬─────────────┘  │
└─────────────┼────────────────┘
              │ HTTPS
              ▼
┌──────────────────────────────┐
│   API Stockaj                │
│   POST /api/v2/kiosk/scan    │
│   GET  /api/v2/kiosk/search  │
│   PATCH /api/v2/rentals/{id} │
└──────────────────────────────┘

Étape 1 : Configurer l'authentification​

Créez un token API dédié pour votre kiosque :

  1. Allez dans Paramètres → Tokens API.
  2. Créez un token nommé kiosque-entrepot-principal (ou similaire).
  3. Sélectionnez les capacités :
    • kiosk:scan — Requis pour le scan et la recherche
    • rents:read — Voir les détails des locations
    • rents:update — Mettre à jour le statut des locations (pour le check-in/check-out)
    • items:read — Voir les détails des articles

Étape 2 : Implémenter le scan QR​

Utilisez une bibliothèque de scanner QR web ou une API caméra native :

// Utilisation de la bibliothèque html5-qrcode
import { Html5QrcodeScanner } from 'html5-qrcode';

const scanner = new Html5QrcodeScanner('reader', {
  qrbox: { width: 300, height: 300 },
  fps: 10,
});

scanner.render(async (decodedText) => {
  // Envoyer le code scanné à Stockaj
  const result = await scanCode(decodedText);
  displayResult(result);
});

Étape 3 : Appeler l'API de scan​

const API_BASE = 'https://app.stockaj.com/api/v2';
const TOKEN = process.env.STOCKAJ_KIOSK_TOKEN;

async function scanCode(code) {
  const response = await fetch(`${API_BASE}/kiosk/scan`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ code }),
  });

  return response.json();
}

Étape 4 : Afficher les résultats​

function displayResult(result) {
  if (!result.found) {
    showError(`Article non trouvé : ${result.message}`);
    return;
  }

  // Afficher les infos de l'article
  showItemCard({
    name: result.item.name,
    code: result.item.code,
    category: result.item.category,
    available: result.item.available_quantity,
  });

  // Afficher les infos de la variante (si une variante a été scannée)
  if (result.variant) {
    showVariantCard({
      serial: result.variant.serial_number,
      condition: result.variant.condition,
      available: result.variant.is_available,
    });
  }

  // Afficher les infos de location (si l'article est actuellement loué)
  if (result.rental) {
    showRentalCard({
      status: result.rental.status,
      renter: result.renter.name,
      returnDate: result.rental.expected_return_date,
    });
  }
}

Étape 5 : Implémenter la recherche​

Ajoutez une barre de recherche pour la recherche manuelle d'articles :

async function searchItems(query) {
  const response = await fetch(
    `${API_BASE}/kiosk/search?q=${encodeURIComponent(query)}&limit=10`,
    {
      headers: {
        'Authorization': `Bearer ${TOKEN}`,
        'Accept': 'application/json',
      },
    }
  );

  const { results } = await response.json();
  displaySearchResults(results);
}

Étape 6 : Ajouter le check-in/check-out​

Utilisez l'API Locations pour mettre à jour le statut des locations :

async function updateRentalStatus(rentalId, newStatus) {
  const response = await fetch(`${API_BASE}/rentals/${rentalId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: newStatus }),
  });

  return response.json();
}

// Utilisation
await updateRentalStatus(42, 'finished'); // Check-in (retour)
await updateRentalStatus(43, 'dispatched'); // Check-out

Recommandations UI​

Pour les applications kiosque :

  • Grandes zones tactiles — Les boutons doivent faire au moins 48px pour les écrans tactiles
  • Contraste élevé — Utilisez des couleurs claires et de grandes polices
  • Réinitialisation automatique — Effacez l'écran après une période d'inactivité
  • Retour sonore — Jouez des signaux audio pour les scans réussis/échoués
  • Scan continu — Redémarrez automatiquement le scanner après chaque résultat
  • File d'attente hors ligne — Mettez les actions en file d'attente lorsque le réseau est indisponible

Considérations de sécurité​

  • Utilisez un token API dédié avec des capacités minimales
  • Verrouillez l'appareil kiosque — Utilisez le mode kiosque ou l'accès guidé
  • HTTPS uniquement — Assurez-vous que tous les appels API utilisent HTTPS
  • Stockez le token dans des variables d'environnement, jamais dans le code côté client
  • Envisagez un proxy backend pour garder le token côté serveur