Fattura dentro, QR di pagamento fuori — via API

Pronto in tre passi

1. 1

   Crea una chiave API

   Accedi all’app e crea una chiave in «API & integrazioni». Inizia con gsk_live_ e viene mostrata una sola volta — conservala al sicuro. 10 token gratuiti sono già sull’account.

2. 2

   Scegli una porta

   REST per il tuo sistema, MCP per il tuo agente IA, email per i flussi di invio esistenti — o semplicemente la web app. La chiave è la stessa ovunque.

3. 3

   Invia le fatture

   Documento dentro, risposta con i dati di pagamento e il GiroCode fuori — per i PDF anche il PDF timbrato. Ogni risposta indica i token addebitati e quelli rimanenti.

L’API REST e il server MCP si autenticano con la stessa chiave API GiroSnap come bearer token. Non esiste una «chiave MCP» separata — la chiave gsk_live_ dell’app è l’unica chiave:

Authorization: Bearer gsk_live_...

Le chiavi si creano e si revocano solo nell’app (sessione autenticata) — una chiave trapelata non può mai generare nuove chiavi. Il testo in chiaro non è più recuperabile dopo la creazione.

JSON o multipart, max 12 MB per documento (JPG, PNG, WEBP, PDF). L’inizio più rapido è l’endpoint tutto-in-uno:

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

• POST/api/v1/invoicesTutto in uno: dati di pagamento + QR, per i PDF anche il PDF timbrato.
• POST/api/v1/extractEstrai solo i dati di pagamento (niente QR, niente timbro).
• POST/api/v1/qrSolo QR — da dati di pagamento (senza estrazione) o da un documento.
• POST/api/v1/stampTimbra il GiroCode su un PDF.
• GET/api/v1/balanceConsulta credito di token, soglia di avviso e pacchetti (gratuito).
• POST/api/v1/checkoutCrea un link Stripe direttamente pagabile per un pacchetto di token.

Tutti i parametri, i formati di risposta e i codici di errore — incluso «try it out» direttamente nel browser: Apri il riferimento API interattivo

MCP (Model Context Protocol) è lo standard aperto con cui gli agenti IA (es. Claude) usano strumenti esterni. Il nostro server MCP consegna GiroSnap al tuo agente come cassetta degli attrezzi: fotografa una fattura, chiama uno strumento e riceve il GiroCode o il PDF timbrato direttamente nel suo flusso.

La via più semplice — Claude (web & desktop): Impostazioni → Connettori → «Aggiungi connettore personalizzato», chiamalo «GiroSnap» e incolla questo URL con la tua chiave. Lascia vuoti i campi OAuth:

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

Questo URL contiene la tua chiave API — trattalo come una password e non condividerlo.

Collegamento: inserisci l’URL del server e passa la tua chiave API nell’header Authorization — la stessa config funziona in Claude, negli agenti IDE e nei tuoi agenti SDK:

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

GIROSNAP_API_KEY è la tua normale chiave gsk_live_ dell’app — non esiste una chiave MCP separata.

Gli strumenti in dettaglio

• extract_invoice1 token/pagina

  Legge beneficiario, IBAN, BIC, importo (in centesimi) e causale da una foto di fattura o da un PDF. Serve solo se il tuo agente non può o non deve leggere la fattura da solo.

• create_payment_qr1 token/pagina

  Genera l’EPC/GiroCode scansionabile — come immagine, SVG e payload grezzo. Accetta dati di pagamento pronti (via più rapida, senza estrazione) o un documento.

• stamp_invoice_pdf1 token/pagina

  Timbra il GiroCode sulla fattura PDF — su spazio libero o su una pagina aggiunta; i PDF firmati e le e-fatture restano intatti e ricevono un foglio di accompagnamento.

• get_token_balancegratuito

  Credito di token attuale, indicatore di soglia, lista pacchetti e link di ricarica.

• buy_tokensgratuito

  Crea un link Stripe Checkout direttamente pagabile per un pacchetto di token — i token vengono accreditati automaticamente dopo il pagamento.

Trucco: se il tuo agente conosce già i dati di pagamento (la fattura l’ha vista, dopotutto), li passa semplicemente come payment a create_payment_qr o stamp_invoice_pdf — da noi non gira nessuna estrazione e la risposta è la più veloce.

Invia le fatture semplicemente per email — senza codice. Per le foto rispondiamo con il GiroCode nel corpo, i PDF tornano timbrati in allegato, anche più di uno per email.

1. Registra il tuo indirizzo mittente nell’app in «API & integrazioni».
2. Clicca il link di conferma nell’email — fatto.
3. Invia le fatture (PDF, JPG, PNG, WEBP) all’indirizzo di elaborazione e attendi la risposta.

Fino a 10 allegati per email, 12 MB ciascuno. La risposta indica sempre i token addebitati e rimanenti; quando il credito scarseggia, il link di ricarica è incluso.

L’app stessa è la quarta porta: carica, verifica, timbra — direttamente nel browser. E da qualunque porta arrivi una fattura, tutto viene registrato nella cronologia, con QR, PDF e costi consultabili in ogni momento.

Una regola, ovunque: 1 token per pagina (un QR da dati pronti conta come una pagina). I nuovi account partono con 10 token gratuiti; si ricarica via Stripe — nell’app, via POST /api/v1/checkout o con lo strumento buy_tokens.

Quando il credito scarseggia ti avvisiamo per email; a 0 l’elaborazione si ferma su tutte le porte (nessun servizio IA viene chiamato) e ogni risposta porta il link di ricarica.

Fatturazione equa: se l’elaborazione fallisce da parte nostra, il token viene rimborsato. Se il modello ha girato ma non ha potuto leggere la fattura, resta addebitato.

Ogni errore usa lo stesso envelope — un code leggibile dalla macchina, un message comprensibile e, in caso di token insufficienti (HTTP 402), il link di ricarica direttamente nella risposta:

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

Codici importanti: insufficient_tokens (402), unreadable (422, il modello ha girato — token addebitato), extraction_failed (502, rimborsato), unsupported_media (415), file_too_large (413). Catalogo completo nel riferimento interattivo.