Factuur erin, betaal-QR eruit — via de API

In drie stappen klaar

1. 1

   Maak een API-key aan

   Log in op de app en maak een key aan onder “API & integraties”. Hij begint met gsk_live_ en wordt precies één keer getoond — bewaar hem veilig. 10 gratis tokens staan al op het account.

2. 2

   Kies een deur

   REST voor je systeem, MCP voor je AI-agent, e-mail voor bestaande verzendworkflows — of gewoon de webapp. De key is overal dezelfde.

3. 3

   Stuur facturen

   Document erin, antwoord met betaalgegevens en de GiroCode eruit — bij PDF’s ook de gestempelde PDF. Elk antwoord vermeldt verbruikte en resterende tokens.

De REST-API en de MCP-server authenticeren met dezelfde GiroSnap-API-key als bearer-token. Er is geen aparte “MCP-key” — de gsk_live_-key uit de app is dé key:

Authorization: Bearer gsk_live_...

Keys maak en trek je alleen in de app in (ingelogde sessie) — een gelekte key kan nooit nieuwe keys aanmaken. De platte tekst is na het aanmaken nooit meer op te vragen.

JSON of multipart, max. 12 MB per document (JPG, PNG, WEBP, PDF). De snelste start is het alles-in-één-endpoint:

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

• POST/api/v1/invoicesAlles in één: betaalgegevens + QR, bij PDF’s ook de gestempelde PDF.
• POST/api/v1/extractAlleen betaalgegevens extraheren (geen QR, geen stempel).
• POST/api/v1/qrAlleen QR — uit betaalgegevens (zonder extractie) of uit een document.
• POST/api/v1/stampDe GiroCode op een PDF stempelen.
• GET/api/v1/balanceTokentegoed, waarschuwingsdrempel en pakketten opvragen (gratis).
• POST/api/v1/checkoutEen direct betaalbare Stripe-link voor een tokenpakket aanmaken.

Alle parameters, antwoordformaten en foutcodes — inclusief “try it out” direct in de browser: Open de interactieve API-referentie

MCP (Model Context Protocol) is de open standaard waarmee AI-agents (bijv. Claude) externe tools gebruiken. Onze MCP-server geeft je agent GiroSnap als gereedschapskist: hij fotografeert een factuur, roept een tool aan en krijgt de GiroCode of de gestempelde PDF direct terug in zijn flow.

De makkelijkste weg — Claude (web & desktop): Instellingen → Connectoren → “Aangepaste connector toevoegen”, noem hem “GiroSnap” en plak deze URL met je key. Laat de OAuth-velden leeg:

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

Deze URL bevat je API-key — behandel hem als een wachtwoord en deel hem niet.

Verbinden: vul de server-URL in en geef je API-key mee als Authorization-header — dezelfde config werkt in Claude, IDE-agents en je eigen SDK-agents:

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

GIROSNAP_API_KEY is je normale gsk_live_-key uit de app — er is geen aparte MCP-key.

De tools in detail

• extract_invoice1 token/pagina

  Leest begunstigde, IBAN, BIC, bedrag (in centen) en betalingskenmerk uit een factuurfoto of PDF. Alleen nodig als je agent de factuur niet zelf kan of mag lezen.

• create_payment_qr1 token/pagina

  Genereert de scanbare EPC/GiroCode — als afbeelding, SVG en ruwe payload. Accepteert kant-en-klare betaalgegevens (snelste weg, geen extractie) of een document.

• stamp_invoice_pdf1 token/pagina

  Stempelt de GiroCode op de PDF-factuur — op vrije ruimte of een toegevoegde pagina; ondertekende PDF’s en e-facturen blijven onaangeroerd en krijgen een begeleidend blad.

• get_token_balancegratis

  Actueel tokentegoed, drempelindicator, pakketlijst en oplaadlink.

• buy_tokensgratis

  Maakt een direct betaalbare Stripe-Checkout-link voor een tokenpakket — na betaling worden de tokens automatisch bijgeschreven.

Slimmigheid: kent je agent de betaalgegevens al (hij heeft de factuur immers gezien), dan geeft hij ze gewoon als payment mee aan create_payment_qr of stamp_invoice_pdf — bij ons draait dan geen extractie en het antwoord komt het snelst.

Stuur facturen gewoon per e-mail — helemaal zonder code. Op foto’s antwoorden we met de GiroCode in de body, PDF’s komen gestempeld terug als bijlage, ook meerdere per mail.

1. Registreer je afzenderadres in de app onder “API & integraties”.
2. Klik op de bevestigingslink in de mail — klaar.
3. Stuur facturen (PDF, JPG, PNG, WEBP) naar het verwerkingsadres en wacht op het antwoord.

Maximaal 10 bijlagen per mail, elk 12 MB. Het antwoord vermeldt altijd verbruikte en resterende tokens; wordt het tegoed krap, dan zit de oplaadlink erbij.

De app zelf is de vierde deur: uploaden, controleren, stempelen — direct in de browser. En via welke deur een factuur ook binnenkomt: alles wordt gejournaliseerd in je geschiedenis, met QR, PDF’s en kosten altijd terug te vinden.

Eén regel, overal: 1 token per pagina (een QR uit kant-en-klare gegevens telt als één pagina). Nieuwe accounts starten met 10 gratis tokens; opladen gaat via Stripe — in de app, via POST /api/v1/checkout of met de buy_tokens-tool.

Wordt het tegoed krap, dan waarschuwen we per e-mail; bij 0 pauzeert de verwerking op alle deuren (er wordt geen AI-dienst meer aangeroepen) en draagt elk antwoord de oplaadlink.

Eerlijk afgerekend: mislukt de verwerking aan onze kant, dan wordt de token terugbetaald. Draaide het model maar kon het de factuur niet lezen, dan blijft hij verbruikt.

Elke fout gebruikt dezelfde envelope — een machineleesbare code, een begrijpelijke message en bij tokentekort (HTTP 402) direct de oplaadlink in het antwoord:

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

Belangrijke codes: insufficient_tokens (402), unreadable (422, het model draaide — token verbruikt), extraction_failed (502, terugbetaald), unsupported_media (415), file_too_large (413). Volledige catalogus in de interactieve referentie.