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

Non serve un progetto di mesi per collegare Velocissimo a un altro sistema. Le nostre API pubbliche sono descritte da uno schema OpenAPI pubblico: un file che descrive in modo formale ogni endpoint, parametro, campo di risposta e limite. Gli assistenti AI che scrivono codice (Claude Code, OpenAI Codex, Cursor, GitHub Copilot e simili) sono fatti apposta per leggere un file del genere e produrre un'integrazione funzionante in poco tempo.

In pratica: dai al tuo assistente AI un indirizzo e poche regole, e lui scrive lo script.

L'unico indirizzo che devi ricordare

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

È pubblico: si apre senza login, quindi l'assistente AI può leggerlo da solo ed è sempre allineato alle API vere. Non serve che tu gli spieghi quali endpoint esistono, che parametri accettano o come sono fatte le risposte: trova tutto lì dentro. Non passargli riassunti scritti a mano: invecchiano, lo schema no.

Prima di iniziare

1. Genera le tue credenziali dal backoffice: Impostazioni → Integrazioni → Credenziali API (vedi l'articolo API Velocissimo: credenziali, token e prima chiamata).
2. Tieni client_id e client_secret a portata, ma non incollarli nella chat con l'AI: vedi la sezione sulla sicurezza più sotto.
3. Decidi in una frase cosa vuoi ottenere. "Voglio le vendite di ieri di tutti i negozi in un foglio Google, ogni mattina alle 6" è un obiettivo. "Voglio integrare le API" non lo è.

Il prompt da copiare

Apri il tuo assistente AI nella cartella del progetto e incolla questo testo, sostituendo solo l'ultima riga con quello che ti serve:

Devi scrivere un'integrazione con le API pubbliche di Velocissimo (piattaforma di food
delivery e gestione ristoranti).

Prima di scrivere qualsiasi riga di codice, scarica e leggi lo schema OpenAPI:
https://api.velocissimo.app/v1/openapi.json
E' pubblico, non serve autenticazione. E' l'unica fonte di verita' per endpoint, parametri,
formati, limiti e struttura delle risposte: non inventare campi o endpoint che non ci sono,
e rispetta i vincoli documentati nello schema (limiti di intervallo, formati data, ecc.).

Le uniche cose che non trovi nello schema:
- Le credenziali (client_id e client_secret) vanno lette da variabili d'ambiente
  VELOCISSIMO_CLIENT_ID e VELOCISSIMO_CLIENT_SECRET. Non scriverle mai nel codice,
  non stamparle nei log, non metterle nei file di esempio o nei commit.
- L'access token scade: tienilo in cache e rinnovalo quando serve, non richiederlo a ogni
  chiamata. Se una chiamata risponde 401, rinnova il token e riprova una volta sola.
- Il tenant e' gia' determinato dal token: non esiste nessun parametro "cliente" o
  "ristorante" da passare.
- Le API sono in sola lettura: se il mio obiettivo richiede di scrivere dati, dimmelo
  invece di inventare un endpoint.
- Se devo estrarre uno storico lungo, procedi in modo ordinato rispettando i limiti dello
  schema e lascia 1-2 secondi tra una chiamata e l'altra.

Procedi cosi':
1. Leggi lo schema e riassumimi quali endpoint userai e perche'.
2. Scrivi uno script minimo che chiama GET /whoiam e stampa l'esito, cosi' verifico subito
   che le credenziali funzionino.
3. Solo dopo che ti confermo che il passo 2 funziona, implementa il resto.

Quello che mi serve alla fine e': <DESCRIVI QUI IL TUO OBIETTIVO>

Esempi da mettere nell'ultima riga:

• "uno script Python che ogni notte scarica le vendite del giorno precedente di tutti i miei negozi e le salva in un file CSV per il commercialista";
• "un job che carica le vendite di ieri su un foglio Google, un negozio per scheda";
• "un endpoint del mio gestionale che, dato un giorno, restituisce totale incassato e totale per metodo di pagamento";
• "un report settimanale dei movimenti del borsello dei rider, con il saldo di contanti per rider".

Regole di sicurezza quando lavori con un'AI

• Non incollare mai il client_secret nella chat. Vale per qualsiasi assistente. Mettilo in un file .env sul tuo computer o sul server e di' all'AI di leggerlo da lì.
• Chiedi esplicitamente che le credenziali stiano in variabili d'ambiente e che il file che le contiene sia escluso dal versionamento (.gitignore).
• Se per sbaglio il secret è finito in una chat, in uno screenshot o in un repository: rigeneralo dal backoffice. Il vecchio smette di funzionare subito.
• Diffida del codice che chiama le API dal browser o da un'app per smartphone: le credenziali vanno usate lato server, altrimenti chiunque può leggerle.

Come farlo funzionare al primo colpo

• Parti da /whoiam. Se quello risponde, il problema non è più l'autenticazione: ti risparmia metà del tempo di debug.
• Guarda com'è fatta una risposta vera prima di scrivere il codice: nel backoffice, Impostazioni → Integrazioni → Documentazione API ti permette di provare gli endpoint dal browser, con il tuo client_id già precompilato.
• Fai testare l'AI su un solo giorno prima di lanciarla su mesi di storico.
• Verifica sempre la quadratura con la chiusura di cassa di quella giornata prima di considerare buona un'estrazione. Se non torna, di solito è un parametro sbagliato (giorno, negozio, intervallo), non un difetto delle API.
• Se l'AI inventa un endpoint o un campo che non esiste, rimandala allo schema: "rileggi https://api.velocissimo.app/v1/openapi.json, quella cosa non c'è".

Cosa le API non fanno

Sono in sola lettura. Non permettono di creare o modificare prodotti, prezzi, ordini, coupon o configurazioni. Se ti serve automatizzare una scrittura, parlane con l'assistenza: va valutato caso per caso.

Vedi anche

• API Velocissimo: credenziali, token e prima chiamata