> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/scan-api.md).
# API Scan
## 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
{% 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 validation, l’anti-fraude et la consommation des avantages dépendent du flux de travail choisi.
{% endhint %}
### Point de terminaison
L’API de scan est disponible via cette opération limitée au tenant :
## Record a pass barcode scan event
> 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
```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Scan"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"AddScanRequest":{"required":["data","type"],"type":"object","properties":{"data":{"maxLength":2048,"minLength":3,"type":"string","description":"Raw Data of the scan value"},"type":{"description":"Type of data","$ref":"#/components/schemas/TypeEnum"}},"additionalProperties":false},"TypeEnum":{"enum":["manual","text","qrcode","pdf417","aztec","code128","code39","codabar","ean8","ean13","itf14","upca","datamatrix","nfc"],"type":"string"},"AddScanResponse":{"required":["passId"],"type":"object","properties":{"passId":{"type":"string","description":"Identifier of the pass"}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/scans":{"post":{"tags":["Scan"],"summary":"Record a pass barcode scan event","description":"Records scan events when pass barcodes/QR codes are scanned. Scans are correlated to passes\nand generate scan completion events for downstream systems (redemption, attendance tracking, etc.).\n\n## Authorization\nRequires PassScan.Scan scope","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Scan payload containing raw barcode data and format type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddScanRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/AddScanRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/AddScanRequest"}}}},"responses":{"201":{"description":"Scan successfully recorded; pass identifier returned","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/AddScanResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/AddScanResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/AddScanResponse"}}}},"400":{"description":"Invalid scan request (data too short/long, missing type)","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"401":{"description":"Not authorized or invalid credentials","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"No pass found with matching scan data","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Processing error during scan event generation"}}}}}}
```
### 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)
{% hint style="warning" %}
`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.
{% endhint %}
### 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é.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/scan-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.