# Ereignisse Ihrer Kasse empfangen

> 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/kassen-eingang/

POST /v1/entrants/:jeton empfängt die Verkäufe aus Square, Shopify, SumUp, Zettle oder jedem anderen Tool und schreibt den Besuch dem richtigen Kunden gut.

`POST /v1/entrants/:jeton`

Eine Adresse, die Sie in Ihrer Kasse hinterlegen: Bei jedem bezahlten Verkauf ruft die Kasse sie auf, und StampyWallet schreibt den Besuch auf die Karte des Kunden, den es über seine E-Mail-Adresse oder Telefonnummer findet. Sie müssen keinen Schlüssel in die Kasse eintragen: Das Token in der Adresse genügt. Eine unbekannte oder widerrufene Adresse antwortet mit `404`.

## Die Quellen

Jede Adresse wird für eine Quelle unter **Einstellungen › Integrationen** erstellt, mit einem optionalen Signaturschlüssel. StampyWallet liest dann das Format dieser Kasse so, wie es ankommt:

| Quelle | Was zählt | Kunde | Betrag | Referenz |
|---|---|---|---|---|
| `square` | `payment.created` / `payment.updated` mit Status `COMPLETED` | E-Mail des Käufers, oder E-Mail und Telefon des Kunden | Ohne Trinkgeld | Die ID der Zahlung |
| `shopify` | `orders/paid` | E-Mail und Telefon des Kunden oder der Bestellung | Zwischensumme der Bestellung | Die ID der Bestellung |
| `sumup` (Beta) | Transaktion `PAID` oder `SUCCESSFUL` | E-Mail oder Telefon | Betrag der Transaktion | Transaktionscode |
| `zettle` (Beta) | `PurchaseCreated` | E-Mail oder Telefon des Kunden | Betrag des Kaufs | Die ID des Kaufs |
| `generique` | Der Body von [`POST /v1/passages`](https://stampywallet.com/de/docs/api/besuch-erfassen/) | `client` | `montant` | `reference` (optional) |

> **Hinweis :** die Kassenquellen **legen nie einen Kunden an**: Ein Verkauf ohne bekannten Kunden wird ignoriert. Ein Verkauf ohne E-Mail und ohne Telefon, oder ohne Referenz, wird ebenfalls ignoriert. Nur die Quelle `generique` kann einen Kunden anlegen, mit `creer_si_absent: true`.

## Die Signatur

Ist für die Adresse ein Signaturschlüssel hinterlegt, muss jeder Aufruf signiert sein, sonst `401 signature_invalide`. Fügen Sie ihn immer ein, wenn die Kasse einen bereitstellt.

| Quelle | Header | Signatur |
|---|---|---|
| `generique` | `X-Stampy-Signature` | HMAC-SHA256 hexadezimal über den Roh-Body, mit dem Schlüssel der Adresse (`sha256=` davor wird akzeptiert) |
| `square` | `x-square-hmacsha256-signature` | HMAC-SHA256 Base64 über die Benachrichtigungs-URL, gefolgt vom Roh-Body |
| `shopify` | `X-Shopify-Hmac-Sha256` | HMAC-SHA256 Base64 über den Roh-Body |
| `sumup` | `X-Payload-Signature` | HMAC-SHA256 hexadezimal über den Roh-Body |
| `zettle` | `X-iZettle-Signature` | HMAC-SHA256 hexadezimal über `timestamp + "." + payload` |

## Das generische Format

Für ein Skript, ein No-Code-Tool oder eine Kasse ohne bekanntes Format senden Sie denselben Body wie bei [`POST /v1/passages`](https://stampywallet.com/de/docs/api/besuch-erfassen/):

```bash title="curl"
corps='{"client": {"telephone": "+33612345678"}, "montant": 18.9, "reference": "T-2026-1025-0091"}'
signature=$(printf '%s' "$corps" | openssl dgst -sha256 -hmac "$STAMPY_ENTRANT_SECRET" | sed 's/^.* //')

curl https://app.stampywallet.com/v1/entrants/9QkT2vX7pL4mR8sN1bC6dF3gH5jK0wYz \
  -H "Content-Type: application/json" \
  -H "X-Stampy-Signature: $signature" \
  -d "$corps"
```
```js title="Node.js"
const crypto = require('node:crypto');

const corps = JSON.stringify({ client: { telephone: '+33612345678' }, montant: 18.9, reference: 'T-2026-1025-0091' });
const signature = crypto.createHmac('sha256', process.env.STAMPY_ENTRANT_SECRET).update(corps).digest('hex');

await fetch(process.env.STAMPY_ENTRANT_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Stampy-Signature': signature },
  body: corps,
});
```

## Die Antworten

Sobald der Aufruf authentifiziert ist, lautet die Antwort immer `200`, damit die Kasse nichts über Ihren Kundenstamm erfährt:

- `{ "ok": true, "ignore": true }`: Das Ereignis betrifft uns nicht (nicht bezahlt, anderes Thema, ohne Kunde, oder bei einer Kasse ohne Referenz);
- `{ "ok": true }`: in allen anderen Fällen, ob der Kunde existiert oder nicht, ob der Besuch gutgeschrieben oder abgelehnt wurde (zu früh, Betrag zu klein).

Nur eine echte Störung antwortet mit `500`: Die Kasse versucht es erneut, und die Referenz stellt sicher, dass ein neuer Versuch nicht zweimal stempelt. Jede Adresse nimmt 300 Aufrufe pro Minute an.

Die Einstellungen Schritt für Schritt, Kasse für Kasse: [Kasse anbinden](https://stampywallet.com/de/docs/api/kasse-anbinden/).
