API Velocissimo: credenziali, token e prima chiamata

Velocissimo espone delle API pubbliche che ti permettono di leggere i dati del tuo ristorante da un programma esterno: il gestionale contabile, un foglio Google, un tuo software, la dashboard del commercialista.

Le API sono in sola lettura: servono a estrarre dati, non a modificare configurazioni o inserire ordini.

Non serve autorizzazione preventiva né un contratto a parte: le credenziali te le generi da solo dal backoffice, in trenta secondi.

Cosa ti serve

• Un utente del backoffice Velocissimo.
• Nel menu Impostazioni → Integrazioni devi vedere le voci Credenziali API e Documentazione API. Se non le vedi, o se la pagina ti dice che il tuo utente non è collegato a un operatore abilitato, scrivi all'assistenza: va abilitato lato configurazione.
• Qualcuno che scriva il codice: uno sviluppatore, il fornitore del tuo gestionale, oppure un assistente AI (vedi l'articolo dedicato a Claude Code / Codex / Cursor).

Passo 1 — Genera le tue credenziali

1. Vai su Impostazioni → Integrazioni → Credenziali API.
2. Premi Genera le mie credenziali e conferma.
3. La pagina mostra due valori:
   • client_id — l'identificativo della tua applicazione. Resta sempre visibile.
   • client_secret — la password della tua applicazione. Viene mostrato una volta sola.
4. Copia subito il client_secret e mettilo al sicuro (un password manager, il file di configurazione del programma che userà le API).

Se hai perso il secret, o sospetti che qualcuno l'abbia visto, torna sulla stessa pagina e premi Rigenera secret: il client_id resta identico, il vecchio secret smette di funzionare immediatamente. Ricordati di aggiornare i programmi che lo stavano usando.

Le credenziali sono personali e legate al tuo profilo: le chiamate API vedono esattamente i negozi e i dati che vedi tu nel backoffice. Non devi passare nessun codice cliente o identificativo del ristorante: il token sa già chi sei.

Passo 2 — Prova subito, senza scrivere codice

Nel backoffice, Impostazioni → Integrazioni → Documentazione API apre il portale con il riferimento completo e sempre aggiornato di tutti gli endpoint, i parametri e gli esempi di risposta.

Da lì puoi provare gli endpoint direttamente dal browser (pulsante "Try it"): il tuo client_id è già precompilato, devi solo incollare il secret. È il modo più veloce per capire che dati ottieni, prima ancora di far scrivere una riga di codice a qualcuno.

Parti dall'endpoint /whoiam: non fa nulla di utile se non confermarti che le credenziali sono valide. È sempre il primo test da fare, anche in seguito quando qualcosa non funziona.

Passo 3 — L'indirizzo da dare a chi scrive il codice

La descrizione tecnica delle API (formato OpenAPI) è pubblica e vive a questo indirizzo:

https://api.velocissimo.app/v1/openapi.json

È l'unica cosa che devi passare al tuo sviluppatore, al fornitore del tuo gestionale o al tuo assistente AI: contiene la descrizione formale di ogni endpoint, parametro, campo di risposta e limite, ed è sempre allineata alle API vere. Non copiarla e non farne un riassunto a mano: manda l'indirizzo, così nessuno lavora su informazioni vecchie.

Le poche cose da sapere prima di leggerlo:

• Indirizzo base delle API: https://api.velocissimo.app/v1
• Autenticazione: OAuth 2.0 client credentials. Si scambiano client_id e client_secret per un access token temporaneo su https://api.velocissimo.app/oauth/token, e poi ogni chiamata viaggia con l'header Authorization: Bearer <token>. Il token scade: va rinnovato, non richiesto a ogni chiamata.

Regole di sicurezza (da rispettare sul serio)

• Il client_secret è una password. Non va scritto dentro un'app per smartphone, dentro il codice JavaScript di un sito, in una email, in una chat o in un repository pubblico: chi lo ottiene può leggere i dati del tuo ristorante.
• Va tenuto lato server, in un file di configurazione o in una variabile d'ambiente.
• Le chiamate devono partire dal tuo server, non dal browser dei tuoi clienti.
• Se hai il dubbio che sia uscito, rigeneralo: costa un click.

Se qualcosa non funziona

• La voce "Credenziali API" non compare, oppure la pagina dice che il tuo utente non è collegato a un operatore abilitato: contatta l'assistenza, va abilitato lato configurazione.
• La richiesta del token viene rifiutata: client_id o client_secret sbagliati. Attenzione ai secret rigenerati — il precedente smette di valere all'istante.
• Le chiamate rispondono 401: il token è assente, scaduto o non valido. Va richiesto un token nuovo.
• Le chiamate rispondono 400: c'è un parametro sbagliato. La risposta contiene sempre un campo message che spiega cosa non va: leggilo prima di aprire un ticket.
• I numeri non quadrano con la cassa: quasi sempre è il giorno o il negozio sbagliato nella richiesta, non un problema delle API. Riprova lo stesso periodo dal portale "Try it" e confronta.

Vedi anche

• Farsi sviluppare l'integrazione API da un assistente AI (Claude Code, Codex, Cursor)