# LEVIAPAY-API — Integrationsanleitung

Diese Anleitung ist eigenständig: Sie kann direkt in euer Repository gelegt und
eurem KI-Assistenten (z. B. Claude) als Kontext gegeben werden. Alle Beispiele
verwenden die fiktive **Muster GmbH** mit dem Abo **„Muster Professional"**:
**299 €/Monat**, **3 000 Minuten inkl.** (danach 0,15 €/Minute), **300 SMS
inkl.** (danach 0,12 €/SMS), optionales Add-on **„KI-Bewertungskommentare"**
(Slug `ki-kommentare`) für **49 €/Monat**.

## 1. Überblick

- **Bezahlmodal (Browser):** Ein `<script>` + ein Button — LEVIAPAY öffnet ein
  gehostetes Bezahlfenster (Karte via Stripe). Kein PCI-Aufwand bei euch.
- **Server-API (dieses Dokument, §4):** Abos abfragen und **Verbrauch melden**
  (Minuten, SMS, …) mit einem geheimen `lp_sk`-Schlüssel.
- **Vorbereitete Zahl-Links (§4.13):** Ihr legt serverseitig einen Link an, in
  dem **Name, E-Mail, Firma, Anschrift und USt-IdNr.** des Käufers schon
  stehen. Der Käufer öffnet den Link und sieht das Bezahlfenster bereits
  ausgefüllt.
- **Test vs. Live:** identische API; die Umgebung folgt dem Schlüssel
  (`lp_sk_test_…` / `lp_sk_live_…` bzw. `lp_pub_test_…` / `lp_pub_live_…`).
  Testkarte: `4242 4242 4242 4242` (beliebiges zukünftiges Datum, beliebiger
  CVC). Live-Schlüssel stehen nach Freigabe eures Kontos zur Verfügung.
- **Beträge** sind überall Ganzzahlen in **Cent** (`29900` = 299 €).
  Zeiträume (`currentPeriodStart`/`currentPeriodEnd`, `periodStart`/`periodEnd`)
  sind **Unix-Sekunden**; `createdAt` ist ISO-8601.

## 2. Bezahlmodal einbetten (Quickstart)

```html
<script src="https://js.leviapay.com/v1/modal.js"></script>

<button
  data-leviapay
  data-key="lp_pub_test_DEIN_SCHLUESSEL"
  data-product="PRODUKT_ID"
  data-ref="kunde-42"
  data-label="Muster Professional abonnieren">
  Muster Professional abonnieren
</button>
```

- `data-key` (Pflicht): euer **öffentlicher** Schlüssel (`lp_pub_…`) aus dem
  Dashboard — niemals der geheime `lp_sk_…`-Schlüssel.
- `data-product` (Pflicht): die Produkt-ID (aus dem Dashboard oder
  `GET /v1/products`, §4.8).
- `data-ref` (optional, ≤128 Zeichen): eure eigene Referenz (z. B. Kunden-ID).
  Sie erscheint als `merchantRef` in der API und erlaubt die Zuordnung
  Abo ↔ euer Kunde.
- `data-label` (optional): Beschriftung im Bezahlfenster.
- `data-voucher` (optional): Gutscheincode, der im Bezahlfenster **vorausgefüllt
  und sofort geprüft** wird — der Käufer sieht den Rabatt direkt und klickt nur
  noch auf Bezahlen.
- `data-voucher-param` (optional): Name eines Query-Parameters **eurer eigenen
  Seite**, aus dem der Code gelesen wird. Damit trägt ein einziger geteilter
  Link den Rabatt bis in die Bezahlung:

  ```html
  <!-- Link an den Kunden: https://eure-seite.de/preise?code=SOMMER25 -->
  <button data-leviapay data-key="lp_pub_…" data-product="PRODUKT_ID"
          data-voucher-param="code">Jetzt buchen</button>
  ```

  Ein ungültiger oder abgelaufener Code blockiert den Kauf nicht — das Feld
  zeigt den Hinweis, der Kunde kann normal weiter bezahlen.

  Seit dem 28.10.2026 hält ein geöffnetes Bezahlfenster den Code für **10
  Minuten** fest: ein Einmalcode gilt dann in genau einem Bezahlvorgang, und
  bei einer Kampagne mit Höchstzahl zählen laufende Vorgänge gegen die
  Höchstzahl mit. Wer parallel ein zweites Fenster mit demselben Code öffnet,
  liest „Dieser Gutschein wird gerade in einem anderen Bezahlvorgang
  verwendet." Ein abgebrochener oder gescheiterter Vorgang gibt den Code
  sofort wieder frei, ein einfach zugeklapptes Fenster nach Ablauf der 10
  Minuten.

> **Firmendaten des Käufers vorbelegen:** Über den Button bzw.
> `LeviaPay.open()` geht das **nicht** — alles, was im Browser steht, kann
> jeder Besucher lesen und ändern, und Kundendaten gehören nicht in euren
> Seitenquelltext. Dafür gibt es den **vorbereiteten Zahl-Link**: euer Server
> legt ihn mit dem geheimen Schlüssel an (§4.13), ihr gebt dem Käufer die
> zurückgegebene `url` (Mail, Kundenportal, Weiterleitung). Ohne
> Programmierung geht dasselbe im Dashboard unter **Bezahlmodal → Produkte → Zahl-Links**.

Buttons, die erst nach dem Laden ins DOM kommen (SPA), meldet ihr mit
`LeviaPay.scan()` nach — oder ihr öffnet das Modal programmatisch inkl.
Erfassung der Subscription-ID:

```html
<script>
  LeviaPay.open({
    key: "lp_pub_test_DEIN_SCHLUESSEL",
    product: "PRODUKT_ID",
    ref: "kunde-42",
    label: "Muster Professional abonnieren", // optional
    voucher: "SOMMER25",                     // optional, s. data-voucher
    onSuccess: function (d) {
      // d = { type: "leviapay:success", subscriptionId: "sub_…" | null,
      //       paymentIntentId: "pi_…" | null, amountCents: 29900 }
      // d.subscriptionId hier speichern — ihr braucht sie zum Verbrauch-
      // Melden. Alternativ später über GET /v1/subscriptions?ref=… (§4.3).
      fetch("/api/leviapay-abo-verknuepfen", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ subscriptionId: d.subscriptionId, kunde: "kunde-42" }),
      });
    },
  });
</script>
```

Im Bezahlfenster sieht der Käufer die vollständige Preisaufstellung
(Grundpreis, Inklusivmengen, Preis je weitere Einheit, wählbare Add-ons,
Testphase) und bestätigt mit „Kostenpflichtig abonnieren". Bei Abos mit
Testphase ist `paymentIntentId` im Erfolgs-Payload `null` (es wird erst zum
Ende der Testphase abgebucht).

> **Einbetten nur über `modal.js`.** Das Bezahlfenster prüft seit dem
> 28.10.2026 selbst, von welcher Seite es eingebettet wurde, und vergleicht
> das mit euren freigegebenen Domains. Dafür braucht es die Angabe des
> Browsers (`location.ancestorOrigins` bzw. der Referrer) — `modal.js` setzt
> am iframe die passende Referrer-Richtlinie und liefert sie damit zuverlässig
> mit. Ein **selbst gebautes iframe** auf `checkout.html` kann daran
> scheitern: wer `referrerpolicy="no-referrer"` setzt oder die Adresse direkt
> aufruft, bekommt „Diese Zahlung kann auf dieser Seite nicht gestartet
> werden." Baut das iframe nicht selbst — `modal.js` ist der unterstützte und
> stabile Weg (`LeviaPay.open()` für dynamische Fälle).

## 3. API-Schlüssel

- Erstellen: LEVIAPAY-Dashboard → **Bezahlmodal → Einrichtung → Geheime
  API-Schlüssel (Server)** → „Schlüssel erstellen" (Bezeichnung vergeben,
  Umgebung wählen). Der Schlüssel wird **nur einmal** angezeigt; danach ist im
  Dashboard nur noch die Bezeichnung + die letzten 4 Zeichen sichtbar.
- Aufbewahrung: als Umgebungsvariable (`LEVIAPAY_API_KEY`), niemals im
  Frontend, niemals ins Repository committen. Bei Verdacht auf Leak: im
  Dashboard widerrufen (sofort wirksam) und neu erstellen — mehrere aktive
  Schlüssel parallel sind für die Rotation erlaubt.
- `lp_pub_…` (öffentlich, nur fürs Bezahlmodal im Browser) und `lp_sk_…`
  (geheim, nur für die Server-API) sind getrennte Schlüssel und nicht
  austauschbar.

## 4. Server-API

Basis-URL: `https://us-central1-leviapay-3fd2b.cloudfunctions.net/api`
Auth: `Authorization: Bearer lp_sk_…` · Alle Antworten JSON.

**Fehlerformat** (immer gleich):

```json
{ "error": { "code": "NOT_FOUND", "message": "No such subscription" } }
```

| Code | HTTP | Bedeutung |
|---|---|---|
| `INVALID_REQUEST` | 400 | Feld fehlt/ungültig, unbekannte Komponente oder gekündigtes Abo (Details in `message`; bei Zahl-Links zusätzlich maschinenlesbar in `reason`, §4.13) |
| `UNAUTHORIZED` | 401 | Schlüssel fehlt, unbekannt, widerrufen oder API nicht freigeschaltet |
| `ACCOUNT_SUSPENDED` | 403 | Konto vorübergehend gesperrt |
| `LIVE_DISABLED` | 403 | Live-Modus ist plattformseitig deaktiviert (gilt nur für `lp_sk_live_`-Schlüssel) |
| `NOT_FOUND` | 404 | Unbekannter Endpunkt oder fremde/unbekannte ID |
| `RATE_LIMITED` | 429 | Zu viele Anfragen (siehe Limits unten) |
| `INTERNAL` | 500 | Serverfehler — mit gleichem `idempotencyKey` wiederholen |

**Rate-Limits** (je Schlüssel):

| Endpunkte | Limit |
|---|---|
| `POST /v1/usage` | 600/min |
| `POST /v1/checkout-links`, `POST /v1/checkout-links/{id}/revoke` (zusammen) | 30/min |
| `POST /v1/subscriptions/{id}/billing-email` | 20/min |
| `POST /v1/invoices/{id}/resend` | 10/min |
| `GET /v1/invoices/{id}/pdf` | 60/min |
| alle übrigen `GET`-Endpunkte | 120/min |

### 4.1 `POST /v1/usage` — Verbrauch melden

```bash
BASE="https://us-central1-leviapay-3fd2b.cloudfunctions.net/api"

curl -X POST "$BASE/v1/usage" \
  -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_ABC123",
    "component": "minuten",
    "quantity": 42,
    "timestamp": "2026-07-08T14:00:00Z",
    "idempotencyKey": "call-8842-minutes"
  }'
```

Antwort: `{ "received": true, "duplicate": false }` — bei Wiederholung mit dem
gleichen `idempotencyKey`: `{ "received": true, "duplicate": true }` (keine
Doppelabrechnung).

Regeln:

- `component`: Schlüssel aus dem Abo-Snapshot (z. B. `minuten`, `sms`);
  Kleinbuchstaben-Slug `a-z 0-9 -`, max. 40 Zeichen. Unbekannte Komponente →
  `INVALID_REQUEST`.
- `quantity`: ganzzahlig, 1 – 1 000 000.
- `timestamp`: optional, ISO-8601 (Default: jetzt), maximal ±24 h von jetzt.
- `idempotencyKey`: **Pflicht**, 1 – 64 Zeichen, pro Meldung eindeutig
  (z. B. eure Call-/Job-ID).
- Gekündigte Abos (`status: "canceled"`) akzeptieren keinen Verbrauch mehr
  (`INVALID_REQUEST`).

```js
// Node ≥18 (fetch eingebaut) — leviapay.js
const BASE = "https://us-central1-leviapay-3fd2b.cloudfunctions.net/api";

export async function reportUsage(subscriptionId, component, quantity, idempotencyKey) {
  const res = await fetch(`${BASE}/v1/usage`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LEVIAPAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ subscriptionId, component, quantity, idempotencyKey }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  return data; // { received: true, duplicate: boolean }
}
```

### 4.2 `GET /v1/subscriptions/{id}` — Abo abfragen

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" "$BASE/v1/subscriptions/sub_ABC123"
```

```json
{
  "id": "sub_ABC123",
  "status": "active",
  "productId": "PRODUKT_ID",
  "productName": "Muster Professional",
  "merchantRef": "kunde-42",
  "interval": "month",
  "baseAmountCents": 29900,
  "addons": ["ki-kommentare"],
  "components": [
    { "key": "minuten", "name": "Minuten", "includedQty": 3000, "overageCentsPerUnit": 15 },
    { "key": "sms", "name": "SMS", "includedQty": 300, "overageCentsPerUnit": 12 }
  ],
  "currentPeriodStart": 1751932800,
  "currentPeriodEnd": 1754611200,
  "cancelAtPeriodEnd": false,
  "createdAt": "2026-07-08T09:00:00.000Z",
  "env": "test"
}
```

- `status`: `active` | `trialing` | `past_due` | `canceled` | `incomplete`.
- `interval`: `week` | `month` | `quarter` | `year`.
- `addons`: die Slugs der beim Abschluss **gewählten** Add-ons.
- `cancelAtPeriodEnd: true` = Kündigung zum Periodenende vorgemerkt; das Abo
  läuft bis `currentPeriodEnd` weiter.
- `components` ist der **Snapshot bei Abschluss** — spätere Preisänderungen am
  Produkt betreffen nur Neuabschlüsse.
- Käufer-E-Mails liefert die API grundsätzlich nicht (Datenschutz; im
  Dashboard sichtbar).

### 4.3 `GET /v1/subscriptions` — Liste/Filter

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  "$BASE/v1/subscriptions?ref=kunde-42&status=active&limit=20"
```

Antwort: `{ "data": [ …Objekte wie in 4.2… ], "has_more": false }`.

- `ref` (optional): exakter Match auf `merchantRef`.
- `status` (optional): einer der Werte aus 4.2.
- `limit` (optional): 1 – 100, Default 20.
- Paginierung: solange `has_more: true`, die **letzte `id` der Seite** als
  `starting_after` mitgeben.

```js
export async function findSubscriptionByRef(ref) {
  const res = await fetch(
    `${BASE}/v1/subscriptions?ref=${encodeURIComponent(ref)}&status=active`,
    { headers: { Authorization: `Bearer ${process.env.LEVIAPAY_API_KEY}` } },
  );
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  return data.data[0] || null;
}
```

### 4.4 `GET /v1/subscriptions/{id}/usage` — Verbrauch abfragen

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" "$BASE/v1/subscriptions/sub_ABC123/usage"
```

```json
{
  "subscriptionId": "sub_ABC123",
  "components": [
    { "key": "minuten", "name": "Minuten", "usedQty": 3100, "includedQty": 3000,
      "overageQty": 100, "overageCentsPerUnit": 15,
      "periodStart": 1751932800, "periodEnd": 1754611200 },
    { "key": "sms", "name": "SMS", "usedQty": 250, "includedQty": 300,
      "overageQty": 0, "overageCentsPerUnit": 12,
      "periodStart": 1751932800, "periodEnd": 1754611200 }
  ]
}
```

`usedQty` ist der gemeldete Verbrauch im **laufenden Abrechnungszeitraum**;
`overageQty = max(0, usedQty − includedQty)`. Antworten sind bis zu **60 s**
zwischengespeichert — eben gemeldeter Verbrauch erscheint also ggf. mit kurzer
Verzögerung.

### 4.5 `GET /v1/invoices` — Rechnungen eines Abos

Für Kundenportale: die Abrechnungshistorie eines Abos. `subscription` ist
**Pflicht** — jede Rechnungsabfrage hängt an einem Abo, das zu deinem
Schlüssel gehört.

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  "$BASE/v1/invoices?subscription=sub_ABC123&limit=12"
```

```json
{
  "data": [
    {
      "id": "in_1PxY…",
      "number": "A5F2-0001",
      "status": "paid",
      "currency": "eur",
      "amountDueCents": 4900,
      "amountPaidCents": 4900,
      "subtotalCents": 4118,
      "taxCents": 782,
      "totalCents": 4900,
      "created": "2026-08-01T00:00:00.000Z",
      "paidAt": "2026-08-01T00:01:00.000Z",
      "periodStart": "2026-08-01T00:00:00.000Z",
      "periodEnd": "2026-09-01T00:00:00.000Z",
      "subscriptionId": "sub_ABC123",
      "pdfUrl": "/v1/invoices/in_1PxY…/pdf",
      "lines": [
        { "description": "Pro-Paket", "quantity": 1, "amountCents": 4900,
          "periodStart": "2026-08-01T00:00:00.000Z",
          "periodEnd": "2026-09-01T00:00:00.000Z" }
      ]
    }
  ],
  "has_more": false
}
```

Parameter: `subscription` (Pflicht), `limit` (1–100, Standard 20),
`starting_after` (Rechnungs-ID der vorherigen Seite).

Nur **Abo-Rechnungen**. Einmalzahlungen erzeugen in Stripe keine Rechnung und
tauchen hier deshalb nicht auf.

**Erstattungen und Stornorechnungen:** Seit dem 01.10.2026 erzeugt jede
Erstattung einer Rechnung automatisch eine **Stornorechnung** (Stripe Credit
Note, mit anteiliger Umsatzsteuer) — auch Teilerstattungen und Erstattungen,
die direkt in Stripe ausgelöst werden. Sie stehen im Dashboard als PDF neben
der Rechnung; über die API sind sie derzeit nicht abrufbar. `amountPaidCents`
einer Rechnung bleibt der ursprünglich gezahlte Betrag.

### 4.6 `GET /v1/invoices/{id}` — einzelne Rechnung

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" "$BASE/v1/invoices/in_1PxY…"
```

Antwort: ein Objekt in der Form oben. Rechnungen, deren Abo nicht zu deinem
Schlüssel (Firma **und** Umgebung) gehört, antworten mit `404 NOT_FOUND` —
identisch zu unbekannten IDs.

### 4.7 `GET /v1/invoices/{id}/pdf` — Rechnungs-PDF

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  "$BASE/v1/invoices/in_1PxY…/pdf" -o rechnung.pdf
```

Antwortet mit `application/pdf` (`Content-Disposition: inline`), nicht mit
einer Weiterleitung. Das PDF läuft durch LEVIAPAY, damit für jeden Abruf der
API-Schlüssel geprüft wird — es gibt bewusst **keinen** dauerhaft gültigen
Direktlink, den man weiterreichen könnte. Für ein Kundenportal heißt das: das
PDF über deinen eigenen Server holen (mit deinem Schlüssel) und an den
eingeloggten Kunden ausliefern, statt einen Link in die Seite zu setzen.

Rechnungen im Status `draft` haben noch kein Dokument → `404`.

### 4.8 `GET /v1/products` — Produkte auflisten

```bash
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" "$BASE/v1/products"
```

```json
{
  "data": [
    {
      "id": "PRODUKT_ID",
      "kind": "subscription",
      "name": "Muster Professional",
      "currency": "eur",
      "amountCents": 29900,
      "minCents": null,
      "maxCents": null,
      "interval": "month",
      "trialDays": 0,
      "setupFeeCents": 0,
      "active": true,
      "apiEditable": false,
      "components": [
        { "key": "minuten", "name": "Minuten", "includedQty": 3000, "overageCentsPerUnit": 15 },
        { "key": "sms", "name": "SMS", "includedQty": 300, "overageCentsPerUnit": 12 }
      ],
      "addons": [
        { "key": "ki-kommentare", "name": "KI-Bewertungskommentare", "amountCents": 4900 }
      ]
    }
  ]
}
```

Nützlich, um Produkt-IDs für den Embed-Code (§2) zu finden. Limits je
Produkt: max. **8 Einträge kombiniert** (Komponenten + Add-ons zusammen),
Slugs `a-z 0-9 -` mit max. 40 Zeichen.

### 4.9 `POST /v1/products` — Produkt anlegen (nur Test-Schlüssel)

Legt ein Checkout-Produkt an. **Nur mit `lp_sk_test_…`-Schlüsseln** — mit
Live-Schlüsseln antwortet die API mit `403 TEST_KEY_REQUIRED`; Live-Produkte
verwaltet ihr im Dashboard.

```bash
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "subscription",
    "name": "Muster Professional",
    "amountCents": 29900,
    "interval": "month",
    "trialDays": 14,
    "meteredComponents": [
      { "key": "minuten", "name": "Minuten", "includedQty": 3000, "overageCentsPerUnit": 15 }
    ],
    "addons": [
      { "key": "ki-kommentare", "name": "KI-Bewertungskommentare", "amountCents": 4900 }
    ]
  }' "$BASE/v1/products"
```

Felder je `kind`:

| `kind` | Pflicht | Optional |
|---|---|---|
| `fixed` | `name`, `amountCents` (50–99999999) | — |
| `variable` | `name`, `minCents`, `maxCents` (je 50–99999999, min ≤ max) | — |
| `subscription` | `name`, `amountCents`, `interval` (`week`/`month`/`quarter`/`year`) | `trialDays` (0–730), `setupFeeCents` (0–100000), `meteredComponents`, `addons` |

Antwort: das öffentliche Produktobjekt inkl. neuer `id` (Format wie §4.8).
Unbekannte Felder werden abgelehnt (400). Max. 100 Produkte pro Konto.

### 4.10 `PATCH /v1/products/{id}` — Produkt ändern (nur Test-Schlüssel)

Partielles Update — **nur für Produkte, die per API angelegt wurden** (§4.9).
Im Dashboard angelegte Produkte sind über die API schreibgeschützt
(`403 DASHBOARD_ONLY`), damit ein API-Schlüssel niemals Preise unter bereits
live eingebetteten Bezahl-Buttons ändern kann. Zusätzlich kann jedes
API-Produkt im Dashboard **für API-Änderungen gesperrt** werden („Für API
sperren“ in der Produktliste) — empfohlen, bevor ihr ein API-Produkt live
einbettet; auch dann antwortet die API mit `403 DASHBOARD_ONLY`. Ob ein
Produkt per API änderbar ist, zeigt das Feld `apiEditable` in §4.8.
**Unveränderlich:** `kind`, `interval`, Währung.
Komponenten-/Add-on-Keys sind **append-only**: bestehende Keys bleiben an
ihrer Position (Stilllegen per `"inactive": true`), neue Einträge werden nur
angehängt — bestehende Abos behalten ohnehin ihren Signup-Snapshot (§4.1).

```bash
curl -X PATCH -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 34900, "active": true }' \
  "$BASE/v1/products/PRODUKT_ID"
```

`"active": false` deaktiviert das Produkt (verschwindet aus §4.8 und aus dem
Checkout). Antwort: das aktualisierte öffentliche Produktobjekt.

### 4.11 `POST /v1/invoices/{id}/resend` — Rechnung erneut verschicken

Schickt einen **bestehenden** Beleg noch einmal per E-Mail, mit dem PDF im
Anhang. Es wird keine Rechnung angelegt, kein Geld bewegt und nichts am Abo
geändert — der Aufruf stellt nur zu.

```bash
# an die hinterlegte Adresse des Abos
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" -d '{}' \
  "$BASE/v1/invoices/in_123/resend"

# einmalig woandershin, z. B. an die zentrale Buchhaltung
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"rechnung@zentrale.de"}' \
  "$BASE/v1/invoices/in_123/resend"
```

```json
{ "sent": true, "invoice": "in_123", "number": "R-2026-0042",
  "email": "rechnung@zentrale.de", "source": "request" }
```

`email` ist **optional**. Fehlt es, geht der Beleg an die Rechnungsadresse des
Abos (`source: "subscription"`); steht es da, gilt es **nur für diesen einen
Versand** — das Abo bleibt unverändert. Wer die Adresse dauerhaft umstellen
will, nimmt `POST /v1/subscriptions/{id}/billing-email`.

Entwürfe, stornierte Rechnungen und Rechnungen ohne PDF antworten mit
`INVALID_REQUEST`. Eine Rechnung, die nicht zu einem Abo dieses Kontos gehört,
antwortet mit `NOT_FOUND` — wie jedes fremde Objekt.

**Budget: 10 Aufrufe je Minute und Schlüssel.** Der Aufruf verschickt Post nach
draußen und hat deshalb ein eigenes, enges Kontingent, unabhängig vom
Lesebudget.

### 4.12 `POST /v1/subscriptions/{id}/billing-email` — Rechnungsadresse umstellen

Stellt um, **wohin die Rechnungen eines Abos gehen** — dauerhaft. Weder Preis
noch Laufzeit noch Geld ändern sich.

```bash
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"rechnung@zentrale.de"}' \
  "$BASE/v1/subscriptions/sub_123/billing-email"
```

```json
{ "subscription": "sub_123", "email": "rechnung@zentrale.de",
  "unchanged": false, "complete": true, "warning": null }
```

Hinter einem Abo stehen **zwei** Adressträger: der Stripe-Kunde (dort hängen
Stripes eigene Rechnungsmails und das PDF) und das Abo selbst (dort hängen
unsere Rechnungsmails). Dieser Aufruf setzt **beide**. Gelingt nur einer,
antwortet er mit **HTTP 207**, `complete: false` und einer `warning`, die sagt,
welche Seite noch auf der alten Adresse steht — dann den Aufruf einfach
wiederholen. Steht die Adresse bereits so, kommt `unchanged: true` und es
passiert nichts.

Bereits verschickte Rechnungen bleiben unverändert; einzelne lassen sich mit
`POST /v1/invoices/{id}/resend` nachreichen.

**Budget: 20 Aufrufe je Minute und Schlüssel.**

> **Live-Schlüssel:** Beide Aufrufe sind auch mit einem Live-Schlüssel
> erlaubt — anders als die Produkt-Schreibrouten. Im **MCP-Server** sind sie
> auf Live-Schlüsseln trotzdem gesperrt, bis `LEVIAPAY_MCP_ALLOW_LIVE_WRITES=1`
> gesetzt ist: ein KI-Assistent soll nicht von sich aus Post an echte
> Kundschaft schicken oder eine Rechnungsanschrift umstellen.

### 4.13 `POST /v1/checkout-links` — Zahl-Link mit Firmendaten anlegen

Legt einen **vorbereiteten Zahl-Link** an: Produkt plus die Daten des Käufers,
die das Bezahlfenster vorbelegt. Es ist derselbe Link wie im Dashboard unter
**Bezahlmodal → Produkte → Zahl-Links** und erscheint dort auch in der Liste (dort lässt
er sich ebenfalls abschalten). Funktioniert mit **Test- und Live-Schlüssel**;
die Umgebung des Links folgt dem Schlüssel. Der Link bewegt kein Geld und
ändert keinen Preis — bezahlt wird erst im Fenster, zu den Bedingungen des
Produkts.

```bash
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "productId": "PRODUKT_ID",
        "ref": "kunde-42",
        "expiresInDays": 14,
        "lockBuyer": true,
        "buyer": {
          "name": "Erika Muster",
          "email": "buchhaltung@kunde.de",
          "companyName": "Kunde GmbH",
          "companyStreet": "Hauptstraße 1",
          "companyZip": "10115",
          "companyCity": "Berlin",
          "ustId": "DE123456789"
        }
      }' \
  "$BASE/v1/checkout-links"
```

```json
{ "id": "K7QXRM2PZ4TB", "url": "https://leviapay.com/pay/K7QXRM2PZ4TB",
  "env": "live", "productId": "PRODUKT_ID", "amountCents": null,
  "voucherCode": null, "ref": "kunde-42", "singleUse": true,
  "lockBuyer": true, "expiresAt": "2026-10-15T08:00:00.000Z", "hasBuyer": true }
```

Die `url` gebt ihr dem Käufer. Die Käuferdaten werden in der Antwort **nicht**
zurückgegeben (nur `hasBuyer`) und lassen sich über die API auch später nicht
auslesen — die API ist kein Adressbuch.

**Felder** (alle außer `productId` optional; jedes andere Feld wird mit `400`
abgelehnt statt still ignoriert — ein `street` statt `companyStreet` fällt
also sofort auf):

| Feld | Bedeutung |
|---|---|
| `productId` | Aktives Produkt eures Betriebs (`GET /v1/products`). Abo oder Einmalzahlung. |
| `buyer.name` | Name des Käufers bzw. Ansprechpartners (≤ 120 Zeichen) |
| `buyer.email` | E-Mail für Beleg und — bei Abos — die Rechnungen |
| `buyer.companyName`, `buyer.companyStreet`, `buyer.companyZip`, `buyer.companyCity` | Firma und Anschrift. **Nur zu viert**: sobald eines gesetzt ist, sind alle vier Pflicht. |
| `buyer.ustId` | USt-IdNr. (nur zusammen mit den vier Firmenfeldern; Leerzeichen, Punkte und Bindestriche werden entfernt) |
| `expiresInDays` | Gültigkeit in Tagen, 1–90. **Pflicht, sobald `buyer` gesetzt ist.** |
| `singleUse` | Link gilt für genau einen Abschluss. Voreinstellung: `true`, sobald `buyer` gesetzt ist, sonst `false`. |
| `lockBuyer` | `true` sperrt die vorbelegten Felder: der Käufer sieht sie, kann sie aber nicht ändern — und der Server übernimmt beim Abschluss die Werte aus dem Link, egal was der Browser schickt. Nur zusammen mit `buyer`. Felder, die der Link leer lässt, bleiben frei. Voreinstellung `false`. |
| `ref` | Eure Referenz (≤ 128 Zeichen), erscheint wie `data-ref` als `merchantRef` am Abo |
| `amountCents` | Nur bei Produkten mit **variablem** Preis, innerhalb von deren Spanne (50 bis 99 999 999 Cent) |
| `voucherCode` | Gutschein, der im Fenster vorausgefüllt wird |
| `label` | Beschriftung (≤ 80 Zeichen) |

**Was der Käufer sieht:** Das Bezahlfenster ist mit den Daten **vorbelegt** —
ohne `lockBuyer` bleibt jedes Feld änderbar, mit `lockBuyer` sind die
belegten Felder grau und gesperrt („Vom Anbieter vorgegeben"). Bei einem
**Abo** heißt das E-Mail-Feld „E-Mail für Rechnungen": an diese Adresse geht
jede Rechnung des Abos. Bei einem
**Abo** landen Anschrift und USt-IdNr. am Stripe-Kunden und stehen damit auf
**jeder** künftigen Rechnung, ohne dass jemand sie abtippt.

**Warum Frist und Einmalverwendung:** Ein Link mit Firmendaten ist
weiterleitbar. Ohne Frist wäre ein weitergeleiteter Link dauerhaft ein
Datenleck; deshalb ist `expiresInDays` bei Käuferdaten Pflicht und der Link ist
nach dem ersten Abschluss verbraucht (bei Abos mit Testphase schon beim Start
der Testphase). Abgelaufen, verbraucht oder widerrufen → die Seite zeigt einen
Hinweis statt des Bezahlfensters.

**Fehler** kommen als `INVALID_REQUEST` mit zusätzlichem Feld `reason`:

| `reason` | Ursache |
|---|---|
| `INVALID_PRODUCT` | `productId` fehlt oder hat eine ungültige Form |
| `BAD_BUYER_COMPANY` | Firmenangaben unvollständig (die vier Felder gehören zusammen) |
| `BAD_USTID` | USt-IdNr. ungültig |
| `INVALID_BUYER_EMAIL` | E-Mail ungültig |
| `BUYER_NEEDS_EXPIRY` | Käuferdaten ohne `expiresInDays` |
| `INVALID_EXPIRY` | `expiresInDays` keine ganze Zahl von 1 bis 90 |
| `LOCK_NEEDS_BUYER` | `lockBuyer: true` ohne `buyer` |
| `INVALID_LOCK` | `lockBuyer` ist nicht `true`/`false` |
| `INVALID_CODE` | `voucherCode` hat keine gültige Form |
| `INVALID_AMOUNT` | `amountCents` keine ganze Zahl von 50 bis 99 999 999 |
| `AMOUNT_NEEDS_VARIABLE` | `amountCents` bei einem Produkt mit festem Preis |
| `AMOUNT_OUT_OF_RANGE` | `amountCents` außerhalb der Spanne (Antwort enthält `minCents`/`maxCents`) |

Ein unbekanntes, fremdes oder pausiertes Produkt ergibt `404 NOT_FOUND`.

```json
{ "error": { "code": "INVALID_REQUEST", "reason": "BUYER_NEEDS_EXPIRY",
  "message": "A link with buyer data needs expiresInDays (1-90) — ..." } }
```

### 4.14 `POST /v1/checkout-links/{id}/revoke` — Zahl-Link abschalten

```bash
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  "$BASE/v1/checkout-links/K7QXRM2PZ4TB/revoke"
```

```json
{ "id": "K7QXRM2PZ4TB", "revoked": true }
```

Sofort wirksam; bereits abgeschlossene Zahlungen und Abos bleiben unberührt.
Links eines anderen Betriebs oder der anderen Umgebung antworten mit `404`.

**Budget (beide Zahl-Link-Routen zusammen): 30 Aufrufe je Minute und
Schlüssel.**

> **MCP-Server:** Die Zahl-Link-Routen sind im MCP-Server `@leviapay/mcp`
> noch nicht als Tool enthalten — bitte direkt per HTTP aufrufen.

## 5. Worked Example: Muster GmbH — stündlicher Verbrauchs-Cron

Nach jedem Telefonat/SMS-Versand sammelt ihr Mengen; ein Cron meldet sie
stündlich mit deterministischen Idempotenz-Schlüsseln — ein Absturz + Neustart
kann so nie doppelt abrechnen:

```js
// usage-cron.js — stündlich (z. B. node-cron / systemd timer)
import { reportUsage } from "./leviapay.js"; // aus §4.1

// Beispiel: eure DB liefert je Kunde die seit letzter Meldung angefallenen Mengen.
async function run() {
  const hourBucket = new Date().toISOString().slice(0, 13); // "2026-07-08T14"
  const rows = await db.query(
    "SELECT leviapay_subscription_id AS sub, minutes, sms FROM usage_pending",
  );
  for (const row of rows) {
    if (row.minutes > 0)
      await reportUsage(row.sub, "minuten", row.minutes, `min-${row.sub}-${hourBucket}`);
    if (row.sms > 0)
      await reportUsage(row.sub, "sms", row.sms, `sms-${row.sub}-${hourBucket}`);
    await db.query("DELETE FROM usage_pending WHERE leviapay_subscription_id = $1", [row.sub]);
  }
}

run().catch((e) => { console.error(e); process.exit(1); });
```

Der Schlüssel `min-{sub}-{stunde}` ist deterministisch: Stürzt der Cron
zwischen Meldung und `DELETE` ab, sendet der nächste Lauf dieselbe Meldung
erneut, bekommt `duplicate: true` zurück und räumt auf — nichts wird doppelt
berechnet. (Analog funktioniert ein Tages-Cron mit `min-{sub}-2026-07-08`.)

Abrechnung übernimmt LEVIAPAY/Stripe: Meldet ihr im Monat 3 100 Minuten und
250 SMS, stellt die nächste Rechnung automatisch 299 € (Basis) + 49 € (Add-on,
falls gewählt) + 100 × 0,15 € = 15 € Minuten-Mehrverbrauch; SMS bleiben in der
Inklusivmenge (0 €).

## 5b. Rechnungen an die Buchhaltung — auch für bestehende Abos

Typischer Fall: Die Standorte eines Kunden bezahlen, die Rechnungen sollen
aber an die **zentrale Buchhaltung** gehen.

**Neue Abos:** Zahl-Link mit der Buchhaltungs-Adresse als `buyer.email` und
`lockBuyer: true` anlegen (§4.13). Der Standort gibt nur noch seine
Zahlungsdaten ein; jede Rechnung des Abos geht an die Buchhaltung.

**Bestehende Abos umstellen** — alle Abos eines Kunden finden und je Abo die
Rechnungsadresse setzen (§4.3, §4.12). Ältere Rechnungen lassen sich danach
an die neue Adresse nachreichen (§4.11).

```bash
# 1. Abos des Kunden finden (merchantRef = eure Referenz aus data-ref / ref)
curl -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  "$BASE/v1/subscriptions?ref=kunde-42&status=active"

# 2. je Abo die Rechnungsadresse umstellen
curl -X POST -H "Authorization: Bearer $LEVIAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"buchhaltung@zentrale.de"}' \
  "$BASE/v1/subscriptions/sub_123/billing-email"
```

```js
// Node 18+: alle aktiven Abos eines Kunden auf die Buchhaltung umstellen.
const BASE = "https://us-central1-leviapay-3fd2b.cloudfunctions.net/api";
const H = {
  Authorization: `Bearer ${process.env.LEVIAPAY_API_KEY}`,
  "Content-Type": "application/json",
};

async function aufBuchhaltungUmstellen(ref, email) {
  const liste = await (
    await fetch(`${BASE}/v1/subscriptions?ref=${encodeURIComponent(ref)}&status=active`, { headers: H })
  ).json();
  for (const abo of liste.data) {
    const r = await fetch(`${BASE}/v1/subscriptions/${abo.id}/billing-email`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({ email }),
    });
    const out = await r.json();
    // 207 = nur eine Seite umgestellt → einfach wiederholen (§4.12)
    console.log(abo.id, r.status, out.complete ? "umgestellt" : out.warning);
    await new Promise((ok) => setTimeout(ok, 3500)); // Budget 20/min
  }
}

aufBuchhaltungUmstellen("kunde-42", "buchhaltung@zentrale.de");
```

Ohne `ref` am Abo: `GET /v1/subscriptions` ohne Filter liefert alle Abos
(blättern mit `starting_after`); dann über `id`, `productName` oder eure
eigene Zuordnung auswählen. Im Dashboard geht dasselbe je Abo unter
**Bezahlmodal → Abos → Abo öffnen → Stift neben „Rechnungs-E-Mail"**.

## 6. MCP-Server für KI-Assistenten

Der offizielle MCP-Server `@leviapay/mcp` gibt eurem Assistenten 14 Tools:
Integrationsdoku abrufen (`get_integration_docs`), Produkte auflisten
(`list_products`), Produkte anlegen/ändern (`create_product`,
`update_product` — nur Test-Schlüssel, §4.9/§4.10), Embed-Snippets erzeugen
(`get_embed_snippet`), Abos und Verbrauch abfragen (`list_subscriptions`,
`get_subscription`, `get_usage`), Verbrauch melden (`report_usage`),
Rechnungen abrufen (`list_invoices`, `get_invoice`, `get_invoice_pdf_url` —
§4.5–§4.7) sowie Rechnung erneut senden und Rechnungsadresse umstellen
(`resend_invoice`, `set_billing_email` — §4.11/§4.12).

`get_invoice_pdf_url` liefert bewusst nur die Adresse, nicht das PDF selbst:
ein Megabyte Binärdaten durch ein Sprachmodell zu schicken hilft niemandem.

**Claude Code:**

```bash
claude mcp add leviapay -e LEVIAPAY_API_KEY=lp_sk_test_DEIN_SCHLUESSEL -- npx -y @leviapay/mcp
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "leviapay": {
      "command": "npx",
      "args": ["-y", "@leviapay/mcp"],
      "env": { "LEVIAPAY_API_KEY": "lp_sk_test_DEIN_SCHLUESSEL" }
    }
  }
}
```

Sicherheitsnetz: Auf **Live**-Schlüsseln ist `report_usage` gesperrt, außer
ihr setzt zusätzlich `LEVIAPAY_MCP_ALLOW_LIVE_USAGE=1` — lesende Tools sind
immer erlaubt. `create_product`/`update_product` sind auf Live-Schlüsseln
**immer** gesperrt (kein Override; zusätzlich serverseitig erzwungen) —
Live-Produkte verwaltet ihr im Dashboard. Details: README des Pakets
`@leviapay/mcp`.

## 7. Startprompts für KI-Assistenten

Kopiere einen der folgenden Prompts in deinen KI-Assistenten (z. B. Claude) um
direkt loszulegen. Füge deinen Schlüssel und deine Produkt-ID ein.

### (a) Integration einrichten

```
Hilf mir, das LEVIAPAY-Bezahlmodal in meine Website einzubinden.
Verwende ausschließlich den TEST-Modus (lp_pub_test_… / lp_sk_test_…).
Mein Test-Public-Key: lp_pub_test_DEIN_KEY
Meine Produkt-ID:    DEINE_PRODUKT_ID

Lies die Integrationsdokumentation über den MCP-Server (Tool: get_integration_docs)
oder direkt unter https://dashboard.leviapay.com/docs/LEVIAPAY-API.md.
Zeige mir den fertigen HTML-Snippet und erkläre die nächsten Schritte.
```

### (b) Täglicher Metering-Cron (Nutzung melden)

```
Baue einen täglichen Cron-Job, der Nutzungsdaten an LEVIAPAY meldet.
Verwende ausschließlich den TEST-Modus. Mein lp_sk_test_…-Schlüssel ist als
Umgebungsvariable LEVIAPAY_API_KEY gesetzt.

Anforderungen:
- Idempotency-Key: deterministisch aus subscriptionId + Datum (z. B. "{sub}-{YYYY-MM-DD}")
- POST /api/usage mit { subscriptionId, componentKey, quantity, idempotencyKey }
- Bei duplicate:true gilt die Meldung als erfolgreich — kein Fehler, kein Retry
- 429 mit exponentiellem Backoff wiederholen; 5xx mit gleichem idempotencyKey erneut senden

Dokumentation: https://dashboard.leviapay.com/docs/LEVIAPAY-API.md (Abschnitt 5)
```

## 8. Checkliste Go-Live

1. Integration vollständig mit `lp_sk_test_…` + Testkarte durchspielen
   (Abschluss, Verbrauch melden, `duplicate:true`-Replay, Rechnungsvorschau im
   Test-Stripe).
2. Live-Schlüssel (`lp_pub_live_…` im Button, `lp_sk_live_…` im Server)
   einsetzen — sonst ändert sich nichts.
3. `idempotencyKey`-Schema dokumentieren (deterministisch pro Meldung, §5).
   Wer Zahl-Links mit Firmendaten nutzt (§4.13): einen Link mit dem
   Live-Schlüssel anlegen, öffnen und prüfen, dass die Daten vorbelegt sind.
4. `429`-Antworten mit Backoff wiederholen; `5xx` mit **gleichem**
   `idempotencyKey` wiederholen.
