Guida · Per gli amministratori

API e integrazioni

Chiavi API

In Impostazioni › API › Crea chiave dai un nome alla chiave (es. «WHMCS»). La chiave, kvm_…, si vede una volta sola: copiala subito. Ogni chiave agisce come l'amministratore che l'ha creata; tienila sul server della fatturazione, mai nel browser. Si revoca dalla stessa pagina.

Le chiamate vanno su https://vm.tuodominio.it/api/v1/… con l'intestazione Authorization: Bearer kvm_…. Limite: 600 richieste al minuto per chiave.

Le chiamate principali

Chiamata	Cosa fa
`GET /ping`	prova la chiave
`GET /plans`, `GET /images`, `GET /locations`	piani, sistemi operativi, nodi e zone
`GET /clients?email=…`, `POST /clients`	trova o crea un cliente
`POST /vps`	crea una VPS
`GET /vps/{id}`, `GET /vps?external_id=…`	stato della VPS
`POST /vps/{id}/power`	`start`, `stop`, `restart`
`POST /vps/{id}/suspend`, `/unsuspend`	sospende (con motivo) e riattiva
`POST /vps/{id}/plan`	cambio piano (`restart: true` per applicarlo subito); con `extra` e `extra_disk_gb` anche risorse in più e disco aggiuntivo
`POST /vps/{id}/resources`	risorse su misura: `vcpu`, `ram_mb`, `disk_gb` (solo in su), `net_mbit`, `traffic_gb`
`GET/POST /vps/{id}/disks`, `PUT`/`DELETE /vps/{id}/disks/{disco}`	dischi aggiuntivi: elenco, aggiunta (`size_gb`, `mount`), allargamento, rimozione (`?confirm=disk1`)
`PUT /vps/{id}/ips`	IP aggiuntivi: `{"count": 3}` porta la VPS ad averne esattamente 3 (per la fatturazione)
`POST /vps/{id}/ips`, `DELETE /vps/{id}/ips/{ip}`	aggiunge IP aggiuntivi (`count` o `ips`), ne toglie uno
`POST /vps/{id}/password`, `/reinstall`	nuova password, reinstallazione
`GET /vps/{id}/usage`	traffico e disco del mese
`POST /vps/{id}/login-link`	link di accesso per il cliente
`DELETE /vps/{id}`	elimina

Esempio di creazione:

curl -X POST https://vm.tuodominio.it/api/v1/vps \
  -H "Authorization: Bearer kvm_…" -H "Content-Type: application/json" \
  -d '{"client":{"email":"mario@esempio.it","name":"Mario Rossi"},"plan_id":1,
       "image":"debian/12/cloud","hostname":"web1.esempio.it","external_id":"ordine-1001"}'

Per vendere risorse in più aggiungi "extra": {"vcpu": 1, "ram_mb": 2048, "disk_gb": 20} (sommate al piano), "extra_disk_gb": 100 per un disco aggiuntivo montato in /mnt/disco1 e "extra_ips": 2 per due IP aggiuntivi presi dai blocchi instradati del nodo (li trovi in extra_ips della VPS).

Con external_id (o l'intestazione Idempotency-Key) la stessa richiesta ripetuta non crea doppioni: restituisce la VPS già creata. La risposta contiene la password di root e, per un cliente nuovo, la sua password.

Accesso con un clic

POST /vps/{id}/login-link restituisce un link monouso, valido 2 minuti, che apre la pagina della VPS già autenticati. Usato una volta scade: il cliente trova la pagina di accesso con un avviso.

WHMCS

Scarica il modulo da Impostazioni › API › Scarica il modulo per WHMCS e copia modules/servers/koavm nella cartella di WHMCS. Poi:

Setup › Products/Services › Servers › Add New Server: hostname del pannello, modulo KoaVM, la chiave kvm_… come password, Secure attivo. Test Connection deve rispondere «successful».
Nel prodotto (tipo Server/VPS), scheda Module Settings: modulo KoaVM, piano, sistema operativo predefinito, posizione (vuota = automatica).
Facoltativi: opzioni configurabili Sistema operativo e Posizione, campo personalizzato Chiave SSH.
Per vendere risorse in più: opzioni configurabili RAM in più (GB), vCPU in più, Disco in più (GB), Disco aggiuntivo (GB) e IP aggiuntivi (vanno negli IP assegnati del servizio).

Il modulo gestisce creazione, sospensione, riattivazione, eliminazione, cambio di pacchetto, password, accensione e spegnimento, accesso al pannello con un clic e l'uso di disco e traffico. Il README nello zip spiega tutto in dettaglio.

Koabilling

In Koabilling aggiungi il fornitore KoaVM con l'indirizzo del pannello e la chiave API. Nel prodotto: piano = id del piano KoaVM, regione = id del nodo o della zona (vuoto = automatica), immagine = sistema (es. debian/12/cloud).