API CLIENTI · V1 BETA
API REST per
VPS e Server Dedicati
Gestisca i Suoi server via codice: ordini e distrugga VPS a ore, esegua azioni di alimentazione e reinstallazioni, acquisisca e distribuisca le Sue immagini e paghi le fatture con il credito.
L'API clienti di X-ZoneServers (v1, beta pubblica) espone 92 operazioni via HTTPS, con una specifica OpenAPI 3.0, chiavi API con scope e un limite predefinito di 1.000 richieste all'ora per chiave. È inclusa in ogni account senza costi aggiuntivi.
92 operazioni API1.000 richieste all'ora per chiave
La Sua prima chiamata
Crei una chiave nell'area cliente, in Profile → API Keys, poi chieda all'API chi è Lei.
curl https://my.x-zoneservers.com/api/v1/ \
-H "Authorization: Bearer $XZ_API_KEY"
{ "success": true,
"data": {
"version": "1",
"key": { "scopes": ["read", "services"] },
"rate_limit": { "limit": 1000, "remaining": 999 }
} }01Funzionalità
Cosa Può Automatizzare
L'API copre l'intero ciclo di vita di un server, dall'ordine alla fattura, con gli stessi permessi dell'area cliente.
Deploy e Distruzione
Ordini un VPS con fatturazione oraria o mensile, passi user-data cloud-init e chiavi SSH per il primo avvio e lo elimini a lavoro finito. La fatturazione oraria si ferma nel momento in cui il server non esiste più.
Alimentazione, Reinstallazione e Statistiche
Avvii, arresti, riavvii e reinstalli i Suoi VPS, reimposti le password di root e legga le statistiche di utilizzo e di traffico dai Suoi script di monitoraggio.
Immagini Personalizzate
Acquisisca un VPS come immagine (fino a 3 per account), oppure registri una Sua immagine qcow2 o raw (verificata tramite SHA-256) e la usi per distribuire nuovi server.
Fatturazione e Utilizzo
Consulti il saldo del credito e gli addebiti orari di questo mese, elenchi fatture e proforma e le paghi con il credito — utile per dashboard dei costi e avvisi di budget.
Add-on e Upgrade
Acquisti add-on per un servizio esistente, come indirizzi IP aggiuntivi, oppure lo passi a un piano superiore senza aprire l'area cliente.
Progetti e Chiavi con Scope
Raggruppi i server in progetti e generi chiavi legate a un singolo progetto: così una chiave di staging non potrà mai vedere né toccare la produzione.
02Come funziona
Esempio: un VPS a Ore per un Singolo Job CI
Crei una macchina di build pulita, esegua la pipeline, la elimini — e paghi le ore in cui è esistita.
I servizi orari vengono addebitati sul credito dell'account anziché fatturati, quindi mantenga un saldo disponibile sull'account. Invii un header Idempotency-Key con ogni ordine: una richiesta andata in timeout potrà così essere ripetuta senza creare un secondo server.
1. Scelga un piano: elenchi i prodotti con i relativi prezzi orari e mensili.
curl https://my.x-zoneservers.com/api/v1/products \
-H "Authorization: Bearer $XZ_API_KEY"2. Lo ordini con fatturazione oraria, con uno script di primo avvio e la Sua chiave SSH.
curl -X POST https://my.x-zoneservers.com/api/v1/orders \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Idempotency-Key: ci-run-4812" \
-H "Content-Type: application/json" \
-d '{"productId": "<plan-id>", "billingCycle": "hourly",
"hostname": "ci-4812.example.com", "location": "<location>",
"configOptions": {"os_image_id": "<image-id>",
"ssh_keys": ["ssh-ed25519 AAAA... ci@runner"],
"user_data": "#!/bin/sh\n/opt/ci/run-pipeline.sh"}}'3. Quando il job è terminato, elimini il server. La fatturazione si ferma immediatamente.
curl -X DELETE https://my.x-zoneservers.com/api/v1/vps/<vps-id> \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"immediate": true}'03API
Progettata per Script e Agenti IA
Quando a premere i pulsanti è un programma e non una persona, un comportamento prevedibile conta più del numero di endpoint.
Chiavi con scope
Ogni chiave dispone solo degli scope che Lei concede — read, services, orders, billing, destructive — più un elenco di IP consentiti e una data di scadenza facoltativi.
Rate limit pubblicati
1.000 richieste all'ora per chiave come impostazione predefinita, indicate negli header X-RateLimit, con brevi tempi di attesa per server sulle azioni di alimentazione e reinstallazione.
Nuovi tentativi sicuri
Gli ordini accettano un Idempotency-Key e ogni rifiuto restituisce un codice di errore leggibile dalle macchine, così l'automazione può distinguere un errore per cui basta riprovare da un errore reale.
Documentazione leggibile dalle macchine
Una specifica OpenAPI 3.0 per i generatori di client e una guida in puro Markdown che assistenti di programmazione e agenti IA possono leggere direttamente.
04Correlati
Vende Server ai Suoi Clienti?
Questa API clienti automatizza il Suo account. Per rivendere con il Suo marchio, aderisca al programma reseller e utilizzi invece l'API Reseller: prezzi all'ingrosso con fasce di volume, richieste firmate HMAC, webhook, chiavi legate al cliente e link alla console che i Suoi clienti aprono senza un account presso di noi.
05Domande
FAQ sull'API
Domande frequenti sull'automazione di X-ZoneServers.
X-ZoneServers ha un'API?
Sì. L'API clienti (v1) è un'API REST su HTTPS all'indirizzo https://my.x-zoneservers.com/api/v1 con 92 operazioni che coprono VPS, server dedicati, ordini, add-on, upgrade, fatture, chiavi SSH e immagini personalizzate. È in beta pubblica: abbastanza stabile per costruirci sopra, ma gli endpoint e la struttura delle risposte possono ancora cambiare.
L'accesso all'API è gratuito?
Sì. L'accesso all'API è incluso in ogni account senza costi aggiuntivi; paga solo i server e gli add-on che ordina, agli stessi prezzi del sito web e dell'area cliente.
Posso creare ed eliminare VPS a ore tramite l'API?
Sì. Effettui un ordine con il ciclo di fatturazione impostato su orario, facoltativamente con user-data cloud-init e chiavi SSH, poi elimini il VPS quando non Le serve più. I servizi orari vengono addebitati sul credito dell'account e smettono di essere fatturati non appena vengono eliminati.
L'API funziona con i server dedicati?
In parte. Per i server dedicati l'API copre ordini, add-on, fatture e dettagli del servizio. Il controllo dell'alimentazione, le reinstallazioni del sistema operativo e il reset delle password non sono disponibili per i server dedicati, né tramite l'API né dall'area cliente.
Come mi autentico?
Crei una chiave API nell'area cliente, in Profile → API Keys, e la invii come token Bearer. Ne scelga gli scope al momento della creazione e, se lo desidera, la limiti a indirizzi IP specifici o le assegni una data di scadenza. Le chiavi vengono mostrate una sola volta e possono essere revocate in qualsiasi momento dall'area cliente.
Esiste una specifica OpenAPI o Swagger?
Sì. La specifica OpenAPI 3.0 completa è pubblicata all'indirizzo https://my.x-zoneservers.com/api/v1/openapi.json, accanto alla documentazione renderizzata e a una guida all'uso in Markdown.
Inizia
Crei la Sua Prima Chiave API
Acceda all'area cliente, apra Profile → API Keys ed effettui la Sua prima chiamata in meno di un minuto. Le domande sull'API arrivano direttamente alle persone che sviluppano la piattaforma.