> 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/guides-design/fr/conception/stamp-card.md).

# Carte à tampons

Configurer un modèle de Carte à tampons pour Apple Wallet et Google Wallet : objectif de tampons, comportement lorsqu’elle est pleine, une image par nombre de tampons et un avantage de récompense.

Une carte de tampons est la version numérique de la carte de fidélité papier tamponnée à chaque visite : « achetez neuf cafés, le dixième est offert ». La Carte montre combien de tampons ont été collectés, l’image sur la carte change à chaque tampon, et lorsque l’objectif est atteint The Wallet Crew peut accorder automatiquement une récompense.

Une carte de tampons est son propre type de modèle de Carte dans The Wallet Crew. Elle ressemble et fonctionne comme une carte de fidélité dans Apple Wallet et Google Wallet. Comme le compteur vit sur la Carte elle-même, une carte de tampons fonctionne sans aucun système de fidélité externe.

<details>

<summary><strong>Exemples concrets</strong></summary>

* **Café :** dix tampons pour une boisson gratuite au choix du client. La carte affiche une tasse qui se remplit, et la récompense apparaît sur la Carte lorsque le dixième tampon est ajouté.
* **Lavage de voiture :** cinq lavages, le sixième est gratuit. La carte reste pleine jusqu’à ce que le lavage gratuit soit utilisé, puis commence un nouveau cycle.
* **Boulangerie ou pizzeria :** un tampon par achat, avec un design saisonnier appliqué via un thème.
* **Salon de coiffure, toilettage pour animaux, bar à jus ou salle de sport :** un tampon par visite ou par cours, avec un avantage de récompense utilisé au comptoir dans Carte Scanner.
* **Série d’événements :** un tampon par match ou concert assisté, avec une récompense de collection à la fin de la saison.

</details>

## Comment fonctionne une carte de tampons

Chaque Carte de tampons comporte un tableau de tampons : le compteur, l’objectif et la liste de chaque tampon ajouté ou corrigé. L’ajout d’un tampon pousse la mise à jour vers le Wallet du détenteur.

```mermaid
flowchart LR
    S["Tampon ajouté<br/>(API, Carte Scanner)"] --> C["Compteur + 1<br/>image du nouveau compteur"]
    C --> G{"Objectif atteint ?"}
    G -- Non --> W["Carte mise à jour<br/>dans le Wallet"]
    G -- Oui --> R["Avantage de récompense accordé<br/>(facultatif)"]
    R --> B{"Lorsque l’objectif est atteint"}
    B -- "Rester pleine, effacer au prochain tampon" --> F1["Tableau complet affiché,<br/>le tampon suivant lance un nouveau cycle"]
    B -- "Effacer immédiatement" --> F2["Le tableau s’efface d’un coup"]
    B -- "Rester pleine" --> F3["La carte n’accepte plus de tampons"]
```

### Dans Apple Wallet

Dans Apple Wallet, une carte de tampons utilise la mise en page de carte de magasin, comme une carte de fidélité. Le **bande** l’image derrière le champ principal est remplacée par l’image du nombre de tampons actuel, afin que le détenteur voie les tampons se remplir.

Quand **Utiliser la nouvelle mise en page de poster** est activé dans l’onglet Apple, les iPhone exécutant iOS 27 ou version ultérieure affichent la carte avec la mise en page de poster, et le **visuel du poster** du nombre actuel est utilisé à la place de la bande. Les iPhone plus anciens conservent la mise en page classique avec la bande, d’où le besoin de conserver les images de bande. Voir [Style et mise en page de la Carte](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/template-configuration/apple-tab.md#pass-style-and-layout) pour la mise en page de poster et les autres champs Apple Wallet, et le [guide de la carte de fidélité](https://docs.thewalletcrew.io/guides-design/fr/conception/loyalty-card-template-configuration.md#poster-layout-on-ios-27) pour des conseils sur l’image de poster.

### Dans Google Wallet

Dans Google Wallet, une carte de tampons est une Carte de fidélité. Le **visuel principal** est remplacée par l’image du nombre de tampons actuel. Le nombre n’est pas écrit automatiquement dans le champ de points de Google : pour l’afficher en texte, référencez les variables de tampons dans un champ (voir [Afficher le nombre dans les champs de la Carte](#show-the-count-in-pass-fields)).

## Créer un modèle de carte de tampons

Un modèle de carte de tampons se crée comme n’importe quel autre modèle de Carte, puis se complète avec ses paramètres de tampons et ses images. Pour accorder une récompense lorsque la carte est pleine, créez d’abord le [modèle d’avantage de récompense](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates.md) de la récompense.

{% hint style="info" %}
**Les modèles d’avantage sont en bêta.** Activez **Fonctionnalités bêta** dans le menu du profil, en haut à droite de la console d’administration, pour voir **Engagement → Modèles d’avantage**.
{% endhint %}

{% stepper %}
{% step %}

#### Créer le modèle

Ouvrir **Wallet → Modèles**, cliquez sur **Ajouter**, puis choisissez **Carte à tampons**. Des modèles de départ de carte de tampons prêts à l’emploi sont disponibles pour une boulangerie, un café, une pizzeria, un lavage de voiture, le toilettage pour animaux, un bar à jus, un salon de coiffure et une salle de sport. Ils incluent un compteur de tampons, un comportement d’objectif et des visuels pour chaque nombre de tampons, et constituent une bonne base à adapter.
{% endstep %}

{% step %}

#### Définir l’objectif

Dans l’onglet **Général** remplissez la carte **Tampons** : le nombre de tampons à atteindre pour l’objectif, ce qui se passe lorsqu’il est atteint, et le modèle d’avantage de récompense facultatif.
{% endstep %}

{% step %}

#### Ajouter une image par nombre de tampons

Dans l’onglet **Apple** onglet, ouvrez **Images → Images de tampons** et ajoutez une image de bande pour chaque nombre, ainsi qu’un visuel de poster pour chaque nombre lorsque la mise en page de poster est activée. Dans l’ **Google** onglet, ajoutez une image principale pour chaque nombre.
{% endstep %}

{% step %}

#### Vérifiez l’aperçu et enregistrez

Utilisez l’aperçu à droite pour vérifier la carte à différents nombres, puis cliquez sur **Enregistrer**. Le modèle est validé à l’enregistrement : chaque image requise doit être présente.
{% endstep %}
{% endstepper %}

Pour transformer une carte de fidélité existante en carte de tampons, créez un nouveau modèle de carte de tampons et déplacez-y les cartes, par exemple à l’aide d’une [automatisation](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/automatisation.md) en utilisant **Changer le modèle de Carte**.

### Paramètres de tampons

Le **Tampons** carte dans l’ **Général** onglet définit combien de tampons atteignent l’objectif, et ce que la Carte fait lorsqu’elle y arrive.

<figure><img src="https://2331677975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-6697b60d80e0a4646faa02214e9c8f36a2b57427%2Fstamp-card-stamps-settings-single-frame.png?alt=media" alt="The Stamps card sets the goal, the behavior when the card is full, and the reward benefit template."><figcaption><p>La carte Tampons définit l’objectif, le comportement lorsque la carte est pleine, et le modèle d’avantage de récompense.</p></figcaption></figure>

| Paramètre                             | Description                                                                                                                                                                                                                                                                                     |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tampons pour atteindre l’objectif** | Obligatoire. Entre 1 et 100.                                                                                                                                                                                                                                                                    |
| **Lorsque l’objectif est atteint**    | Ce que fait la carte une fois pleine. Voir les options ci-dessous.                                                                                                                                                                                                                              |
| **Modèle d’avantage de récompense**   | Facultatif. Un [modèle d’avantage de récompense](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates.md) accordé une fois l’objectif atteint, par exemple « Boisson gratuite au choix ». Choisissez **Aucune récompense** pour gérer la récompense ailleurs. |

| Lorsque l’objectif est atteint                             | Ce que voit le détenteur                                                                                                    | Idéal pour                                                                                                  |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Rester pleine, effacer au prochain tampon** (par défaut) | Le tableau complet reste visible. Le tampon suivant efface le tableau et compte comme le premier tampon d’un nouveau cycle. | La plupart des programmes : le détenteur profite d’une carte pleine jusqu’à la prochaine visite.            |
| **Effacer immédiatement**                                  | Le tableau s’efface dès que l’objectif est atteint, donc un tableau plein n’est jamais affiché.                             | Programmes où la récompense est le seul signal dont le détenteur a besoin.                                  |
| **Rester pleine**                                          | La carte refuse les tampons supplémentaires une fois pleine.                                                                | Collections ponctuelles, comme une saison de matchs, où une nouvelle carte est émise pour le cycle suivant. |

L’avantage de récompense est accordé une fois par cycle. Lorsque l’objectif est de nouveau atteint alors que la récompense précédente figure encore sur la Carte, la récompense existante est actualisée plutôt que dupliquée, de sorte qu’un détenteur ne porte qu’une seule récompense active à la fois.

### Images de tampons

Les images de tampons rendent la progression visible : il y a une image pour chaque nombre que la carte peut afficher, de **Vide** (0 tampons) jusqu’à l’objectif. Une carte avec un objectif de 10 nécessite donc 11 images par emplacement d’image. Avec **Effacer immédiatement**, la carte pleine n’est jamais affichée, donc l’image du nombre objectif n’est pas nécessaire.

<figure><img src="https://2331677975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-1bba3d98c9cd89b766f3e1f660984430d5b6da22%2Fstamp-card-apple-stamp-images-single-frame.png?alt=media" alt="Stamp images lists one row per stamp count, from Empty to the goal, each with its own image."><figcaption><p>Les images de tampons listent une ligne par nombre de tampons, de Vide jusqu’à l’objectif, chacune avec sa propre image.</p></figcaption></figure>

| Emplacement                 | Où                                        | Taille         | Obligatoire                                                                             |
| --------------------------- | ----------------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| **Bande Apple**             | Onglet Apple → Images → Images de tampons | 1200 × 462 px  | Pour chaque nombre.                                                                     |
| **Poster Apple**            | Onglet Apple → Images → Images de tampons | 1236 × 1680 px | Pour chaque nombre, lorsque **Utiliser la nouvelle mise en page de poster** est activé. |
| **Image principale Google** | Onglet Google → Images de tampons         | 1032 × 336 px  | Pour chaque nombre.                                                                     |

Les applications Wallet recadrent les images qui ne correspondent pas à ces proportions, donc gardez les tampons à l’écart des bords. Modifier l’objectif ajoute ou supprime des lignes dans l’éditeur ; les lignes remplies conservent leurs images.

{% hint style="info" %}
Une façon simple de produire les images consiste à concevoir une fois la carte vide, puis à exporter une version par nombre avec un tampon supplémentaire rempli à chaque fois. Nommez les fichiers par nombre, par exemple `stamp-0.png` à `stamp-10.png`, pour les téléverser dans l’ordre.
{% endhint %}

### Afficher le nombre dans les champs de la Carte

Le tableau de tampons est accessible à tous les champs du modèle via Liquid, ce qui est utile pour un texte comme « 7 / 10 tampons » ou « 3 de plus pour une boisson gratuite ».

| Variable                 | Valeur                                               |
| ------------------------ | ---------------------------------------------------- |
| `{{ stamps.count }}`     | Tampons collectés. 0 sur une carte jamais tamponnée. |
| `{{ stamps.target }}`    | Tampons nécessaires pour atteindre l’objectif.       |
| `{{ stamps.remaining }}` | Tampons encore nécessaires, jamais en dessous de 0.  |

Par exemple, un champ secondaire avec la valeur `{{ stamps.remaining }} de plus pour une boisson gratuite` tient le détenteur informé sur les deux Wallet. Voir [Mise en forme Liquid](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/templating-engine.md) pour la syntaxe.

## Ajouter des tampons

Les tampons sont ajoutés au comptoir avec Carte Scanner, ou par un système tel qu’un POS ou une plateforme e-commerce via l’API. Chaque mouvement est enregistré avec sa date, sa valeur, la personne qui l’a appliqué et une remarque facultative.

### Depuis la console d’administration

La page de la Carte affiche le nombre d’une carte de tampons à côté de son type, par exemple **7 / 10 tampons**, et l’aperçu dessine le tableau tel que le voit le détenteur.

<figure><img src="https://2331677975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-05e2821965b56b0457928c4ca8a754c6a88449c2%2Fstamp-card-pass-overview-stamp-count.png?alt=media" alt="The pass overview shows the stamp count next to the pass type, and the preview shows the board with five stamps out of eight."><figcaption><p>L’aperçu de la carte affiche le nombre de tampons, et l’aperçu montre le tableau avec cinq tampons sur huit.</p></figcaption></figure>

Le **Tampons** onglet de la Carte contient le **Tableau de tampons**: le nombre par rapport à l’objectif, l’état de la carte (**Collecte** ou objectif atteint), ce qui se passe après l’objectif, et la récompense. En dessous, une grille liste chaque mouvement avec sa **Date**, la **Tampons** ajouté ou retiré, la personne qui l’a appliqué (**Appliqué par**) et les **Remarques**.

<figure><img src="https://2331677975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-8320fd2e2203bf70ba9befd0bb5f9afb45d57a62%2Fstamp-card-pass-stamps-tab.png?alt=media" alt="The Stamps tab shows the stamp board with 5 of 8 stamps and every movement, with who applied it and the remarks."><figcaption><p>Le tableau de tampons montre 5 tampons sur 8 et chaque mouvement, avec la personne qui l’a appliqué et les remarques.</p></figcaption></figure>

**Appliquer des tampons** enregistre un mouvement manuellement, par exemple pour un achat effectué sans la carte ou pour corriger une erreur.

{% stepper %}
{% step %}

#### Ouvrez la boîte de dialogue

Sur la page de la Carte, ouvrez l’ **Tampons** onglet et cliquez sur **Appliquer des tampons**. La boîte de dialogue montre le nombre actuel et le nombre après le mouvement, par exemple « Actuellement 5 sur 10 → 7 ».
{% endstep %}

{% step %}

#### Définissez les tampons à appliquer

Définissez **Tampons à appliquer** : un nombre positif pour tamponner la carte, un nombre négatif pour la corriger. La boîte de dialogue affiche le **Marge restante** avant l’objectif et ne laisse jamais le compteur dépasser l’objectif ni passer sous zéro.
{% endstep %}

{% step %}

#### Ajoutez une remarque et confirmez

Ajouter **Remarques (facultatif)**, comme le numéro du reçu, puis cliquez sur **Appliquer des tampons**. La Carte est mise à jour dans le Wallet du détenteur.
{% endstep %}
{% endstepper %}

<figure><img src="https://2331677975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-e2e8ec424515737a0688f2c909a0f0785652ab26%2Fstamp-card-apply-stamps-dialog.png?alt=media" alt="Applying two stamps with the receipt number as a remark takes the card from 5 to 7 stamps."><figcaption><p>Appliquer deux tampons avec le numéro du reçu comme remarque fait passer la carte de 5 à 7 tampons.</p></figcaption></figure>

### Avec Carte Scanner

Le personnel peut tamponner une carte lorsque le [profil Carte Scanner](https://docs.thewalletcrew.io/guides-scan/fr/scanner/pass-scanner/pass-scanner-profiles.md) exécuté sur l’appareil a **Le personnel peut ajouter des tampons** activé. Chaque appui sur **Ajouter un tampon** applique un tampon. Voir [Cartes de tampons dans Carte Scanner](https://docs.thewalletcrew.io/guides-scan/fr/scanner/pass-scanner.md#stamp-cards).

### Avec l’API

Les intégrations ajoutent des tampons avec l’endpoint de carte de tampons de la Carte.

| Opération                       | Endpoint                                       |
| ------------------------------- | ---------------------------------------------- |
| Lire le tableau de tampons      | `GET /api/{tenantId}/passes/{passId}/stamps`   |
| Ajouter ou corriger des tampons | `POST /api/{tenantId}/cartes/{passId}/tampons` |

Le corps de la requête contient :

| Champ            | Description                                                                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `valeur`         | Obligatoire. Tampons à ajouter (positifs) ou à supprimer en correction (négatifs), entre -100 et 100, jamais 0.                                                                                        |
| `ancienneValeur` | Obligatoire. Le compteur lu en dernier par l'appelant. Si le tableau a changé entre-temps, la requête est refusée et rien n'est appliqué, donc une requête rejouée ne peut jamais tamponner deux fois. |
| `remarques`      | Facultatif. Un commentaire libre, jusqu'à 500 caractères, par exemple le numéro du reçu.                                                                                                               |

La réponse renvoie le nouveau compteur, l'objectif, l'état de la carte (`collecting` ou `goalReached`) et indique si ce mouvement a atteint l'objectif.

La requête est refusée, et rien n'est appliqué, dans les cas suivants :

| Erreur                                       | Cause                                                                       | Correctif                                                   |
| -------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Le nombre de tampons a changé** (409)      | `ancienneValeur` ne correspond plus au compteur.                            | Relisez le tableau, puis réessayez avec le compteur actuel. |
| **Cible de tampons dépassée** (400)          | Les tampons envoyés ne tiennent pas dans l'espace restant avant l'objectif. | Envoyez au plus le nombre de tampons restants.              |
| **Nombre de tampons inférieur à zéro** (400) | Une correction ferait passer le compteur sous zéro.                         | Corrigez d'au plus le compteur actuel.                      |
| **Objectif de tampons atteint** (400)        | La carte est pleine et définie sur **Rester pleine**.                       | Émettez une nouvelle carte pour le tour suivant.            |
| **Pas une carte à tampons** (404)            | La Carte n'utilise pas de modèle de carte à tampons.                        | Vérifiez le modèle de la Carte.                             |

Voir la [référence de l'API de carte à tampons](https://docs.thewalletcrew.io/api-reference/pass-management/stamp-card.md) pour les autorisations et les charges utiles complètes.

## Suivre les cartes à tampons

Chaque mouvement de tampon produit des événements qui peuvent être interrogés avec l' [API Insights](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/insights-api.md) ou envoyés à d'autres outils avec [webhooks](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/webhooks.md).

| Événement            | Quand                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Carte:StampApplied` | Un tampon, ou une correction, est enregistré.                                                                            |
| `Carte:GoalReached`  | Un mouvement atteint l'objectif, une fois par tour.                                                                      |
| `Carte:StampsReset`  | Le tableau est effacé après l'objectif, avec **Rester pleine, effacer au prochain tampon** ou **Effacer immédiatement**. |

Les événements contiennent le compteur, l'objectif, le comportement et, pour l'objectif, le modèle d'avantage de récompense, ce qui permet de mesurer facilement combien de détenteurs terminent une carte et combien de temps cela prend.

## Erreurs de configuration courantes

Le modèle est vérifié à l'enregistrement et par le test de configuration du locataire. Les messages les plus courants sont :

| Message                                                                                   | Correctif                                                                                                             |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Une Carte à tampons doit déclarer sa configuration « stamps ».                            | Renseignez la **Tampons** carte dans l'onglet Général.                                                                |
| La cible de tampons doit être au moins 1, mais vaut N.                                    | Définissez **Tampons pour atteindre l’objectif** entre 1 et 100.                                                      |
| L'image de tampon Apple pour le compteur N n'a pas son image de bande.                    | Ajoutez la bande Apple pour ce compteur.                                                                              |
| L'image de tampon Apple pour le compteur N n'a pas son visuel d'affiche.                  | Ajoutez le visuel d'affiche pour ce compteur, ou désactivez **Utiliser la nouvelle mise en page de poster**.          |
| L'image de tampon Google pour le compteur N n'a pas son image hero.                       | Ajoutez le hero Google pour ce compteur.                                                                              |
| L'image de tampon Apple (ou Google) déclare le compteur N, que la carte n'affiche jamais. | Supprimez l'image supplémentaire, souvent laissée après avoir abaissé l'objectif ou choisi **Effacer immédiatement**. |

## FAQ

<details>

<summary><strong>Le titulaire reçoit-il une notification lorsqu'un tampon est ajouté ?</strong></summary>

Chaque tampon met à jour la Carte dans le Wallet. Pour envoyer un message, par exemple lorsque l'objectif est atteint, utilisez une automatisation ou une notification sur la Carte. L'avantage de récompense lui-même apparaît sur la Carte et sur la page des avantages.

</details>

<details>

<summary><strong>Un thème peut-il changer l'apparence d'une carte à tampons ?</strong></summary>

Oui. Un [thème](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/wallet-pass-themes.md) peut modifier les couleurs et les images d'une carte à tampons, par exemple pour un design saisonnier. [Quelles positions s'appliquent à quelle Carte](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/wallet-pass-themes.md#which-positions-apply-to-which-pass) indique quelles positions s'appliquent aux cartes à tampons. Les thèmes sont en bêta : activez **Fonctionnalités bêta** dans le menu du profil pour voir **Wallet → Thèmes**.

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/guides-design/fr/conception/stamp-card.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
