# API de scan
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
{% hint style="info" %}
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.
{% endhint %}
### Point de terminaison
L'API de scan est exposée en tant que point de terminaison scoped au locataire :
```http
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 :
```json
{
"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)
{% hint style="warning" %}
`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.
{% endhint %}
### Réponse
En cas de succès, l'API répond avec l'identifiant de la Carte corrélé depuis le scan :
```json
{
"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é.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.thewalletcrew.io/docs/fr/developper/guides/api-de-scan.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.