# Die StampyWallet-API

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

Erfassen Sie Besuche, legen Sie Kunden an und empfangen Sie die Ereignisse Ihrer Stempelkarte aus Ihrer Kasse, Ihrer Website oder einem No-Code-Tool.

Die API verbindet StampyWallet mit dem Rest Ihres Geschäfts. Sie funktioniert in beide Richtungen:

- **Zu StampyWallet**: Ihre Kasse, Ihre Website oder Ihre Buchungssoftware erfasst einen Besuch, legt einen Kunden an oder löst eine Prämie ein, ohne Scan an der Theke.
- **Von StampyWallet**: Bei jedem Besuch, jeder neuen Karte oder Prämie ruft StampyWallet eine Adresse Ihrer Wahl auf (einen [Webhook](https://stampywallet.com/de/docs/api/webhooks/)). So füllen Sie eine Tabelle, ein CRM oder ein Zapier-Szenario.

> **Bevor Sie anfangen :** die API, die Eingangsadressen für Kassen ([Kasse anbinden](https://stampywallet.com/de/docs/api/kasse-anbinden/)) und die Webhooks sind im Tarif **Wachstum** enthalten (40 € zzgl. MwSt. pro Monat) und während der kostenlosen Testphase freigeschaltet. Im Tarif Essential antworten die Aufrufe mit `403` und dem Code `formule_requise`.

> **Achtung :** die API ist in der **Beta**. Die hier beschriebenen Routen und Felder entsprechen der Implementierung; vor der stabilen Version können neue Felder hinzukommen: Ignorieren Sie die, die Sie nicht kennen. Änderungen werden in den [Neuigkeiten](https://stampywallet.com/de/neuigkeiten/) angekündigt.

## Die Basisadresse

Alle Routen laufen über HTTPS, im JSON-Format (Feldnamen auf Französisch, in snake_case), unter:

```text title="Basisadresse"
https://app.stampywallet.com/v1
```

IDs sind UUIDs; Beträge sind in der Währung des Geschäfts angegeben, in Einheiten (`12.5` für 12,50 €).

## Ein erster Aufruf

Erstellen Sie einen Schlüssel unter **Einstellungen › Integrationen** (siehe [Authentifizierung](https://stampywallet.com/de/docs/api/authentifizierung/)) und rufen Sie dann die Daten Ihres Geschäfts ab:

```bash title="curl"
curl https://app.stampywallet.com/v1/commerce \
  -H "Authorization: Bearer sw_live_votre_cle"
```
```js title="Node.js"
const reponse = await fetch('https://app.stampywallet.com/v1/commerce', {
  headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` },
});
console.log(await reponse.json());
```
```python title="Python"
import os, requests

reponse = requests.get(
    "https://app.stampywallet.com/v1/commerce",
    headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
)
print(reponse.json())
```

## Was die API kann

| Route | Zweck |
|---|---|
| `GET /v1/commerce` | [Die Daten des Geschäfts abrufen](https://stampywallet.com/de/docs/api/geschaeft/) und die Regeln der Karte |
| `POST /v1/clients` | [Einen Kunden anlegen](https://stampywallet.com/de/docs/api/kunden-anlegen/) und den Link zu seiner Karte erhalten |
| `GET /v1/clients` | [Einen Kunden finden](https://stampywallet.com/de/docs/api/kunden-finden/) über Telefon, E-Mail oder Karte |
| `GET /v1/clients/:id` | [Einen Kunden abrufen](https://stampywallet.com/de/docs/api/kunden-abrufen/) und den Stand seiner Karte |
| `POST /v1/passages` | [Einen Besuch erfassen](https://stampywallet.com/de/docs/api/besuch-erfassen/): einen Stempel, oder Punkte je nach Betrag |
| `DELETE /v1/passages/:id` | [Einen Besuch stornieren](https://stampywallet.com/de/docs/api/besuch-stornieren/) |
| `POST /v1/recompenses` | [Eine verdiente Prämie einlösen](https://stampywallet.com/de/docs/api/praemie-einloesen/) |
| `POST /v1/entrants/:jeton` | [Die Verkäufe Ihrer Kasse empfangen](https://stampywallet.com/de/docs/api/kassen-eingang/) (Square, Shopify, SumUp, Zettle oder das generische Format) |

Und in die andere Richtung die [ausgehenden Webhooks](https://stampywallet.com/de/docs/api/webhooks/): neun signierte [Ereignisse](https://stampywallet.com/de/docs/api/ereignisse/).

> **Tipp :** kein Entwickler zur Hand? Die Seite [Kasse anbinden](https://stampywallet.com/de/docs/api/kasse-anbinden/) erklärt die Einstellungen Schritt für Schritt für Square, Shopify, SumUp und Zettle sowie für Zapier, Make und n8n.

## Und MCP?

Die API ist für Software gedacht: eine Kasse, eine Website, ein Skript. Um Ihr Geschäft **im Gespräch** zu steuern, aus Claude, ChatGPT oder Cursor heraus, nutzen Sie besser den [MCP-Server](https://stampywallet.com/de/docs/mcp/verbinden/): Er braucht keinen Schlüssel, Sie verbinden nur Ihr Konto.

## Häufige Fragen

**Was kostet die API?**
Die API, die Eingangsadressen für Kassen und die Webhooks sind im Tarif Wachstum enthalten, für 40 € zzgl. MwSt. pro Monat, und während der 30 Tage kostenlosen Testphase freigeschaltet. Im Tarif Essential antworten die Aufrufe mit `403`.

**Brauche ich einen Entwickler, um meine Kasse anzubinden?**
Nicht für Square, Shopify, SumUp, Zettle, Zapier, Make oder n8n: Die Seite [Kasse anbinden](https://stampywallet.com/de/docs/api/kasse-anbinden/) erklärt die Einstellungen Schritt für Schritt. Wer die API aus eigener Software aufrufen will, braucht dagegen jemanden, der Code schreibt.

**Gibt es ein Aufruflimit?**
Ja: 120 Anfragen pro Minute und Schlüssel. Darüber hinaus lautet die Antwort `429` mit dem Header `Retry-After`.

**Gilt ein Schlüssel für mehrere Filialen?**
Nein. Ein Schlüssel gibt nur Zugriff auf das Geschäft, in dem er erstellt wurde: Erstellen Sie in jeder Filiale einen eigenen Schlüssel.

**Wie vermeide ich einen doppelten Stempel, wenn meine Kasse es erneut versucht?**
Geben Sie jedem Besuch eine `reference`, zum Beispiel die Bonnummer, und senden Sie bei jedem `POST` einen Header `Idempotency-Key`: Ein erneuter Versuch stempelt nicht zweimal.
