Lasku sisään, maksu-QR ulos — APIn kautta

Valmista kolmessa vaiheessa

1. 1

   Luo API-avain

   Kirjaudu sovellukseen ja luo avain kohdassa ”API & integraatiot”. Se alkaa gsk_live_ ja näytetään tasan kerran — talleta se turvallisesti. 10 ilmaista tokenia on jo tilillä.

2. 2

   Valitse ovi

   REST järjestelmällesi, MCP tekoälyagentillesi, sähköposti olemassa oleviin lähetysprosesseihin — tai yksinkertaisesti verkkosovellus. Avain on sama kaikkialla.

3. 3

   Lähetä laskuja

   Dokumentti sisään, vastauksena maksutiedot ja GiroCode — PDF:istä myös leimattu PDF. Jokainen vastaus kertoo käytetyt ja jäljellä olevat tokenit.

REST-API ja MCP-palvelin todentavat samalla GiroSnap-API-avaimella bearer-tokenina. Erillistä ”MCP-avainta” ei ole — sovelluksen gsk_live_-avain on se yksi avain:

Authorization: Bearer gsk_live_...

Avaimia luodaan ja peruutetaan vain sovelluksessa (kirjautunut istunto) — vuotanut avain ei voi koskaan luoda uusia avaimia. Selkokielistä avainta ei voi palauttaa luonnin jälkeen.

JSON tai multipart, enintään 12 Mt per dokumentti (JPG, PNG, WEBP, PDF). Nopein aloitus on kaikki-yhdessä-päätepiste:

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

• POST/api/v1/invoicesKaikki yhdessä: maksutiedot + QR, PDF:istä myös leimattu PDF.
• POST/api/v1/extractPoimi vain maksutiedot (ei QR:ää, ei leimaa).
• POST/api/v1/qrVain QR — valmiista maksutiedoista (ilman poimintaa) tai dokumentista.
• POST/api/v1/stampLeimaa GiroCode PDF:ään.
• GET/api/v1/balanceHae token-saldo, varoitusraja ja paketit (ilmainen).
• POST/api/v1/checkoutLuo suoraan maksettava Stripe-linkki token-paketille.

Kaikki parametrit, vastausmuodot ja virhekoodit — mukaan lukien ”try it out” suoraan selaimessa: Avaa interaktiivinen API-referenssi

MCP (Model Context Protocol) on avoin standardi, jolla tekoälyagentit (esim. Claude) käyttävät ulkoisia työkaluja. MCP-palvelimemme antaa agentillesi GiroSnapin työkalupakiksi: se kuvaa laskun, kutsuu työkalua ja saa GiroCoden tai leimatun PDF:n suoraan takaisin työnkulkuunsa.

Helpoin reitti — Claude (web & työpöytä): Asetukset → Liittimet → ”Lisää mukautettu liitin”, nimeä se ”GiroSnap” ja liitä tämä URL avaimesi kanssa. Jätä OAuth-kentät tyhjiksi:

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

Tämä URL sisältää API-avaimesi — käsittele sitä kuin salasanaa äläkä jaa sitä.

Yhdistäminen: syötä palvelimen URL ja anna API-avaimesi Authorization-otsakkeessa — sama asetus toimii Claudessa, IDE-agenteissa ja omissa SDK-agenteissasi:

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

GIROSNAP_API_KEY on tavallinen gsk_live_-avaimesi sovelluksesta — erillistä MCP-avainta ei ole.

Työkalut yksitellen

• extract_invoice1 token/sivu

  Lukee saajan, IBANin, BICin, summan (sentteinä) ja viitteen laskukuvasta tai PDF:stä. Tarpeen vain, jos agenttisi ei voi tai saa lukea laskua itse.

• create_payment_qr1 token/sivu

  Luo skannattavan EPC/GiroCoden — kuvana, SVG:nä ja raakadatana. Ottaa valmiit maksutiedot (nopein reitti, ei poimintaa) tai dokumentin.

• stamp_invoice_pdf1 token/sivu

  Leimaa GiroCoden PDF-laskuun — vapaaseen tilaan tai lisätylle sivulle; allekirjoitetut PDF:t ja verkkolaskut säilyvät koskemattomina ja saavat saatelehden.

• get_token_balanceilmainen

  Nykyinen token-saldo, varoitusrajan ilmaisin, pakettilista ja latauslinkki.

• buy_tokensilmainen

  Luo suoraan maksettavan Stripe Checkout -linkin token-paketille — tokenit hyvitetään automaattisesti maksun jälkeen.

Vinkki: jos agenttisi tuntee maksutiedot jo (onhan se nähnyt laskun), se antaa ne payment-kenttänä create_payment_qr- tai stamp_invoice_pdf-työkalulle — meillä ei silloin aja mikään poiminta ja vastaus tulee nopeimmin.

Lähetä laskut yksinkertaisesti sähköpostilla — täysin ilman koodia. Kuviin vastaamme GiroCodella viestin rungossa; PDF:t palaavat leimattuina liitteinä, vaikka useampi per viesti.

1. Rekisteröi lähettäjäosoitteesi sovelluksessa kohdassa ”API & integraatiot”.
2. Napsauta vahvistuslinkkiä sähköpostissa — valmis.
3. Lähetä laskut (PDF, JPG, PNG, WEBP) käsittelyosoitteeseen ja odota vastausta.

Enintään 10 liitettä per viesti, kukin 12 Mt. Vastaus kertoo aina käytetyt ja jäljellä olevat tokenit; kun saldo käy vähiin, latauslinkki on mukana.

Sovellus itse on neljäs ovi: lataa, tarkista, leimaa — suoraan selaimessa. Ja tulipa lasku mistä ovesta tahansa: kaikki kirjautuu historiaasi, ja QR, PDF:t ja kulut ovat haettavissa milloin vain.

Yksi sääntö, kaikkialla: 1 token per sivu (QR valmiista tiedoista lasketaan yhdeksi sivuksi). Uudet tilit alkavat 10 ilmaisella tokenilla; lataus tapahtuu Stripen kautta — sovelluksessa, POST /api/v1/checkout -kutsulla tai buy_tokens-työkalulla.

Kun saldo käy vähiin, varoitamme sähköpostilla; nollassa käsittely pysähtyy kaikilla ovilla (mitään tekoälypalvelua ei kutsuta) ja jokainen vastaus sisältää latauslinkin.

Reilu laskutus: jos käsittely epäonnistuu meidän päässämme, token palautetaan. Jos malli ajoi mutta ei voinut lukea laskua, se jää käytetyksi.

Kaikki virheet käyttävät samaa kuorta — koneluettava code, ymmärrettävä message ja tokenien loppuessa (HTTP 402) latauslinkki suoraan vastauksessa:

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

Tärkeät koodit: insufficient_tokens (402), unreadable (422, malli ajoi — token käytetty), extraction_failed (502, palautettu), unsupported_media (415), file_too_large (413). Täysi luettelo interaktiivisessa referenssissä.