This documentation is currently under development. Certain sections are not yet complete and will be added shortly.
Ctrlk
HomeDocumentation
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

API de scan

L’API de scan enregistre le scan d’un code-barres ou d’un QR, puis le relie à une Carte. Cela crée un signal fiable « en magasin / sur site » que les systèmes en aval peuvent utiliser pour les parcours de validation, le suivi des présences ou l’automatisation CRM.

Exemples concrets

  • Fidélité en point de vente: enregistrer un scan à la caisse pour déclencher une automatisation après la visite.

  • Entrée à un événement: enregistrer les scans des accès pour suivre la fréquentation et empêcher la réutilisation.

  • Utilisation d’un 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 l’élément qui rend ce scan exploitable dans The Wallet Crew.

Quand l’API de scan est appelée, The Wallet Crew peut :

  • identifier quelle Carte a été scannée

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

  • émettre 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 validation, l’anti-fraude et la consommation des avantages dépendent du flux de travail choisi.

Point de terminaison

L’API de scan est disponible via cette opération limitée au tenant :

Record a pass barcode scan event

post
/api/{tenantId}/scans

Records scan events when pass barcodes/QR codes are scanned. Scans are correlated to passes and generate scan completion events for downstream systems (redemption, attendance tracking, etc.).

Authorization

Requires PassScan.Scan scope

Scopes requis
Cet endpoint nécessite les scopes suivants :
Autorisations
OAuth2implicitRequis
Authorization URL:
Paramètres de chemin
tenantIdstringRequis
Corps
datastring · min: 3 · max: 2048Requis

Raw Data of the scan value

typestring · enumRequis

Type of data

Valeurs possibles:
Réponses
201

Scan successfully recorded; pass identifier returned

passIdstringRequis

Identifier of the pass

post/api/{tenantId}/scans

Authentification et autorisation

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

Les schémas courants sont :

  • authentification par clé API (X-API-KEY) pour les appels serveur à serveur depuis un backend de point de vente.

  • jeton Bearer OAuth 2.0 pour les identités d’administration/utilisateur.

Le modèle d’autorisation effectif dépend de la configuration du tenant. Dans la définition OpenAPI, ce point de terminaison nécessite le PassScan.Scan scope.

Champs de requête

L’opération accepte deux champs :

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

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

type values

type est une énumération. Les valeurs courantes sont :

  • qrcode

  • pdf417

  • code128

  • ean13

  • datamatrix

  • nfc

  • manual (lorsque le personnel saisit un code)

data est traité comme un identifiant opaque. Le fait de le garder stable importe davantage que de le garder lisible par l’humain. Les modifications de format (trim, zéros initiaux, séparateurs) sont des causes fréquentes d’échec de corrélation.

Réponse

L’opération renvoie l’identifiant de Carte corrélé. Elle renvoie 404 lorsque la corrélation échoue.

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.

L’appel via un relais backend est courant. Cela garde les secrets hors des appareils de scan et permet l’enrichissement, la journalisation et les politiques de reprise.

Valider l’intégration

Une séquence de validation minimale est :

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

  2. Scannez son code-barres/QR et capturez la valeur décodée.

  3. Utilisez l’opération de l’API de scan avec data et type.

  4. Confirmez une 201 réponse et un CarteId.

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

Dépannage

404 Introuvable

La valeur scannée ne correspondait à aucune Carte.

Les causes courantes sont des différences de formatage du code-barres, l’absence de préfixes/suffixes 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 une longueur hors limites ou un type.

401 Non autorisé

Les identifiants sont manquants, invalides ou ne disposent pas du scope requis.

FAQ

Chaque scan de code-barres déclenche-t-il un événement CRM ?

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

Une fois enregistré, le scan peut être transmis à des systèmes connectés tels que Bloomreach sous la forme d’un 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 ils augmentent les contraintes de gestion des secrets et des appareils.

Que faut-il stocker dans data?

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

Garder cette valeur stable entre les systèmes est l’exigence clé.

Mis à jour