OpenTabacchi

Chiavi API

Ogni chiamata a /v1 richiede una chiave otb_… legata al tuo account. La crei dal sito, la usi nel tuo software, la revochi quando non serve più.

Creare una chiave

  1. Accedi

    Richiedi il link di accesso da /login (vedi Accedere e registrarsi).

  2. Vai alla pagina del tuo account

    In Il tuo account trovi la sezione «Chiavi API» con le chiavi attive, la data di creazione e l'ultimo uso.

  3. Crea una chiave con un'etichetta

    L'etichetta serve solo a te per riconoscerla (ad esempio «cassa negozio» o «server di test»). Puoi avere al massimo 3 chiavi attive: per crearne una quarta devi prima revocarne una.

  4. Copia la chiave subito

    La chiave completa viene mostrata una sola volta. Il servizio ne conserva solo un'impronta e i primi caratteri: se la perdi, revocala e creane un'altra.

Usare la chiave

Inviala in ogni richiesta, in uno di questi due modi:

Authorization: Bearer otb_la_tua_chiave
X-Api-Key: otb_la_tua_chiave
esempio 
curl -H "Authorization: Bearer otb_la_tua_chiave" https://opentabacchi.org/v1/me

GET /v1/me conferma che la chiave funziona e mostra i contatori residui; costa una lettura come ogni altra chiamata in lettura.

Chiave mancante o non valida

L'API risponde 401 con WWW-Authenticate: Bearer e questo corpo:

{ "error": "invalid_api_key", "message": "Chiave API mancante o non valida." }

Lo stesso errore si ottiene con una chiave revocata o con un account bloccato: il servizio non distingue i casi.

Limiti condivisi tra le chiavi

I contatori (10 letture al giorno, 100 barcode all'ora) sono dell'account, non della singola chiave: tre chiavi non triplicano il budget. Servono a separare ambienti o installazioni, non ad aggirare i limiti. Dettagli in Limiti e uso corretto.

Buone pratiche

  • Conserva la chiave in una variabile d'ambiente o in un archivio segreti, mai nel codice sorgente o in un file distribuito con il software.
  • Una chiave per installazione server; non distribuire la stessa chiave a molte casse: il budget giornaliero è uno solo.
  • Revoca subito una chiave che potrebbe essere stata esposta. La revoca ha effetto immediato e non si annulla.
  • Se pensi che qualcuno abbia usato il tuo accesso al sito, usa «Chiudi tutte le sessioni» nella pagina del tuo account.