CORS (Cross-Origin Resource Sharing)

Invoicetronic API supporta CORS, il meccanismo standard del browser che consente a pagine web di effettuare richieste HTTP verso domini diversi da quello di origine. Questo significa che puoi chiamare l'API direttamente da JavaScript in esecuzione nel browser, ad esempio da una single-page application (SPA), un portale web o qualsiasi altra applicazione frontend.

Come funziona

Per impostazione predefinita, le richieste CORS sono bloccate. Per abilitarle, devi configurare esplicitamente le origini consentite per ogni API key che verrà usata dal browser.

Quando un browser effettua una richiesta cross-origin verso l'API, invia prima una richiesta preflight (metodo OPTIONS) per verificare che il server consenta la chiamata. L'API verifica che l'origine della richiesta sia presente nella lista delle origini consentite per la chiave utilizzata. Se l'origine è autorizzata, il browser procede con la richiesta vera e propria; in caso contrario, la richiesta viene rifiutata.

Configurazione delle origini

Le origini consentite si configurano dalla Dashboard, nella sezione Chiavi. Puoi impostare le origini sia per la chiave primaria che per ogni chiave con restrizioni.

Sono supportati due formati:

Formato	Esempio	Corrisponde a
Origine esatta	https://app.example.com	Solo https://app.example.com
Wildcard sottodomini	*.example.com	sub.example.com, a.b.example.com, ma non example.com

Consiglio

Configura solo le origini strettamente necessarie. Lascia vuota la lista per bloccare completamente l'accesso da browser (impostazione predefinita e consigliata per le chiavi che non devono essere usate dal frontend).

Esposizione della API key

Attenzione

Quando chiami l'API da JavaScript nel browser, la tua API key è inevitabilmente esposta. Chiunque può vederla ispezionando il codice sorgente della pagina o le richieste di rete tramite i DevTools del browser. Non esiste modo di nascondere una API key in un'applicazione frontend.

Questo è un rischio concreto: una chiave esposta può essere copiata e usata al di fuori della tua applicazione. La configurazione delle origini CORS non è una misura di sicurezza sufficiente da sola, perché limita solo le richieste provenienti da browser — un attaccante può comunque usare la chiave da un client non-browser (es. curl, Postman, script server-side).

Approccio consigliato: usa un backend

Best practice

Quando possibile, chiama l'API dal tuo backend, non dal browser. Questo è l'approccio più sicuro in assoluto: la chiave rimane sul server e non è mai esposta al client.

L'architettura consigliata è a due livelli:

1. Frontend (browser) — comunica con il tuo backend, non direttamente con l'API Invoicetronic
2. Backend (server) — chiama l'API con la chiave primaria, al sicuro dal client

Con questo approccio non è necessario configurare origini CORS, perché le chiamate partono dal server.

Se non puoi usare un backend

Se la tua applicazione non dispone di un backend (ad esempio una SPA statica o un sito generato), puoi chiamare l'API direttamente dal browser. In questo caso:

1. Crea una chiave con restrizioni dedicata con i permessi minimi necessari:

   • Sola lettura se l'applicazione deve solo consultare dati (fatture, log, stato)
   • Invio se deve anche inviare fatture
   • Restrizione per azienda per limitare l'accesso ai soli documenti pertinenti

2. Configura le origini CORS per quella chiave dalla Dashboard, specificando solo i domini da cui la tua applicazione effettuerà le chiamate

Le chiavi con restrizioni e le origini CORS insieme riducono il danno in caso di compromissione, ma non lo eliminano: la chiave resta utilizzabile da client non-browser. Monitora l'uso delle tue chiavi e revocale tempestivamente in caso di sospetta compromissione.

Non usare mai la chiave primaria nel browser

La chiave primaria ha accesso completo a tutte le risorse del tuo account. Esporla in un'applicazione frontend è un rischio grave. Crea sempre una chiave con restrizioni dedicata e riserva la chiave primaria per il backend.