Rechnung rein, Bezahl-QR raus — per API

In drei Schritten startklar

1. 1

   API-Key erstellen

   In der App anmelden und unter „API & Integrationen“ einen Key erstellen. Er beginnt mit gsk_live_ und wird genau einmal angezeigt — sicher speichern. 10 Gratis-Tokens sind schon drauf.

2. 2

   Weg wählen

   REST für dein System, MCP für deinen KI-Agenten, E-Mail für bestehende Versand-Workflows — oder einfach die Web-App. Der Key ist überall derselbe.

3. 3

   Rechnungen schicken

   Dokument rein, Antwort mit Zahldaten und GiroCode raus — bei PDFs zusätzlich die gestempelte PDF. Jede Antwort nennt verbrauchte und verbleibende Tokens.

REST-API und MCP-Server authentifizieren mit demselben GiroSnap-API-Key als Bearer-Token. Es gibt keinen separaten „MCP-Key“ — der gsk_live_-Key aus der App ist der eine Schlüssel:

Authorization: Bearer gsk_live_...

Keys erstellst und widerrufst du nur in der App (eingeloggte Session) — ein geleakter Key kann keine neuen Keys erzeugen. Der Klartext ist nach dem Erstellen nie wieder abrufbar.

JSON oder multipart, maximal 12 MB pro Dokument (JPG, PNG, WEBP, PDF). Der schnellste Einstieg ist der Alles-in-einem-Endpunkt:

curl -X POST https://www.girosnap.eu/api/v1/invoices \
  -H "Authorization: Bearer gsk_live_..." \
  -F "file=@rechnung.pdf"

• POST/api/v1/invoicesAlles in einem: Zahldaten + QR, bei PDF zusätzlich die gestempelte PDF.
• POST/api/v1/extractNur Zahldaten extrahieren (kein QR, kein Stempel).
• POST/api/v1/qrNur QR — aus Zahldaten (ohne Extraktion) oder aus einem Dokument.
• POST/api/v1/stampPDF mit dem GiroCode stempeln.
• GET/api/v1/balanceToken-Stand, Warnschwelle und Pakete abfragen (kostenlos).
• POST/api/v1/checkoutDirekt bezahlbaren Stripe-Link für ein Token-Paket erzeugen.

Alle Parameter, Antwortformate und Fehlercodes — inklusive „Try it out“ direkt im Browser: Zur interaktiven API-Referenz

MCP (Model Context Protocol) ist der offene Standard, mit dem KI-Agenten (z. B. Claude) externe Werkzeuge nutzen. Unser MCP-Server gibt deinem Agenten GiroSnap als Werkzeugkasten: Er fotografiert eine Rechnung, ruft ein Tool auf und bekommt den GiroCode oder die gestempelte PDF direkt in seinen Arbeitsfluss zurück.

Der einfachste Weg — Claude (Web & Desktop): Einstellungen → Konnektoren → „Benutzerdefinierten Connector hinzufügen“, Name „GiroSnap“, und als URL diese Adresse mit deinem Key. Die OAuth-Felder bleiben leer:

https://www.girosnap.eu/api/mcp?key=GIROSNAP_API_KEY

Diese URL enthält deinen API-Key — behandle sie wie ein Passwort und teile sie nicht.

Verbinden: Server-URL eintragen und deinen API-Key als Authorization-Header mitgeben — dieselbe Config funktioniert in Claude, IDE-Agenten und eigenen SDK-Agenten:

{
  "mcpServers": {
    "girosnap": {
      "type": "http",
      "url": "https://www.girosnap.eu/api/mcp",
      "headers": {
        "Authorization": "Bearer gsk_live_..."
      }
    }
  }
}

GIROSNAP_API_KEY ist dein normaler gsk_live_-Key aus der App — es gibt keinen separaten MCP-Key.

Die Werkzeuge im Einzelnen

• extract_invoice1 Token/Seite

  Liest Empfänger, IBAN, BIC, Betrag (in Cent) und Verwendungszweck aus einem Rechnungsfoto oder PDF. Nur nötig, wenn dein Agent die Rechnung nicht selbst lesen kann oder soll.

• create_payment_qr1 Token/Seite

  Erzeugt den scanbaren EPC/GiroCode — als Bild, SVG und Roh-Payload. Nimmt fertige Zahldaten (schnellster Weg, keine Extraktion) oder ein Dokument.

• stamp_invoice_pdf1 Token/Seite

  Stempelt den GiroCode auf die PDF-Rechnung — auf freie Fläche oder eine angehängte Seite; signierte PDFs und E-Rechnungen bleiben unverändert und bekommen ein Begleitblatt.

• get_token_balancekostenlos

  Aktueller Token-Stand, Warnschwellen-Flag, Paketliste und Auflade-Link.

• buy_tokenskostenlos

  Erzeugt einen direkt bezahlbaren Stripe-Checkout-Link für ein Token-Paket — nach der Zahlung werden die Tokens automatisch gutgeschrieben.

Spartrick: Kennt dein Agent die Zahldaten schon (er hat die Rechnung ja gesehen), übergibt er sie einfach als payment an create_payment_qr oder stamp_invoice_pdf — dann läuft auf unserer Seite keine Extraktion und die Antwort kommt am schnellsten.

Rechnungen einfach per E-Mail schicken — ganz ohne Code. Fotos beantworten wir mit dem GiroCode im Body, PDFs mit der gestempelten PDF im Anhang, auch mehrere pro Mail.

1. In der App unter „API & Integrationen“ deine Absenderadresse registrieren.
2. Bestätigungslink in der Mail anklicken — fertig.
3. Rechnungen (PDF, JPG, PNG, WEBP) an die Verarbeitungsadresse schicken und die Antwort abwarten.

Maximal 10 Anhänge pro Mail, je 12 MB. Die Antwort nennt immer verbrauchte und verbleibende Tokens; wird das Guthaben knapp, ist der Auflade-Link gleich dabei.

Die App selbst ist der vierte Weg: hochladen, prüfen, stempeln — direkt im Browser. Und egal über welchen Weg eine Rechnung reinkommt: Alles wird im Verlauf journalisiert, mit QR, PDFs und Kosten jederzeit wieder abrufbar.

Eine Regel, überall: 1 Token pro Seite (ein QR aus fertigen Zahldaten zählt als eine Seite). Neue Konten starten mit 10 Gratis-Tokens; aufgeladen wird per Stripe — in der App, per POST /api/v1/checkout oder mit dem buy_tokens-Tool.

Wird das Guthaben knapp, warnen wir per E-Mail; bei 0 pausiert die Verarbeitung auf allen Wegen (es wird kein KI-Dienst mehr aufgerufen) und jede Antwort trägt den Auflade-Link.

Fair abgerechnet: Scheitert die Verarbeitung auf unserer Seite, wird der Token erstattet. Lief das Modell, konnte die Rechnung aber nicht lesen, bleibt er verbraucht.

Alle Fehler kommen im selben Envelope — maschinenlesbarer code, verständliche message und bei Tokenknappheit (HTTP 402) direkt der Auflade-Link:

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Not enough tokens for this operation.",
    "needed": 3,
    "balance": 1,
    "checkoutUrl": "https://www.girosnap.eu/app?screen=tokens"
  }
}

Wichtige Codes: insufficient_tokens (402), unreadable (422, Modell lief — Token verbraucht), extraction_failed (502, erstattet), unsupported_media (415), file_too_large (413). Vollständiger Katalog in der interaktiven Referenz.