API: autenticazione, endpoint e prove operative
Manuale delle API pubbliche di ISP Billing: chiavi, permessi, paginazione, risorse, errori e console interattiva.
Ultimo aggiornamento: 2026-08-19
Scopo e perimetro
Le API pubbliche collegano sistemi esterni a clienti, gruppi, campi personalizzati, fatture, pagamenti, catalogo e istanze servizi, ISPRadius 2.0, magazzino e attività. Ogni famiglia è descritta da una specifica OpenAPI consultabile nella console ufficiale.
L’esistenza di un endpoint non concede automaticamente l’accesso: modulo attivo, chiave valida, IP sorgente e permesso specifico vengono valutati separatamente.
Creare una chiave API
Apri Impostazioni → API → API Keys e seleziona Crea nuova API Key. Assegna un nome che identifichi applicazione e ambiente, inserisci gli IP consentiti separati da virgola quando l’integrazione ha indirizzi stabili e abilita soltanto i permessi necessari.
La prova ha creato “Documentazione API - sola lettura” con il solo permesso di lettura clienti. Il segreto non compare in nessuna schermata pubblicata.
Segreto, rigenerazione ed eliminazione
Il valore segreto viene mostrato soltanto dopo creazione o rigenerazione. Copialo subito in un gestore sicuro: l’elenco conserva API ID, nome, whitelist e account proprietario, ma non rende nuovamente leggibile la chiave.
Rigenera invalida il valore precedente; Modifica aggiorna nome, IP e permessi; Elimina revoca definitivamente l’accesso. Pianifica la rotazione evitando interruzioni e non registrare il segreto in log, ticket o repository.
Header di autenticazione
Ogni richiesta usa Authorization: Bearer {api_id}:{api_key}. API ID e segreto sono separati da due punti; la parola Bearer appartiene all’header, non al valore inserito nella finestra Authorize di Swagger, che la aggiunge automaticamente.
Un’integrazione deve usare HTTPS, conservare la chiave lato server e inviare Accept: application/json. Non incorporare mai la credenziale in JavaScript pubblico o URL.
Permessi disponibili
I permessi osservati separano lettura e scrittura per clienti, gruppi e campi custom; lettura ed eliminazione fatture; lettura pagamenti; lettura e gestione di articoli, categorie, marchi e carichi; lettura giacenze; lettura attività; lettura e creazione istanze servizi; lettura account/stato e gestione account ISPRadius; lettura profili Radius.
Una chiave con permesso di lettura clienti non può creare o cancellare clienti. La regola del privilegio minimo riduce il danno di una perdita e rende più chiara la responsabilità dell’integrazione.
Whitelist IP e account proprietario
Se la whitelist contiene valori, l’indirizzo sorgente deve coincidere con uno di essi; in caso contrario la richiesta viene rifiutata. Inserisci indirizzi pubblici effettivi, non IP locali del server chiamante. Una whitelist vuota non sostituisce i permessi.
La chiave è legata all’ISP e all’account amministrativo che l’ha creata. Revocare o cambiare un’integrazione deve quindi includere controllo di proprietario, nome, permessi e sistemi che la utilizzano.
Console interattiva Swagger
Ogni voce dell’indice apre una console con server, schema, Authorize, endpoint, parametri, corpi richiesta, risposte ed esempi. Usa Try it out soltanto nel tenant e con la chiave corretti: i POST di creazione, aggiornamento o eliminazione sono operazioni reali.
La pagina Clienti espone venti operazioni tra anagrafica, rivenditori, metodi di pagamento e recapiti aggiuntivi.
Risposte ed errori
Le risposte applicative usano in genere status: OK con data, oppure status: ERROR con un messaggio. Le specifiche descrivono gli esiti di autenticazione, permesso o whitelist, validazione, risorsa non trovata ed errore interno previsti dai singoli endpoint.
Il client deve controllare insieme status HTTP, Content-Type e corpo, perché una risposta trasportata correttamente può comunque contenere un errore applicativo. Inviare soltanto i parametri necessari, validare il JSON prima di elaborarlo e registrare identificativo della richiesta ed esito senza conservare segreti o record completi.
Paginazione e filtri
Le liste clienti, gruppi, campi custom, fatture, pagamenti, istanze servizi e account Radius usano paginazione numerata; altre famiglie, in particolare diverse risorse di magazzino e attività, dichiarano cursor pagination. Non riutilizzare automaticamente gli stessi parametri.
I filtri complessi possono essere codificati secondo la specifica. Tratta i valori mostrati dalla console come esempi da valutare, non come parametri obbligatori. Conserva cursore o numero pagina restituito e applica limiti per evitare scansioni incontrollate.
Clienti: lettura e gestione
GET /api/modules/crm/customers restituisce l’elenco paginato; GET .../{customer_id} il dettaglio; GET .../resellers i rivenditori disponibili. I POST create, update e delete modificano l’anagrafica.
Prima di creare, cerca duplicati; prima di aggiornare, recupera il record corrente; prima di eliminare, valuta servizi, documenti e storico collegati. Password e identificativi gateway restituiti non devono finire nei log dell’integrazione.
Clienti: indirizzi, telefoni, e-mail e pagamenti
Per ogni cliente sono disponibili GET degli indirizzi aggiuntivi, numeri aggiuntivi, e-mail aggiuntive e metodi di pagamento. Ogni tipo di recapito dispone dei relativi POST di creazione, aggiornamento ed eliminazione.
POST .../{customer_id}/payment-method-setup-link genera un collegamento di autorizzazione: non restituisce una carta da salvare nel sistema chiamante e non dimostra che il cliente abbia completato il flusso.
Gruppi cliente
GET /api/modules/crm/customer-groups elenca i gruppi, il percorso con {group_id} apre il dettaglio e i POST create, update, delete ne gestiscono il ciclo di vita.
Un gruppo può influenzare classificazione e processi downstream. Prima della cancellazione verifica clienti associati e regole che usano quell’identificativo.
Campi personalizzati cliente
La famiglia /api/modules/crm/customer-custom-fields offre elenco, dettaglio, creazione, aggiornamento ed eliminazione. Tipo, opzioni, obbligatorietà e significato del campo devono restare coerenti con l’interfaccia amministrativa.
Non cambiare tipo a un campo popolato senza un piano di migrazione; non usare campi custom per segreti o dati che richiedono protezioni non previste.
Fatture e pagamenti
GET /api/modules/invoices/invoices restituisce l’elenco, il percorso con {invoice_id} il dettaglio e POST .../delete elimina il documento secondo i controlli applicativi. GET /api/modules/invoices/payments elenca i pagamenti registrati.
Un pagamento restituito deve essere riconciliato con documento, importo, data, modalità e riferimento. La sola presenza di un gateway o di un checkout non equivale a un pagamento registrato.
Catalogo servizi e istanze
GET /api/modules/subscription-services/services elenca il catalogo ISP. Le istanze dispongono di elenco, dettaglio e POST .../create per la creazione “lite”.
L’istanza deve riferirsi a cliente e servizio validi e rispettare prerequisiti del modulo. La creazione commerciale non garantisce provisioning, attivazione tecnica o avvio corretto della fatturazione.
ISPRadius 2.0
Gli account Radius offrono elenco, dettaglio, creazione, aggiornamento, eliminazione, disconnessione, sospensione, attivazione, terminazione e GET dello stato con traffico dell’ultima sessione attiva. I profili offrono elenco e dettaglio con attributi Radius.
Disconnect agisce sulla sessione corrente; suspend, activate e terminate modificano lo stato dell’account. Sono azioni operative distinte e richiedono permesso di gestione, identificativo verificato e controllo dell’esito sul sistema Radius.
Magazzino: articoli, categorie e marchi
Articoli offre elenco, dettaglio, creazione, aggiornamento ed eliminazione. Categorie e marchi offrono elenco cursor, dettaglio, creazione e aggiornamento. Codice, barcode, categoria, marchio, unità, prezzi e IVA devono seguire le regole del catalogo.
Non creare duplicati per aggirare una categoria non visibile. Le anomalie dell’interfaccia e le API sono ambiti distinti e vanno investigate separatamente.
Magazzino: giacenze e carichi
Giacenze espone elenco cursor e dettaglio. Carichi espone elenco, dettaglio con testata e righe, creazione, aggiornamento delle righe esistenti ed eliminazione/annullamento.
Una movimentazione incide su quantità e tracciabilità: usa una causale, una sede e righe coerenti, conserva l’identificativo restituito e verifica il saldo dopo la scrittura.
Attività e team
Attività offre elenco cursor e dettaglio; Team offre elenco cursor ed è pubblicato anche come specifica separata. Le risorse collegano pianificazione, cliente, operatori e squadra ma le API pubbliche osservate sono di sola lettura.
Usa filtri temporali e cursori per sincronizzazioni incrementali e non confondere attività cliente con task personali o ticket.
Verificare una richiesta in lettura
Autorizzare nella console una chiave con il solo permesso necessario, rimuovere i parametri di esempio non richiesti e inviare una GET su una risorsa leggibile. Controllare insieme HTTP 200, Content-Type JSON, status: OK, struttura dei dati e paginazione.
Non pubblicare la risposta completa quando contiene recapiti o identificativi. Per documentare l’esito sono sufficienti stato, schema, numero di elementi e identificativo di correlazione privo di dati personali.
Checklist per un’integrazione
- Creare una chiave diversa per applicazione e ambiente
- Concedere solo i permessi necessari
- Configurare la whitelist quando possibile
- Conservare il segreto lato server
- Usare HTTPS e timeout espliciti
- Validare status HTTP, Content-Type e corpo
- Gestire paginazione numerata e cursor separatamente
- Non inviare valori di esempio non necessari
- Rendere idempotenti retry e scritture quando possibile
- Registrare identificativi, non segreti o dati completi
- Verificare l’effetto nel modulo operativo
- Ruotare e revocare le chiavi non più usate