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.

Anche i rivenditori hanno le loro chiavi: agiscono solo sui loro clienti e sulle loro VPS, con i loro piani e nodi e dentro i loro limiti.

I clienti hanno un altro tipo di chiave (pagina Team e API dell'area clienti, dalla 0.13): vale sull'API del pannello (/api/…), con i permessi del ruolo scelto, solo sulle cose del cliente. Le chiavi dei clienti non valgono su /api/v1 e quelle di questa pagina non valgono sull'API del pannello. Vedi Clienti e VPS.

Le chiamate principali

Chiamata	Cosa fa
`GET /ping`	prova la chiave
`GET /plans`, `GET /images`, `GET /locations`	piani, sistemi (con tipo `linux`/`windows`, requisiti e piani; `?plan_id=` per quelli di un piano), nodi e zone
`GET /apps`	applicazioni da installare al primo avvio: sigla, sistemi, requisiti, campi da compilare
`GET /clients?email=…`, `POST /clients`	trova o crea un cliente (con `twofa`: `true` se ha la verifica in due passaggi attiva)
`DELETE /clients/{id}/2fa`	toglie la verifica in due passaggi al cliente che ha perso il telefono (per l'assistenza: chiude le sue sessioni e gli manda un'email; `409` se non è attiva). Con la chiave di un rivenditore vale sui suoi clienti, non sul rivenditore
`POST /vps`	crea una VPS (con `"no_ipv4": true` e una rete privata, senza IPv4 pubblico: vedi router)
`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`; dalla 1.14 anche i limiti (vedi sotto)
`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}/ips/{ip}/move`	sposta un IP aggiuntivo su un'altra VPS dello stesso cliente (`{"to": id}`)
`GET/PUT /vps/{id}/firewall`	firewall della VPS: `enabled` e `rules`
`PUT /vps/{id}/ha`	alta affidabilità: `protect` (`""` come il piano, `"on"`, `"off"`), `reserve_id` (0 = lo sceglie il pannello), `priority` (0–2); lo stato è in `ha` di `GET /vps/{id}`
`POST /vps/{id}/disks/{disco}/detach`, `GET /volumes`, `POST /volumes/{id}/attach`	volumi: stacca un disco, elenco, collega a una VPS (`vps_id`, `mount`)
`GET/POST /volumes/{id}/snapshots`, `POST …/{nome}/restore`, `DELETE …/{nome}`	snapshot dei volumi
`GET/POST /private-networks`, `POST /vps/{id}/private-networks`	reti private: elenco, creazione, collegamento (`network_id` o `default: true`)
`GET/POST /vps/{id}/rescue`, `POST /vps/{id}/rescue/exit`	modalità di soccorso: stato, avvio (`ssh_key` o `ssh_key_ids` facoltativi; la risposta contiene la password temporanea di root), uscita
`POST /vps/{id}/password`, `/reinstall`	nuova password (non per Windows), reinstallazione (`image_id`, anche con `app_id` e `app_options`)
`GET /vps/{id}/app`	stato dell'applicazione: passo, errore, indirizzo, utente e password
`GET /vps/{id}/usage`	traffico e disco del mese
`GET/PUT/DELETE /clients/{id}/quota`, `GET /usage`	pacchetto self-service del cliente e uso a ore del mese
`GET/POST /load-balancers`, `GET/PUT/DELETE /load-balancers/{id}`	load balancer: `client_id`, `name`, `city`, `services`, `targets` (id delle VPS), `external_id`
`GET/POST /dns/zones`, `GET/PUT/DELETE /dns/zones/{id}`, `POST /dns/zones/{id}/records`, `PUT/DELETE /dns/zones/{id}/records/{rid}`, `POST …/import`, `GET …/export`	DNS: `name`, `client_id`, `ttl`, `records` (`name`, `type`, `content`, `ttl`, `priority`), `external_id`; import di un file di zona (`text`, `replace`)
`GET/POST /routers`, `GET/PUT/DELETE /routers/{id}`	router: `client_id`, `name`, `city`, `network_id`, `forwards` (`protocol`, `public_port`, `vps_id`, `target_port`, `note`), `external_id`
`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).

Limiti del disco e della CPU (1.14). I piani di GET /plans e le VPS di GET /vps/{id} hanno disk_read_mbs, disk_write_mbs (MB/s), disk_read_iops, disk_write_iops (operazioni al secondo), cpu_max_pct (uso massimo di ogni vCPU in %) e cpu_priority (normal, low, high); 0 = senza limite. MB/s e operazioni al secondo della stessa direzione valgono insieme, per ogni disco. Nelle VPS sono i limiti che valgono e limits_custom dice se sono su misura. Con POST /vps/{id}/resources li cambi per una VPS (-1 = come il piano: su uno dei due campi di una direzione rimette come il piano tutta la direzione; i campi che non mandi restano come sono) oppure li rimetti tutti come il piano con "limits_as_plan": true. Esempio: {"disk_write_iops": 2000, "cpu_max_pct": 50}. Un cambio piano con POST /vps/{id}/plan rimette i limiti del piano nuovo. Le VPS dei fornitori non hanno limiti.

Per un'applicazione preinstallata aggiungi "app": "wordpress" (la sigla di GET /apps) e, per cPanel, Plesk e DirectAdmin, "app_options": {"accept": "1", "license": "…"}. Per le VPS Windows l'utente di accesso è Administrator (campo login_user 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.

Il link non chiede la verifica in due passaggi, anche quando è attiva o obbligatoria: la fatturazione, che lo crea con la chiave API, ha già autenticato il cliente. Le chiavi API non usano la verifica in due passaggi.

Con la chiave di un rivenditore i link di accesso (/clients/{id}/login-link, /vps/{id}/login-link) e i pacchetti (/clients/{id}/quota) valgono per i suoi clienti e le loro VPS, mai per il rivenditore stesso (dalla 1.13): la chiave può averla creata una persona del suo team.

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).
Per la rete privata: opzione Sì/No Rete privata (modulo 1.3.0): la VPS va sulla rete privata predefinita del cliente.
Per le applicazioni preinstallate: impostazione Applicazione del prodotto o opzione configurabile Applicazione con valori come wordpress|WordPress (modulo 1.4.0); per le VPS Windows l'utente del servizio è Administrator.
Per vendere un pacchetto self-service invece di una VPS: Tipo = pacchetto e i limiti del pacchetto nelle impostazioni del prodotto (modulo 1.5.0); vedi Self-service e uso a ore.

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.

I limiti del disco e della CPU (1.14) vengono dal piano KoaVM del prodotto: per venderli basta un piano con i limiti, il modulo non ha impostazioni nuove.

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).

Per i pacchetti self-service e la fatturazione a ore KoaBilling usa PUT /clients/{id}/quota e GET /usage?month=AAAA-MM: vedi Self-service e uso a ore.