# Besuch erfassen

> 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/besuch-erfassen/

POST /v1/passages fügt der Karte eines Kunden aus Ihrer Kasse einen Stempel oder Punkte hinzu und meldet, ob eine Prämie erreicht ist.

`POST /v1/passages`

Das Gegenstück zu einem Scan an der Theke, gesendet von Ihrer Kasse: ein Stempel (oder mehrere) oder Punkte. Es gelten dieselben Regeln und Grenzen wie an der Theke, die Karte des Kunden aktualisiert sich in seinem Wallet, und der Besuch zählt wie jeder andere (Stammkunden, Erinnerungen, Bitte um Bewertung).

**Body (JSON)**

- `client` (object, erforderlich) : Wer den Besuch erhält: **eines** von `id`, `carte` (der Code der Karte), `email` oder `telephone`.
- `montant` (number, optional) : Betrag des Bons, in Einheiten (`12.5` für 12,50 €). Hat das Geschäft eine Regel „10 € = 1 Stempel“, hat der Betrag Vorrang vor `quantite`; im Punktemodus wird er mit der Regel „Punkte pro Euro“ des Geschäfts umgerechnet.
- `quantite` (integer, optional) : Modi Stempel und Stufen: Anzahl der Stempel, standardmäßig 1, höchstens 50.
- `points` (integer, optional) : Punktemodus ohne Betrag: die zu vergebenden Punkte. Standardmäßig der Wert des Geschäfts.
- `reference` (string, optional) : Die Bonnummer. Eine Referenz stempelt pro Geschäft nur einmal.
- `creer_si_absent` (boolean, optional) : `true`: Ein unbekannter Kunde, angegeben über `email` oder `telephone`, wird angelegt (mit `prenom` und `nom`, wenn sie in `client` stehen). Standardmäßig `false`.
- `conditions_acceptees` (boolean, optional) : Wenn das Geschäft die Zustimmung zu seinen Bedingungen verlangt und `creer_si_absent` den Kunden anlegt (in `client` oder auf oberster Ebene).

## Beispiel

```bash title="curl"
curl https://app.stampywallet.com/v1/passages \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "client": { "telephone": "+33612345678", "prenom": "Léa" },
    "montant": 12.5,
    "reference": "TICKET-4512",
    "creer_si_absent": true
  }'
```
```js title="Node.js"
const r = await fetch('https://app.stampywallet.com/v1/passages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.STAMPY_CLE}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    client: { telephone: '+33612345678', prenom: 'Léa' },
    montant: 12.5,
    reference: 'TICKET-4512',
    creer_si_absent: true,
  }),
});
const resultat = await r.json();
if (resultat.recompense_atteinte) console.log('Prämie fällig!');
```
```python title="Python"
import os, requests

r = requests.post(
    "https://app.stampywallet.com/v1/passages",
    headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
    json={"client": {"telephone": "+33612345678", "prenom": "Léa"},
          "montant": 12.5, "reference": "TICKET-4512", "creer_si_absent": True},
)
print(r.json()["recompense_atteinte"])
```

## Antwort

```json title="201 Created"
{
  "passage": {
    "id": "226fdea1-ba59-49fb-93e6-60a14a765134",
    "client_id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
    "valeur": 1,
    "montant": 12.5,
    "reference": "TICKET-4512",
    "cree_le": "2026-10-22T09:20:00.000Z"
  },
  "rejoue": false,
  "client_cree": false,
  "recompense_atteinte": true,
  "recompenses_gagnees": 1,
  "plafonne": false,
  "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 0, "objectif": 10 } }
}
```

| Feld | Bedeutung |
|---|---|
| `passage.valeur` | Die vergebenen Stempel oder Punkte |
| `passage.montant` | Der gespeicherte Betrag, oder `null` |
| `rejoue` | `true`, wenn die `reference` schon verwendet wurde: Die Antwort ist dann `200` und liefert den ursprünglichen Besuch, ohne ein zweites Mal zu stempeln |
| `client_cree` | `true`, wenn `creer_si_absent` den Kunden angelegt hat |
| `recompense_atteinte`, `recompenses_gagnees` | Dieser Besuch bringt eine Prämie (oder mehrere): [einzulösen](https://stampywallet.com/de/docs/api/praemie-einloesen/), wenn der Kunde sie abholt |
| `plafonne` | `true`, wenn der Wert auf die Obergrenze der Theke gekürzt wurde |
| `client` | [Das Kundenobjekt](https://stampywallet.com/de/docs/api/kunden-abrufen/#objet) nach dem Besuch |

## Ablehnungen

| Status | `code` | Wann |
|---|---|---|
| `404` | `client_introuvable` | Kein passender Kunde, und `creer_si_absent` steht nicht auf `true` |
| `409` | `trop_tot` | Ein Besuch desselben Kunden liegt kürzer zurück als die Sperrfrist gegen Doppelbesuche des Geschäfts (standardmäßig 90 Sekunden) |
| `422` | `montant_insuffisant` | Der Betrag reicht nicht für einen Stempel (oder einen Punkt) |
| `422` | `conditions_requises` | Der Kunde würde angelegt, aber die Bedingungen des Geschäfts sind nicht akzeptiert |

> **Achtung :** geben Sie immer eine `reference` an (die Bonnummer): So vergibt eine Kasse, die es nach einem Verbindungsabbruch erneut versucht, keine zwei Stempel. Eine Referenz, deren Besuch storniert wurde, wird nicht erneut vergeben.
