Vai al contenuto

Chiavi con restrizioni

Quando ti registri su Invoicetronic ricevi una coppia di chiavi primarie (test e live) con accesso completo a tutte le risorse API. Le chiavi con restrizioni ti permettono di creare chiavi aggiuntive, ideali per gestire integrazioni multiple o delegare l'accesso in modo sicuro.

Creazione e gestione

Le chiavi con restrizioni si creano e gestiscono dalla Dashboard, nella sezione Chiavi, oppure via API con l'endpoint /subkey. Per ogni chiave puoi configurare:

  • Descrizione — un nome identificativo per ricordare lo scopo della chiave
  • Stato — attiva o disattiva la chiave in qualsiasi momento
  • Aziende — limita l'accesso a specifiche aziende, oppure lascia vuoto per consentire l'accesso a tutte
  • Permessi — in Dashboard scegli un preset (vedi sotto), via API imposti il livello per ogni risorsa
  • Origini CORS — configura le origini consentite per le richieste da browser (vedi la guida CORS)

Ogni chiave con restrizioni genera automaticamente una coppia di chiavi test e live, proprio come la chiave primaria. Le chiavi si vedono una sola volta, al momento della creazione: vedi Visibilità e rigenerazione.

Preset di permessi

Ogni chiave con restrizioni ha un preset di permessi che determina quali operazioni può eseguire:

Preset Descrizione
Accesso completo Lettura e scrittura su tutti gli endpoint. Equivalente alla chiave primaria (eccetto la gestione delle chiavi con restrizioni stesse)
Sola lettura Solo operazioni di lettura (GET) su tutti gli endpoint. Ideale per integrazioni di monitoraggio o reporting
Invio Permessi di lettura su tutti gli endpoint, più la possibilità di inviare fatture. Ideale per integrazioni che devono emettere documenti ma non gestire altre risorse

Nessun preset include la gestione delle chiavi: una chiave con restrizioni non può creare, modificare o eliminare altre chiavi. Via API, al posto dei preset imposti i permessi risorsa per risorsa (vedi Permessi).

Restrizione per azienda

Se la tua chiave primaria gestisce più aziende, puoi creare chiavi con restrizioni che hanno accesso solo ad alcune di esse. Questo è utile quando:

  • Hai clienti diversi e vuoi dare a ciascuno una chiave che accede solo ai propri documenti
  • Vuoi isolare gli ambienti di lavoro tra reparti o integrazioni diverse
  • Devi delegare l'accesso a collaboratori esterni limitandolo alle aziende pertinenti

Se non selezioni alcuna azienda, la chiave avrà accesso a tutte le aziende del tuo account, comprese quelle create in seguito.

Una chiave limitata ad alcune aziende vede solo i dati di quelle aziende: fatture inviate e ricevute, aggiornamenti di stato, esportazioni, webhook e relativo storico, eventi del log (più le proprie chiamate). Può gestire solo webhook associati a una delle sue aziende: un webhook senza azienda riceverebbe gli eventi di tutto l'account.

Gestione via API

Con la chiave primaria puoi gestire le chiavi con restrizioni direttamente dall'API, senza passare dalla Dashboard. È la strada per gli integratori che fanno l'onboarding dei propri clienti in modo automatico.

Metodo Endpoint Descrizione
GET /subkey Elenco delle chiavi con restrizioni, paginato. Filtri: company_id, active, q (descrizione)
GET /subkey/{id} Dettaglio di una chiave
POST /subkey Crea una chiave. La risposta contiene test_key e live_key
PUT /subkey Aggiorna descrizione, stato, permessi, aziende e origini CORS. Sostituisce tutti i campi: permissions, company_ids o cors_origins omessi valgono "nessuno"
DELETE /subkey/{id} Elimina la chiave, che smette subito di funzionare
POST /subkey/{id}/roll Rigenera le chiavi (vedi Visibilità e rigenerazione)

Gli endpoint rispondono solo alla chiave primaria: una chiave con restrizioni riceve 403 con code = subkey_not_allowed.

Onboarding di un cliente in due chiamate

Crea l'azienda del cliente, poi una chiave limitata a quell'azienda:

# 1. Crea l'azienda (chiave primaria)
curl -X POST https://api.invoicetronic.com/v1/company/ \
  -u ik_live_YOUR-API-KEY: \
  -H "Content-Type: application/json" \
  -d '{"vat": "IT01234567891", "fiscal_code": "01234567891", "name": "Studio Rossi Srl"}'
# → { "id": 42, ... }

# 2. Crea la chiave con restrizioni limitata all'azienda
curl -X POST https://api.invoicetronic.com/v1/subkey/ \
  -u ik_live_YOUR-API-KEY: \
  -H "Content-Type: application/json" \
  -d '{
        "description": "Studio Rossi Srl",
        "company_ids": [42],
        "permissions": {"company": "Read", "send": "Write", "receive": "Read", "update": "Read", "status": "Read"}
      }'
# → { "id": 318, "test_key": "ik_test_…", "live_key": "ik_live_…", ... }

Consegna al cliente le chiavi della risposta: potrà operare solo sulla propria azienda. Alcune cose da sapere:

  • se la partita IVA è già registrata su un altro account, il passo 1 fallisce con code = company_already_registered: il trasferimento si richiede al supporto;
  • per ricevere le fatture passive, il cliente deve comunque registrare il codice destinatario sul portale dell'Agenzia delle Entrate (vedi Agenzia delle Entrate);
  • le operazioni fatte con le chiavi con restrizioni usano i crediti del tuo account.

Permessi

Via API i permessi si impostano per risorsa, nell'oggetto permissions. Una risorsa assente vuol dire nessun accesso.

Risorsa Read Write
company elenco e dettaglio delle aziende anche creazione, modifica ed eliminazione
send elenco e dettaglio delle fatture inviate anche invio e validazione delle fatture
receive elenco e dettaglio delle fatture ricevute anche eliminazione
webhook elenco e dettaglio dei webhook anche creazione, modifica ed eliminazione
update, log, webhookhistory, export, status lettura —

Regole:

  • ogni permesso non può superare quello della chiave primaria (400, code = permission_exceeds_parent);
  • alla creazione, se ometti permissions la chiave riceve i permessi della chiave primaria, copiati in quel momento: se poi cambiano quelli della primaria, la chiave non li segue;
  • gli id in company_ids devono appartenere al tuo account (400, code = company_not_found);
  • un account può avere al massimo 1.000 chiavi con restrizioni (400, code = subkey_limit_reached).

Visibilità e rigenerazione

Per sicurezza, le chiavi di una chiave con restrizioni (sia test sia live) si vedono una sola volta: nella risposta della creazione, in Dashboard subito dopo averla creata, e dopo ogni rigenerazione. Non sono più leggibili in seguito: copiale e conservale subito in un luogo sicuro.

Se perdi una chiave, o sospetti che sia stata esposta, rigenerala: dalla Dashboard con il pulsante Rigenera, oppure via API con POST /subkey/{id}/roll. La chiave con restrizioni mantiene id, permessi, aziende e origini CORS; cambiano solo le chiavi test e live.

Le chiavi sostituite smettono di funzionare subito. Per migrare senza interruzioni puoi tenerle valide ancora per un po': in Dashboard con Mantieni valide le chiavi attuali per 24 ore, via API con expires_in_hours (da 1 a 168 ore). Nel frattempo funzionano sia le vecchie sia le nuove.

Chiavi create prima di questa modifica

Le chiavi con restrizioni create prima dell'introduzione della visibilità unica restano visibili in Dashboard come prima. La chiave primaria resta sempre visibile.

Casi d'uso

  • Integrazione con accesso minimo: crea una chiave di sola lettura per un sistema di reportistica che deve solo consultare fatture e log
  • Collaboratore esterno: crea una chiave temporanea limitata a specifiche aziende per un consulente o sviluppatore
  • Microservizio dedicato: assegna a ogni servizio della tua architettura una chiave con i soli permessi necessari
  • Sviluppo e test: crea chiavi di test con permessi ridotti per i tuoi ambienti di sviluppo
  • Applicazione frontend/browser: se chiami l'API da JavaScript nel browser, la chiave è inevitabilmente visibile nel codice client. Usa una chiave con restrizioni con i permessi minimi necessari e configura le origini CORS consentite dalla Dashboard. Vedi la guida CORS per approfondire
  • ISV con Desk: assegna a ogni cliente una chiave con restrizioni limitata alla sola azienda gestita dal cliente, e fagli usare Desk direttamente con quella chiave. Ogni cliente avrà accesso esclusivamente ai propri documenti, in totale autonomia e sicurezza

Postazione Desk

Una postazione Desk abilita l'accesso a Desk Cloud per una specifica chiave API live. Le postazioni sono abbonamenti indipendenti, ognuno con il proprio ciclo di fatturazione.

Le chiavi sandbox (test) non richiedono una postazione: funzionano in Desk gratuitamente, senza limiti di tempo. Usale per provare Desk o per sviluppo e test.

Come funziona

  1. Nella sezione Chiavi della Dashboard, clicca Abilita Desk su qualsiasi chiave live (primaria o con restrizioni)
  2. Completa il checkout
  3. La chiave è ora collegata a una postazione Desk. Il tuo cliente (o tu stesso) può registrarsi su Desk, inserire la chiave e iniziare a usarlo immediatamente

Gestione delle postazioni

Dalla pagina Chiavi puoi:

  • Abilita Desk — acquistare una nuova postazione per una chiave
  • Sposta Desk — riassegnare una postazione esistente a un'altra chiave (stesso abbonamento, nessun nuovo checkout)
  • Disabilita Desk — cancellare l'abbonamento della postazione

Ogni postazione è legata a una singola chiave (1:1). Una chiave può avere al massimo una postazione, e una postazione è assegnata esattamente a una chiave alla volta.

Per gli ISV

Se sei un ISV che serve più clienti:

  1. Crea una chiave con restrizioni per ogni cliente (con limitazioni per azienda per l'isolamento), dalla Dashboard o via API
  2. Acquista una postazione Desk per ogni chiave
  3. Condividi la chiave con il tuo cliente — lui si registra su Desk e la inserisce nel suo profilo

Controlli l'accesso centralmente: disabilita o sposta le postazioni in qualsiasi momento dalla Dashboard. I tuoi clienti non si occupano della fatturazione — gestisci tutto tu.

Sicurezza

Le chiavi con restrizioni seguono il principio del privilegio minimo: assegna sempre i permessi strettamente necessari. Puoi disattivare o eliminare una chiave in qualsiasi momento, dalla Dashboard o via API, con effetto immediato, e rigenerarla se è stata esposta.

Consiglio

Evita di condividere la tua chiave primaria. Crea invece chiavi con restrizioni dedicate per ogni integrazione o collaboratore, così potrai revocare l'accesso singolarmente senza impattare le altre integrazioni.