Endpoint REST sincrono per studi e aziende che vogliono integrare le conversioni nei propri gestionali. Stesse 23 banche del web, output JSON + Excel + CSV in un'unica risposta. Incluso nel piano Studio (19,90 €/mese, fino a 200 documenti al mese).
Salviamo solo l'hash della chiave (HMAC-SHA256 con un segreto che non sta nel database), mai la chiave in chiaro. La vedi una sola volta, alla creazione: non si può recuperare dopo. Ogni chiave ha un nome e i suoi permessi (per esempio conversions:write) e si revoca in ogni momento dall'area riservata.
Limiti per chiave
Ogni chiave ha un proprio limite di 100 richieste al minuto, più un limite per indirizzo IP. Le chiamate oltre soglia ricevono HTTP 429. Se al tuo studio serve un limite diverso, scrivici.
Audit log e conteggio documenti
Ogni chiamata viene tracciata senza dati personali nei log (no IBAN, no importi, no descrizioni). Una conversione riuscita conta come uno dei 200 documenti del mese; se la conversione non riesce (nessun movimento trovato o lettura troppo incerta) l'API risponde 422 e il documento non viene conteggiato.
L'endpoint
Un solo endpoint sincrono: invii il PDF, ricevi i dati. Autenticazione con la chiave del piano Studio via header Bearer.
POST/api/v1/conversions
Endpoint SINCRONO: invii il PDF (raw application/pdf o multipart con campo file, fino a 10 MB e 200 pagine) con header Authorization: Bearer eccx_... e ricevi nella stessa risposta il risultato completo: bankDetected, pageCount, confidenceScore e l'array rows dei movimenti, più csv e xlsxBase64 pronti da salvare. Nessun polling, nessun job_id.
Domande frequenti sull'API
L'API è già disponibile?
Sì. L'endpoint POST /api/v1/conversions è attivo e sincrono. Per ottenere una chiave serve il piano Studio: la generi dalla tua area riservata (sezione Chiavi API), la vedi in chiaro una sola volta e la usi come Authorization: Bearer. Le chiavi hanno permessi (es. conversions:write) e si possono revocare in qualsiasi momento.
Quanto costa una chiamata API?
L'API è inclusa nel piano Studio (19,90 €/mese). Ogni conversione riuscita conta come un documento dei 200 del mese, indipendentemente dal numero di pagine e anche per le scansioni (lette in automatico fino a 40 pagine per documento). Se la conversione non riesce (nessun movimento trovato o lettura troppo incerta) non viene conteggiata. Finiti i documenti del mese l'API risponde 402 fino al 1° del mese successivo; nel frattempo sul sito ogni documento si scarica a 1 €.
Quali formati restituisce l'API?
Un'unica risposta JSON che contiene sia i dati strutturati (array rows con data operazione, data valuta, descrizione, entrate, uscite, saldo e uno score di confidenza per riga) sia il file già pronto: csv (UTF-8, separatore punto e virgola, virgola decimale) e xlsxBase64. Non serve una seconda chiamata per scaricare l'output.
Dove vengono elaborati i dati?
Il PDF inviato via API non viene salvato sui nostri server: è letto in memoria durante la richiesta e scartato al termine, esattamente come dal web. Le scansioni e i formati che il lettore non riconosce vengono letti da Claude, il modello di intelligenza artificiale di Anthropic, o di riserva da Cloudflare Workers AI; nessuno dei due usa il documento per addestrare modelli. Il database dei metadati è in Unione Europea (region eu-central-1). Il DPA è pubblicato su /dpa e si applica senza firma a chi attiva lo Studio; se ti serve una copia firmata, chiedicela.
L'API supporta tutte le 23 banche del web?
Sì. L'API condivide gli stessi parser dedicati (Intesa Sanpaolo, UniCredit, BancoPosta, Fineco, BPER, BNL, MPS, Banco BPM, Mediolanum, Crédit Agricole, Credem, ING, Sella, Revolut, N26, Wise, Hype, Satispay, Trade Republic, Vivid Money, buddybank e altre) e la stessa strategia generica per banche non ancora coperte.
Posso integrare l'API in TeamSystem, Zucchetti o altri gestionali?
Sì. L'export JSON è pensato proprio per integrazioni gestionali: ogni riga porta data contabile, data valuta, descrizione, entrate, uscite, saldo e una colonna confidence (0-1) per filtrare le righe da revisionare manualmente prima dell'import.