HELPER VPS

Avvio rapido API del VPS: creare la chiave API e il primo server

L'API di HELPER VPS è una REST API che scambia JSON via HTTPS. Con una sola chiave consulti i piani, crei server, gestisci l'alimentazione, rinnovi ed elimini. Segui i passi dalla prima richiesta fino a creare ed eliminare un server.

Passo 1. Crea la chiave API

Puoi creare una chiave API dopo il primo pagamento. Consulta la guida al pagamento USDT per sapere come pagare.

  • Nel menu Chiavi API dell'account premi Crea chiave API.
  • La chiave, che inizia con hvp_, viene mostrata una sola volta. Copiala subito e salvala in un gestore di password.
  • Sullo schermo restano solo le ultime cifre della chiave, così capisci quale stai usando.
  • Premendo Crea nuova chiave ne compare una nuova e quella precedente smette subito di funzionare.

La chiave apre l'intero account, quindi usala tramite variabili d'ambiente perché non compaia in repository di codice o condivisioni dello schermo. Gli esempi di questa guida partono mettendo la chiave in una variabile nel terminale.

Terminale
export HVP_KEY=hvp_LA_TUA_CHIAVE
export HVP=https://helpervps.com/api/v1

Passo 2. Autenticazione e prima richiesta

Tutte le richieste vanno inviate sotto l'indirizzo base https://helpervps.com/api/v1 con l'intestazione Authorization: Bearer chiave. Come prima richiesta carica l'elenco dei tuoi server. Se non hai server, torna un elenco vuoto [].

Terminale
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Ogni account può inviare fino a 300 richieste al minuto, e fino a 10 creazioni di server ogni 10 minuti. Per richieste ripetute di verifica dello stato, un intervallo di qualche secondo è più che sufficiente. Tutte le risposte sono in JSON; in caso di errore tornano con il codice di stato nella forma {"error": "codice"}.

Passo 3. Scegli piano, regione e immagine

Tutti i valori da inserire alla creazione del server vengono dal catalogo. GET /catalog restituisce in una volta piani in vendita (plans), regioni (locations), immagini (images) e opzioni aggiuntive (addons). Con jq è comodo vedere solo le parti che ti servono.

Terminale
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'
  • Codice del piano: come s1 e s2, indica tipo e dimensione. type è basic (SSD standard), fast (NVMe ad alte prestazioni), cpu (CPU dedicata) o mem (memoria elevata). monthly è il canone mensile in dollari USA.
  • Codice della regione: il nome della città, come frankfurt, singapore e seoul.
  • Codice dell'immagine: sistemi operativi come ubuntu-24-04, debian-13 e almalinux-10 e app come app-docker e app-wordpress.
  • Opzioni aggiuntive: percentuale del backup automatico, dimensioni del disco extra e costo per GB, costo della protezione DDoS. Le opzioni non in vendita arrivano come null.

Se non c'è, installalo con apt install -y jq su Ubuntu o con brew install jq su Mac. È lo stesso elenco che scegli nell'interfaccia: le differenze tra i piani si vedono comodamente anche nella pagina dei prezzi.

Passo 4. Crea un server

Invia il piano, la posizione, l'immagine e il nome come JSON a POST /servers. Paga per il primo periodo del piano scelto e inizia la creazione del server.

Terminale
curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

In caso di successo torna il codice di stato 201 con i dati del server. id è il codice del server nella forma S-XXXX-XXXX-XXXX, da usare in tutte le richieste successive. root_password è presente una sola volta in questa risposta, quindi salvala subito. È visibile anche nella pagina del server per 7 giorni.

  • label: il nome del server. Fino a 40 caratteri tra lettere, numeri, punti e trattini; gli altri caratteri diventano trattini.
  • backups: con true si attiva il backup automatico.
  • extra_disk_gb: la dimensione del disco a blocchi NVMe aggiuntivo. Inserisci uno dei valori sizes_gb del catalogo (50, 100, 250, 500, 1000).
  • ddos_protection: con true si attiva la protezione DDoS.

Il costo delle opzioni si somma al canone mensile del server, compare in monthly nella risposta e si rinnova in automatico allo stesso importo a ogni data di addebito. Ogni account può creare fino a 10 server.

Passo 5. Verifica lo stato e accedi

Un nuovo server parte nello stato creating e, quando è pronto, passa a running e l'indirizzo ipv4 viene compilato. Il ciclo qui sotto controlla lo stato ogni 10 secondi e mostra l'IP quando diventa running. Sostituisci il codice del server con quello del tuo server.

Terminale
ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

Lo stato è uno tra creating, running, stopped, rebooting, installing, suspended o check. suspended significa che il server è stato sospeso perché non è stato rinnovato alla data di fatturazione, e check significa che stiamo verificando il risultato della configurazione del server. Una volta che appare l'IP, connettiti con ssh root@IP. Come connettersi è spiegato nella guida al primo accesso.

Passo 6. Alimentazione, rinnovo, eliminazione

Terminale
curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"
  • start: accende un server fermo (stopped).
  • stop, reboot: spegne o riavvia un server in esecuzione (running).
  • renew: paga per 1, 3, 6 o 12 mesi in più ora. Un server sospeso torna attivo anche con questa richiesta.
  • DELETE: elimina server e disco e restituisce {"state": "deleted"}. Il periodo residuo del mese già pagato non viene rimborsato.

Se invii un'operazione non possibile nello stato attuale, torna 409 wrong_state. Per esempio, inviando start a un server già acceso. Reinstallazione e nuova password root si fanno dalla pagina del server. I passi sono nella guida alla reinstallazione.

Eseguire gli stessi passi con Python

Lo stesso flusso scritto come script Python è così. Usa la libreria requests (pip install requests).

create_server.py
import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Codici di errore frequenti

  • 401 unauthorized: la chiave manca o è errata. Controlla che l'intestazione sia nella forma Authorization: Bearer hvp_....
  • 403 not_allowed: si sblocca una volta confermato il primo pagamento.
  • 400 bad_request: nome o valore di un campo errato. Usa i codici esattamente come nel catalogo.
  • 402 not_enough_balance: l'importo del pagamento è inferiore a $25. Invia di nuovo con almeno $25.
  • 409 limit: hai raggiunto il numero di server creabili nell'account.
  • 409 not_created: il server non può essere creato e la tariffa viene restituita al credito del tuo account.
  • 202 checking: stiamo verificando il risultato della configurazione del server. Non inviare di nuovo la stessa richiesta; controlla la lista dei server. Il server verrà completato o la tariffa verrà restituita al credito del tuo account.
  • 404 not_found: codice del server o indirizzo non presente nel tuo account.
  • 409 wrong_state: operazione non possibile nello stato attuale.
  • 429 rate_limited: hai raggiunto il limite di richieste al minuto. Aspetta un attimo e invia di nuovo.

Tutti gli endpoint, i campi delle risposte e gli esempi sono raccolti nella documentazione API. Cosa puoi fare con l'API e i casi d'uso sono nella pagina API VPS.

Guide correlate

Impostazioni utili da completare dopo questa guida.

Tutte le guide