# Liste der Ereignisse

> Für KI-Agenten: Das vollständige Verzeichnis der Dokumentation steht unter [llms.txt](https://stampywallet.com/de/docs/llms.txt), die gesamte Dokumentation passt in eine Datei: [llms-full.txt](https://stampywallet.com/de/docs/llms-full.txt). Seite online: https://stampywallet.com/de/docs/api/ereignisse/

Die neun Ereignisse, die die Webhooks von StampyWallet senden, wann sie ausgelöst werden und der genaue Inhalt ihres Felds donnees.

Jedes Ereignis hat dieselbe Hülle (`id`, `type`, `cree_le`, `commerce`, siehe [Webhooks](https://stampywallet.com/de/docs/api/webhooks/#requete)). Nur `donnees` ändert sich; unten wird nur dieses Feld gezeigt. Die Ereignisse werden von der Theke genauso ausgelöst wie von der API: Ein Besuch, der gescannt oder über [`POST /v1/passages`](https://stampywallet.com/de/docs/api/besuch-erfassen/) erfasst wird, erzeugt dasselbe `passage.cree`.

| Ereignis | Gesendet, wenn |
|---|---|
| `client.cree` | Ein Kunde tritt dem Programm bei (seine Karte wird erstellt) |
| `carte.ajoutee` | Der Kunde speichert seine Karte in Apple Wallet oder Google Wallet |
| `passage.cree` | Ein Besuch wird erfasst: ein oder mehrere Stempel, oder Punkte |
| `passage.annule` | Der letzte Besuch eines Kunden wird storniert |
| `recompense.atteinte` | Ein Besuch überschreitet eine Stufe: Eine Prämie ist fällig (eine pro überschrittener Stufe) |
| `recompense.offerte` | Die Prämie wird dem Kunden übergeben |
| `recompense.annulee` | Die Übergabe einer Prämie wird storniert: Sie ist wieder fällig |
| `carte_cadeau.vendue` | Ein Gutschein wird verkauft |
| `forfait.vendu` | Ein Prepaid-Paket wird verkauft |

> **Hinweis :** `carte.ajoutee` gilt für Apple Wallet und Google Wallet: `donnees.carte.wallet` ist `apple` oder `google`. Bei Apple wird das Ereignis für jedes neue Gerät ausgelöst (ein iPhone und dann eine Uhr ergeben zwei). Das Entfernen der Karte löst nichts aus.

## client.cree

```json title="donnees"
{
  "client": {
    "id": "3374a06e-9608-4376-91cb-1a3fb6721b04",
    "prenom": "Camille",
    "cree_le": "2026-10-22T05:52:45.664Z"
  }
}
```

`telephone` und `email` erscheinen nur, wenn der Kunde sie angegeben hat. `prenom` kann `null` sein.

## carte.ajoutee

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "carte": { "wallet": "apple" }
}
```

## passage.cree

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "passage": {
    "id": "226fdea1-ba59-49fb-93e6-60a14a765134",
    "quantite": 1,
    "montant": null,
    "devise": "EUR",
    "reference": "caisse-1",
    "source": "scan",
    "piste": "normal",
    "tampons": 1,
    "objectif": 2
  }
}
```

- `quantite`: was der Besuch wert ist (Stempel, oder Punkte im Punktemodus).
- `montant`: der Betrag des Bons in Cent, falls er eingegeben wurde, sonst `null`.
- `reference`: die Vorgangskennung, die der Aufrufer gesendet hat (die Referenz der API oder die der Theke), sonst `null`.
- `source`: `scan`, `manuel`, `api`…
- `piste`: `normal`, oder `premium` für den zweiten Zähler.
- `tampons` (oder `points` im Punktemodus) und `objectif`: der Zählerstand **nach** dem Besuch. Ein Besuch, der die Karte vollmacht, liefert den Stand der nächsten Karte (oft `0`); die Prämie kommt in einem eigenen `recompense.atteinte`.

## passage.annule

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "passage": {
    "id": "d8f62d77-88a6-44ef-a0c3-2a7d5066b90a",
    "quantite": 1,
    "source": "scan",
    "piste": "normal",
    "tampons": 0,
    "objectif": 2
  },
  "recompenses_retirees": 0,
  "motif": "doppelt gescannt"
}
```

`passage.id` ist die des ursprünglichen `passage.cree`, und der Zählerstand der nach der Stornierung. `recompenses_retirees`: die Prämien, die dieser Besuch freigeschaltet hatte und die mit ihm verschwinden. `motif`: der an der Theke eingegebene Grund, oder `null`.

## recompense.atteinte

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Ein Kaffee gratis",
    "palier": 2,
    "piste": "normal",
    "expire_le": null
  },
  "passage_id": "8bfbdd5e-eff4-4a3b-94fe-1557ec6edce6"
}
```

Ein Ereignis pro überschrittener Stufe. `expire_le` ist `null`, wenn die Prämien des Geschäfts nicht verfallen.

## recompense.offerte

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Ein Kaffee gratis",
    "piste": "normal",
    "offerte_le": "2026-10-22T05:54:51.790Z"
  }
}
```

## recompense.annulee

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Ein Kaffee gratis",
    "piste": "normal"
  },
  "motif": "falsche Karte"
}
```

## carte_cadeau.vendue

```json title="donnees"
{
  "client": null,
  "carte_cadeau": {
    "id": "ac7e56a5-3c00-492f-971a-21ca7d675fd6",
    "code": "EJ9Y-7FYN",
    "sorte": "montant",
    "produit": null,
    "montant": 2500,
    "devise": "EUR",
    "pour": "Lucie",
    "de": "Marc",
    "canal": "comptoir",
    "expire_le": "2027-04-22T05:54:51.879Z"
  }
}
```

`sorte` ist `montant` oder `produit` (dann enthält `produit` den Namen und `montant` den Preis). Hier 2500 Cent: 25 €.

> **Achtung :** `code` ist der Code des Gutscheins, der in seinem QR-Code steckt: Er reicht aus, um ihn an der Theke zu belasten. Behandeln Sie ihn wie ein Geheimnis: Schreiben Sie ihn weder in eine geteilte Tabelle noch in Logs.

## forfait.vendu

```json title="donnees"
{
  "client": null,
  "forfait": {
    "id": "0ec29323-ed13-4e6b-9595-963601290eac",
    "code": "XFF2-WTW9",
    "nom": "10 Kaffee",
    "unites": 10,
    "prix": 3000,
    "devise": "EUR",
    "titulaire": "Paul",
    "canal": "comptoir",
    "expire_le": "2027-04-22T05:54:51.891Z"
  }
}
```

`titulaire`: der beim Verkauf eingetragene Name, oder `null`. `expire_le` ist `null` bei einem Prepaid-Paket ohne Ablaufdatum. Wie bei einem Gutschein ist `code` geheim zu halten.

> **Hinweis :** die personenbezogenen Daten beschränken sich auf das, was der Kunde bei der Anmeldung angegeben hat. Sobald Sie sie erhalten haben, liegen sie in Ihrer Verantwortung: Bewahren Sie sie nur so lange auf wie nötig.
