> 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 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).
## API de scan
L'API de scan enregistre un scan de code-barres ou de QR, puis le corrèle à 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**: enregistrez un scan à la caisse pour déclencher l'automatisation post-visite.
* **Entrée à un événement**: enregistrez les scans aux accès pour suivre la fréquentation et empêcher la réutilisation.
* **Utilisation de bons**: enregistrez les scans pour marquer une offre comme consommée.
### Quand l'API de scan est nécessaire
Le matériel code-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.
Lorsque 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 l'horodatage et la symbologie
* émettre des événements vers 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 d'utilisation, l'anti-fraude et la consommation des privilèges dépendent du flux de travail choisi.
{% endhint %}
### Point de terminaison
L'API de scan est disponible via cette opération à l'échelle du 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.).
```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":["tenant.scan:scan"]},{"apiKey":[]}],"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.).","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 :
* **Clé API** authentification (`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'administrateur/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 `CarteScan.Scan` scope.
### Champs de requête
L'opération accepte deux champs :
* `données`: la valeur décodée brute lue par le lecteur.
* `type`: le type d'entrée du scan (symbologie).
#### `type` valeurs
`type` est une énumération. Les valeurs courantes sont :
* `qrcode`
* `pdf417`
* `code128`
* `ean13`
* `datamatrix`
* `nfc`
* `manuel` (lorsque le personnel saisit un code)
{% hint style="warning" %}
`données` est traité comme un identifiant opaque. Le fait de le garder stable est plus important que de le rendre lisible par un humain. Les changements 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 la Carte corrélée. Elle renvoie `404` lorsque la corrélation échoue.
### Notes d'implémentation
Un système de scan peut appeler l'API de scan directement (lorsque l'accès réseau est disponible) ou 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 stratégies de relance.
### 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 `données` et `type`.
4. Confirmez une `201` réponse et une `passId`.
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 des codes-barres, l'absence de préfixes/suffixes ou une incohérence entre la configuration des codes-barres du modèle et le décodage du lecteur.
#### `400 Requête incorrecte`
La charge utile a échoué à la validation.
Les causes courantes sont des champs manquants, `données` une longueur hors limites, ou un `type`.
#### `401 Non autorisé`
Les identifiants sont manquants, invalides ou n'ont pas la portée requise.
### 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.
Lorsqu'il est enregistré, le scan peut être transmis à des systèmes connectés tels que Bloomreach sous forme de `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 les contraintes de gestion des secrets et des appareils.
Que doit-on stocker dans données?
La valeur décodée brute qui est configurée dans le code-barres/QR de la Carte.
Le fait de conserver 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.