Rēķins iekšā, maksājuma QR ārā — caur API

Gatavs trīs soļos

1. 1

   Izveido API atslēgu

   Pieraksties lietotnē un izveido atslēgu sadaļā “API un integrācijas”. Tā sākas ar gsk_live_ un tiek parādīta tieši vienu reizi — glabā to drošā vietā. 10 bezmaksas marķieri jau ir kontā.

2. 2

   Izvēlies durvis

   REST tavai sistēmai, MCP tavam MI aģentam, e-pasts esošajām sūtīšanas plūsmām — vai vienkārši tīmekļa lietotne. Atslēga visur ir viena un tā pati.

3. 3

   Sūti rēķinus

   Dokuments iekšā, atbildē maksājuma dati un GiroCode — PDF gadījumā arī apzīmogotais PDF. Katra atbilde norāda iztērētos un atlikušos marķierus.

REST API un MCP serveris autentificējas ar to pašu GiroSnap API atslēgu kā bearer tokenu. Atsevišķas “MCP atslēgas” nav — lietotnes gsk_live_ atslēga ir tā vienīgā:

Authorization: Bearer gsk_live_...

Atslēgas veido un atsauc tikai lietotnē (pierakstīta sesija) — noplūdusi atslēga nekad nevar izveidot jaunas atslēgas. Atslēgas teksts pēc izveides vairs nav atgūstams.

JSON vai multipart, ne vairāk kā 12 MB uz dokumentu (JPG, PNG, WEBP, PDF). Ātrākais sākums ir viss-vienā galapunkts:

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

• POST/api/v1/invoicesViss vienā: maksājuma dati + QR, PDF gadījumā arī apzīmogotais PDF.
• POST/api/v1/extractTikai maksājuma datu izvilkšana (bez QR, bez zīmoga).
• POST/api/v1/qrTikai QR — no gataviem maksājuma datiem (bez izvilkšanas) vai no dokumenta.
• POST/api/v1/stampGiroCode uzzīmogošana uz PDF.
• GET/api/v1/balanceMarķieru atlikuma, brīdinājuma sliekšņa un pakešu vaicājums (bez maksas).
• POST/api/v1/checkoutTieši apmaksājamas Stripe saites izveide marķieru paketei.

Visi parametri, atbilžu formāti un kļūdu kodi — ieskaitot “try it out” tieši pārlūkā: Atvērt interaktīvo API atsauci

MCP (Model Context Protocol) ir atvērtais standarts, ar kuru MI aģenti (piem., Claude) izmanto ārējos rīkus. Mūsu MCP serveris nodod tavam aģentam GiroSnap kā rīku komplektu: tas nofotografē rēķinu, izsauc rīku un saņem GiroCode vai apzīmogoto PDF tieši atpakaļ savā darba plūsmā.

Vienkāršākais ceļš — Claude (tīmeklis un darbvirsma): Iestatījumi → Savienotāji → “Pievienot pielāgotu savienotāju”, nosauc to “GiroSnap” un ielīmē šo URL ar savu atslēgu. Atstāj OAuth laukus tukšus:

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

Šis URL satur tavu API atslēgu — izturies pret to kā pret paroli un nedalies ar to.

Pieslēgšana: ievadi servera URL un padod savu API atslēgu Authorization galvenē — tā pati konfigurācija darbojas Claude, IDE aģentos un tavos SDK aģentos:

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

GIROSNAP_API_KEY ir tava parastā gsk_live_ atslēga no lietotnes — atsevišķas MCP atslēgas nav.

Rīki pa vienam

• extract_invoice1 marķieris/lapa

  Nolasa saņēmēju, IBAN, BIC, summu (centos) un maksājuma mērķi no rēķina fotogrāfijas vai PDF. Vajadzīgs tikai tad, ja tavs aģents pats nevar vai nedrīkst lasīt rēķinu.

• create_payment_qr1 marķieris/lapa

  Ģenerē skenējamu EPC/GiroCode — kā attēlu, SVG un neapstrādātu saturu. Pieņem gatavus maksājuma datus (ātrākais ceļš, bez izvilkšanas) vai dokumentu.

• stamp_invoice_pdf1 marķieris/lapa

  Uzzīmogo GiroCode uz PDF rēķina — brīvā vietā vai pievienotā lapā; parakstīti PDF un e-rēķini paliek neskarti un saņem pavadlapu.

• get_token_balancebez maksas

  Pašreizējais marķieru atlikums, sliekšņa rādītājs, pakešu saraksts un papildināšanas saite.

• buy_tokensbez maksas

  Izveido tieši apmaksājamu Stripe Checkout saiti marķieru paketei — pēc maksājuma marķieri tiek ieskaitīti automātiski.

Padoms: ja tavs aģents maksājuma datus jau zina (viņš taču redzēja rēķinu), viņš tos vienkārši padod kā payment rīkam create_payment_qr vai stamp_invoice_pdf — mūsu pusē tad nenotiek nekāda izvilkšana, un atbilde ir visātrākā.

Sūti rēķinus vienkārši pa e-pastu — pilnīgi bez koda. Uz fotogrāfijām atbildam ar GiroCode vēstules tekstā; PDF atgriežas apzīmogoti kā pielikumi, kaut vairāki vienā vēstulē.

1. Reģistrē savu sūtītāja adresi lietotnē sadaļā “API un integrācijas”.
2. Noklikšķini uz apstiprinājuma saites e-pastā — gatavs.
3. Sūti rēķinus (PDF, JPG, PNG, WEBP) uz apstrādes adresi un gaidi atbildi.

Līdz 10 pielikumiem vienā vēstulē, katrs 12 MB. Atbilde vienmēr norāda iztērētos un atlikušos marķierus; kad atlikums kļūst mazs, klāt ir papildināšanas saite.

Pati lietotne ir ceturtās durvis: augšupielādē, pārbaudi, apzīmogo — tieši pārlūkā. Un lai pa kurām durvīm rēķins ienāktu: viss tiek reģistrēts tavā vēsturē, kur QR, PDF un izmaksas ir pieejamas jebkurā brīdī.

Viens noteikums, visur: 1 marķieris par lapu (QR no gataviem datiem skaitās kā viena lapa). Jauni konti sāk ar 10 bezmaksas marķieriem; papildināšana notiek caur Stripe — lietotnē, ar POST /api/v1/checkout vai ar buy_tokens rīku.

Kad atlikums kļūst mazs, brīdinām pa e-pastu; pie nulles apstrāde apstājas uz visām durvīm (neviens MI serviss netiek izsaukts), un katra atbilde nes papildināšanas saiti.

Godīga uzskaite: ja apstrāde neizdodas mūsu pusē, marķieris tiek atgriezts. Ja modelis darbojās, bet nevarēja izlasīt rēķinu, tas paliek iztērēts.

Visas kļūdas izmanto vienu un to pašu aploksni — mašīnlasāms code, saprotams message un, ja pietrūkst marķieru (HTTP 402), papildināšanas saite tieši atbildē:

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

Svarīgākie kodi: insufficient_tokens (402), unreadable (422, modelis darbojās — marķieris iztērēts), extraction_failed (502, atgriezts), unsupported_media (415), file_too_large (413). Pilns katalogs interaktīvajā atsaucē.