Guida rapida

La prima risposta in due minuti con un token di prova, poi il percorso completo con OAuth 2.0.

Due strade

Per arrivare a un token ci sono due strade, e ti servono entrambe:

Token di prova: un clic nella console e interroghi il tuo locale di prova. Ideale per conoscere l'API: bastano due minuti.
OAuth 2.0: è così che più avanti ogni locale collegherà la tua app. Il titolare accede, dà il consenso e la tua app riceve i token proprio per quel locale.

Ti basta un account Flavoso gratuito, senza un locale tuo e senza abbonamento. Gli esempi funzionano con curl, Node.js dalla versione 18, Python 3 con requests e PHP dalla versione 8.

Con l'assistente di configurazione

La via più rapida passa dalla console stessa. Se non hai ancora un'app, la console apre l'assistente di configurazione, che in cinque passi ti porta alla prima risposta. Finché non è tutto fatto, lo trovi a sinistra in Configurazione.

1
Crea l'app
Nome, dove gira (sul tuo server o su un dispositivo nel locale) e cosa può fare. L'assistente mostra il client secret una sola volta.
Console › Configurazione
2
Crea il locale di prova
Un ristorante per provare, con menu di esempio e tavoli.
3
Crea un token di prova
Accesso al locale di prova senza il flusso OAuth.
4
Prima richiesta
GET /me con il token, dal tuo codice o direttamente nel browser. L'assistente riconosce la richiesta appena arriva a Flavoso e mostra stato e risposta.
5
Ricevi gli eventi
Via webhook al tuo server, oppure recuperati con GET /events. Un ordine di prova mostra che arrivano.

Le sezioni qui sotto ripercorrono gli stessi passi a mano, con il codice per ciascuno.

Creare l'app e il locale di prova

1
Crea un account
Con «Account sviluppatore gratuito» nella pagina iniziale di questa documentazione. Se hai già un account Flavoso, ti basta accedere.
app.flavoso.com
2
Crea l'app
Nella console, sotto App, scegli «Nuova app»: nome, tipo di app (riservata per le app con un proprio server), un URI di reindirizzamento e i permessi di cui la tua app ha bisogno. Accetta le condizioni per sviluppatori. Il client secret viene mostrato una sola volta: copialo subito.
Console › App › Nuova app
3
Crea il locale di prova
Un clic crea il tuo locale di prova: un ristorante gratuito per provare, con menu di esempio e tavoli. Tutte le tue app lo condividono.
Console › Locale di prova

Per la guida rapida bastano i permessi orders:write, menu:write e store:write. Tutti i permessi sono elencati in Permessi.

Strada 1: token di prova

Nelle Credenziali della tua app, «Crea token di prova» rilascia un token di accesso e un token di aggiornamento per il tuo locale di prova, entrambi con i permessi della tua app. Il token di accesso vale un'ora, quello di aggiornamento 180 giorni dall'ultimo utilizzo e, come ogni altro, viene sostituito a ogni utilizzo. La console li mostra entrambi una sola volta. In questo modo nasce il collegamento tra l'app e il locale di prova, esattamente come con un consenso.

Imposta il token come variabile d'ambiente ACCESS_TOKEN e chiama GET /me, cioè il collegamento stesso:

# The test token from the developer console (valid for up to one hour)
export ACCESS_TOKEN="flv_at_..."

curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La risposta indica il locale, i permessi concessi e livemode. Nel locale di prova livemode è sempre false:

Risposta

{
  "object": "connection",
  "id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "livemode": false,
  "app": {
    "client_id": "flv_app_...",
    "name": "Example POS"
  },
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Test restaurant",
    "slug": "test-k7q2m9",
    "timezone": "Europe/Berlin",
    "currency": "EUR",
    "country": "DE"
  },
  "scopes": [
    "orders:write",
    "menu:write",
    "store:write",
    "reports:read"
  ],
  "plan": "pro",
  "rate_limit": {
    "limit": 120,
    "window_seconds": 60
  },
  "created_at": "2026-10-04T17:40:00.000Z"
}

Accettare il primo ordine

1
Crea un ordine di prova
«Crea ordini di prova» crea nel locale di prova un ordine vero, come se lo avesse fatto un cliente. Compare nell'API e attiva i webhook.
Console › Locale di prova › Ordini
2
Recupera gli ordini aperti
GET /orders?status=pending restituisce gli ordini in attesa del locale.
3
Accetta
POST /orders/{id}/accept lo accetta, come un clic nella dashboard. Con Idempotency-Key ripetere la richiesta non comporta rischi.

# The orders waiting for the restaurant ("Create test orders" in the console creates one)
curl "https://api.flavoso.com/v1/orders?status=pending" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Accept one. The same key gives the same result, so a retry is safe.
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID"

Nella console, in Locale di prova › Ordini, l'ordine risulta poi accettato, e il registro della tua app mostra la richiesta con la risposta.

Strada 2: collegare con OAuth

Un locale reale non ti consegna un token. È il suo titolare a collegare la tua app, e per questo devi integrare il flusso OAuth 2.0 con PKCE. Puoi provarlo con il tuo locale di prova prima che lo veda qualcun altro.

1
Genera state e PKCE
Genera un code_verifier e uno state casuali e ricava da questi la code_challenge (SHA-256, Base64URL).
2
Reindirizza al consenso
Manda il browser a https://app.flavoso.com/oauth/authorize. Lì accedi con il tuo account, scegli il locale di prova e premi «Collega».
3
Scambia il codice con i token
Flavoso reindirizza al tuo URI di reindirizzamento con code, state e iss. Confronta state, poi scambia il codice entro 10 minuti su https://api.flavoso.com/oauth/token.
4
Invia le richieste
Chiama l'API con l'access_token della risposta, esattamente come con il token di prova.

# 1. PKCE: a random code_verifier, its S256 code_challenge and a random state
CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

# 2. Open this address in a browser, sign in, pick your test restaurant, press "Connect".
#    http://127.0.0.1:8080/callback must be one of your app's redirect URIs. For a
#    confidential app such a loopback address only connects your test restaurant.
echo "https://app.flavoso.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&scope=orders%3Awrite&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# 3. The browser lands on http://127.0.0.1:8080/callback?code=...&state=...&iss=...
#    Nothing has to listen there. Compare state with $STATE, then copy the code (valid 10 minutes, once).
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  --data-urlencode redirect_uri=http://127.0.0.1:8080/callback \
  -d code_verifier=$CODE_VERIFIER

# 4. First request with the access_token from the response
curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La risposta dell'endpoint del token:

Risposta

{
  "access_token": "flv_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "flv_rt_...",
  "scope": "orders:write menu:write store:write reports:read",
  "connection_id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Pizzeria Example",
    "slug": "pizzeria-example"
  }
}

Trovi tutto su tipi di client, URI di reindirizzamento, errori e consenso in Autenticazione.

Rinnovare il token

Un token di accesso vale un'ora. Dopo, con il token di aggiornamento ottieni una nuova coppia. Ogni rinnovo porta un nuovo token di aggiornamento, e solo quello nuovo resta valido: salvalo prima di usare il nuovo token di accesso.

# Access tokens last one hour. The response carries a NEW refresh token: store it.
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

Come si legano rotazione, periodo di tolleranza e revoca è spiegato in Autenticazione.

Come proseguire

Configura i webhook, così i nuovi ordini arrivano da soli. Una cassa senza indirizzo pubblico può invece recuperare gli eventi.
Per una cassa: la guida all'integrazione cassa dalla A alla Z.
Gestisci bene gli errori: Errori, Idempotenza, Limiti di richieste.
Quando tutto funziona: Revisione ed elenco delle app.

Qualcosa non è chiaro? Scrivi a support@flavoso.com indicando l'identificativo di X-Request-Id. Così troviamo la tua richiesta nel registro.