Sąskaita įeina, mokėjimo QR išeina — per API

Paruošta per tris žingsnius

1. 1

   Sukurk API raktą

   Prisijunk prie programos ir sukurk raktą skiltyje „API ir integracijos“. Jis prasideda gsk_live_ ir parodomas lygiai vieną kartą — saugok jį patikimai. 10 nemokamų žetonų jau yra paskyroje.

2. 2

   Pasirink duris

   REST tavo sistemai, MCP tavo DI agentui, el. paštas esamiems siuntimo procesams — arba tiesiog žiniatinklio programa. Raktas visur tas pats.

3. 3

   Siųsk sąskaitas

   Dokumentas įeina, atsakyme — mokėjimo duomenys ir GiroCode; PDF atveju dar ir antspauduotas PDF. Kiekvienas atsakymas nurodo panaudotus ir likusius žetonus.

REST API ir MCP serveris autentifikuojasi tuo pačiu GiroSnap API raktu kaip bearer tokenu. Atskiro „MCP rakto“ nėra — programos gsk_live_ raktas ir yra tas vienintelis:

Authorization: Bearer gsk_live_...

Raktai kuriami ir atšaukiami tik programoje (prisijungusi sesija) — nutekėjęs raktas niekada negali sukurti naujų raktų. Rakto teksto po sukūrimo atgauti nebeįmanoma.

JSON arba multipart, iki 12 MB dokumentui (JPG, PNG, WEBP, PDF). Greičiausia pradžia — visko-viename galinis taškas:

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

• POST/api/v1/invoicesViskas viename: mokėjimo duomenys + QR, PDF atveju dar ir antspauduotas PDF.
• POST/api/v1/extractTik mokėjimo duomenų išgavimas (be QR, be antspaudo).
• POST/api/v1/qrTik QR — iš paruoštų mokėjimo duomenų (be išgavimo) arba iš dokumento.
• POST/api/v1/stampGiroCode antspaudavimas ant PDF.
• GET/api/v1/balanceŽetonų likučio, įspėjimo ribos ir paketų užklausa (nemokama).
• POST/api/v1/checkoutTiesiogiai apmokamos Stripe nuorodos sukūrimas žetonų paketui.

Visi parametrai, atsakymų formatai ir klaidų kodai — įskaitant „try it out“ tiesiai naršyklėje: Atidaryti interaktyvią API nuorodą

MCP (Model Context Protocol) — atvirasis standartas, kuriuo DI agentai (pvz., Claude) naudoja išorinius įrankius. Mūsų MCP serveris tavo agentui atiduoda GiroSnap kaip įrankių dėžę: jis nufotografuoja sąskaitą, iškviečia įrankį ir gauna GiroCode arba antspauduotą PDF tiesiai į savo darbo eigą.

Paprasčiausias kelias — Claude (žiniatinklis ir darbalaukis): Nustatymai → Jungtys → „Pridėti tinkintą jungtį“, pavadink ją „GiroSnap“ ir įklijuok šį URL su savo raktu. OAuth laukus palik tuščius:

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

Šiame URL yra tavo API raktas — elkis su juo kaip su slaptažodžiu ir juo nesidalink.

Prijungimas: įvesk serverio URL ir perduok savo API raktą Authorization antraštėje — ta pati konfigūracija veikia Claude, IDE agentuose ir tavo paties SDK agentuose:

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

GIROSNAP_API_KEY — tavo įprastas gsk_live_ raktas iš programos; atskiro MCP rakto nėra.

Įrankiai po vieną

• extract_invoice1 žetonas/psl.

  Nuskaito gavėją, IBAN, BIC, sumą (centais) ir mokėjimo paskirtį iš sąskaitos nuotraukos ar PDF. Reikalingas tik tada, kai tavo agentas negali arba neturi pats skaityti sąskaitos.

• create_payment_qr1 žetonas/psl.

  Sugeneruoja nuskaitomą EPC/GiroCode — kaip paveikslėlį, SVG ir neapdorotą turinį. Priima paruoštus mokėjimo duomenis (greičiausias kelias, be išgavimo) arba dokumentą.

• stamp_invoice_pdf1 žetonas/psl.

  Antspauduoja GiroCode ant PDF sąskaitos — laisvoje vietoje arba pridėtame puslapyje; pasirašyti PDF ir e. sąskaitos lieka nepaliesti ir gauna palydimąjį lapą.

• get_token_balancenemokama

  Esamas žetonų likutis, ribos indikatorius, paketų sąrašas ir papildymo nuoroda.

• buy_tokensnemokama

  Sukuria tiesiogiai apmokamą Stripe Checkout nuorodą žetonų paketui — po apmokėjimo žetonai įskaitomi automatiškai.

Gudrybė: jei tavo agentas mokėjimo duomenis jau žino (juk sąskaitą matė), jis tiesiog perduoda juos kaip payment įrankiui create_payment_qr arba stamp_invoice_pdf — mūsų pusėje tada nevyksta joks išgavimas ir atsakymas ateina greičiausiai.

Siųsk sąskaitas tiesiog el. paštu — visiškai be kodo. Į nuotraukas atsakome GiroCode laiško tekste; PDF grįžta antspauduoti kaip priedai, kad ir keli viename laiške.

1. Užregistruok savo siuntėjo adresą programoje skiltyje „API ir integracijos“.
2. Spustelk patvirtinimo nuorodą laiške — atlikta.
3. Siųsk sąskaitas (PDF, JPG, PNG, WEBP) apdorojimo adresu ir lauk atsakymo.

Iki 10 priedų viename laiške, kiekvienas iki 12 MB. Atsakymas visada nurodo panaudotus ir likusius žetonus; kai likutis senka, pridedama papildymo nuoroda.

Pati programa — ketvirtosios durys: įkelk, patikrink, antspauduok — tiesiai naršyklėje. Ir kad ir pro kurias duris sąskaita ateitų: viskas registruojama tavo istorijoje, kur QR, PDF ir išlaidos pasiekiami bet kada.

Viena taisyklė visur: 1 žetonas už puslapį (QR iš paruoštų duomenų skaičiuojamas kaip vienas puslapis). Naujos paskyros pradeda su 10 nemokamų žetonų; papildoma per Stripe — programoje, per POST /api/v1/checkout arba su buy_tokens įrankiu.

Kai likutis senka, įspėjame el. paštu; pasiekus nulį apdorojimas sustoja visose duryse (joks DI servisas nebekviečiamas), o kiekvienas atsakymas neša papildymo nuorodą.

Sąžiningas skaičiavimas: jei apdorojimas nepavyksta mūsų pusėje, žetonas grąžinamas. Jei modelis veikė, bet negalėjo perskaityti sąskaitos, jis lieka panaudotas.

Visos klaidos naudoja tą patį voką — mašininiu būdu nuskaitomą code, suprantamą message ir, pritrūkus žetonų (HTTP 402), papildymo nuorodą tiesiai atsakyme:

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

Svarbiausi kodai: insufficient_tokens (402), unreadable (422, modelis veikė — žetonas panaudotas), extraction_failed (502, grąžintas), unsupported_media (415), file_too_large (413). Visas katalogas interaktyvioje nuorodoje.