API de scan

Enregistrez les scans de codes-barres/QR pour valider les cartes et déclencher des événements en aval (utilisation, présence, signaux CRM).

L'API de scan enregistre un scan de code-barres ou de QR, puis le met en corrélation avec une Carte. Cela crée un signal « en magasin / sur site » fiable que les systèmes en aval peuvent utiliser pour les flux de remboursement, le suivi de la fréquentation ou l'automatisation CRM.

Exemples concrets

• Fidélité retail: enregistrer un scan au passage en caisse pour déclencher une automatisation post-visite.

• Entrée à un événement: enregistrer les scans aux portiques pour suivre la fréquentation et empêcher les réutilisations.

• Remboursement de bon: enregistrer les scans pour marquer une offre comme consommée.

Quand l'API de scan est nécessaire

Le matériel de lecture de codes-barres/QR peut lire la valeur affichée sur une Carte. L'API de scan est la partie qui rend ce scan exploitable dans The Wallet Crew.

Lorsque l'API de scan est invoquée, The Wallet Crew peut :

• identifier quelle Carte a été scannée

• enregistrer l'événement de scan avec horodatage et symbologie

• émouvoir des événements en aval pour les systèmes connectés

L'API de scan ne remplace pas la logique de validation opérationnelle. Elle fournit un enregistrement de scan et une corrélation. Les règles de remboursement, la lutte contre la fraude et la consommation de privilèges dépendent du flux de travail choisi.

Point de terminaison

L'API de scan est exposée en tant que point de terminaison scoped au locataire :

POST /api/{tenantId}/scans

Authentification et autorisation

L'API de scan nécessite une identité autorisée à enregistrer des scans.

Les modèles courants sont :

• Clé API authentification (X-API-KEY) pour les appels serveur-à-serveur depuis un backend POS.

• Jeton Bearer OAuth 2.0 pour les identités admin/utilisateur.

Le modèle d'autorisation effectif dépend de la configuration du locataire. Dans la définition OpenAPI, ce point de terminaison requiert le PassScan.Scan scope.

Payload de la requête

La requête est un objet JSON avec deux champs :

• data: la valeur brute décodée lue par le scanner.

• type: le type d'entrée du scan (symbologie).

Exemple :

{
  "data": "0123456789012",
  "type": "code128"
}

type valeurs

type est un énum. Les valeurs courantes sont :

• qrcode

• pdf417

• code128

• ean13

• datamatrix

• nfc

• manuel (lorsque le personnel saisit un code)

data est traité comme un identifiant opaque. Le garder stable est plus important que le rendre lisible par un humain. Les changements de formatage (trim, zéros initiaux, séparateurs) sont des causes courantes d'échecs de corrélation.

Réponse

En cas de succès, l'API répond avec l'identifiant de la Carte corrélé depuis le scan :

{
  "passId": "..."
}

Si la corrélation échoue, l'API peut renvoyer 404.

Notes d'implémentation

Un système de scan peut appeler l'API de scan soit directement (lorsque l'accès réseau est disponible) soit via un relais backend.

Appeler depuis un relais backend est courant. Cela évite de stocker des secrets sur les appareils de scan et permet l'enrichissement, la journalisation et les politiques de nouvelle tentative.

Validez l'intégration

Une séquence minimale de validation est :

1. Utiliser une vraie Carte émise par The Wallet Crew.

2. Scanner son code-barres/QR et capturer la valeur décodée.

3. Appeler POST /api/{tenantId}/scans avec data et type.

4. Confirmer une 201 réponse et un passId.

5. Confirmer que le signal en aval est reçu (par exemple, wallet_scanned dans Bloomreach).

Dépannage

404 Introuvable

La valeur scannée ne correspond à aucune Carte.

Les causes courantes sont des différences de formatage du code-barres, des préfixes/suffixes manquants, ou un décalage entre la configuration du code-barres du modèle et le décodage du scanner.

400 Requête incorrecte

La charge utile n'a pas passé la validation.

Les causes courantes sont des champs manquants, data longueur hors limites, ou un type.

401 Unauthorized

Les informations d'identification sont manquantes, invalides ou n'ont pas le scope requis.

FAQ

Est-ce que chaque scan de code-barres déclenche un événement CRM ?

Seuls les scans enregistrés via l'API de scan sont connus de The Wallet Crew comme événements de scan.

Lorsqu'il est enregistré, le scan peut être transmis aux systèmes connectés tels que Bloomreach en tant qu' wallet_scanned événement.

L'API de scan doit-elle être appelée depuis l'appareil de scan ou depuis un backend ?

Un relais backend est la configuration la plus courante car il conserve les clés API côté serveur et permet les nouvelles tentatives.

Les appels directs depuis les appareils peuvent fonctionner, mais cela augmente la gestion des secrets et les contraintes de gestion des appareils.

Que doit-on stocker dans data?

La valeur brute décodée qui est configurée dans le code-barres/QR de la Carte.

Maintenir cette valeur stable entre les systèmes est l'exigence clé.