--- title: REST API description: Chiama l'API clienti della tua installazione NexCMP: autenticazione, riferimento interattivo, download OpenAPI e Postman, errori, rate limit, idempotenza ed esempi curl. url: https://nexcmp.com/it/docs/developers/api/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # REST API > **Dove nel portale:** Riferimento API su `https:///apidoc` (pubblico) e chiavi API su `/api-keys`. **Dove nell'amministrazione:** Customers › API keys (`/customers/apikeys`) elenca le chiavi create dai clienti. ## Descrizione {#what-it-does} Ogni azione che un cliente può compiere nel portale — elencare e gestire VM, leggere fatture, gestire chiavi SSH, Kubernetes, storage, ticket di supporto — è disponibile tramite un'API REST con controllo di versione sotto `https:///v1/`. I clienti la chiamano da script e CI con una **API key** con ambito limitato. La stessa API alimenta lo strumento a riga di comando [`cmp` command-line tool](https://nexcmp.com/it/docs/developers/cmp-cli/) e il server [MCP server](https://nexcmp.com/it/docs/developers/mcp/), e il riferimento viene generato dall'installazione in esecuzione, quindi elenca sempre esattamente le funzionalità che hai attivato. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Indirizzo HTTPS pubblico | L'API è servita sul tuo dominio principale (e sul dominio di ciascun rivenditore). | | Una chiave API | Creata dal cliente nel portale; vedi [API keys](https://nexcmp.com/it/docs/developers/api-keys/). | | Dipendenze | Nessuno. Gli endpoint di un modulo che non hai abilitato (ad esempio Kubernetes o Object Storage) sono nascosti dal riferimento e rifiutati. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Nulla da installare. Se un proxy inverso si trova davanti a NexCMP, inoltra `/v1/`, `/mcp`, `/cli/` e `/apidoc` al pannello (la configurazione nginx del programma di installazione lo fa già). ## Collega in NexCMP {#connect-in-nexcmp} ### Il riferimento interattivo {#the-interactive-reference} Apri `https://cloud.example.com/apidoc` (sostituisci l'host con il tuo dominio; i clienti di un rivenditore vedono il riferimento sul dominio del rivenditore, con il nome del rivenditore). Dispone di documentazione sugli endpoint con esempi di richiesta e risposta in curl, `cmp` CLI, JavaScript, Python e Go, una casella di ricerca (Ctrl o Cmd + K) e un pannello **Try it**. Try it invia richieste solo allo stesso sito, con una chiave incollata dal visitatore (mantenuta nella sessione del browser); è di sola lettura per impostazione predefinita e le chiamate di scrittura o a pagamento richiedono un interruttore aggiuntivo e una conferma. ### Download e documenti leggibili da macchina {#downloads-and-machine-readable-documents} Tutti sono pubblici, non richiedono chiavi e sono generati per sito: | URL | Contenuto | |---|---| | `/apidoc` | Riferimento interattivo. | | `/v1/public/openapi.json` | Documento OpenAPI 3.1. | | `/v1/public/openapi.yaml` | Stesso, YAML. | | `/v1/public/postman.json` | Raccolta Postman. | | `/v1/public/insomnia.json` | Esportazione Insomnia. | | `/v1/public/api.md` | Il riferimento come singolo file Markdown. | | `/v1/public/api-catalog` | JSON leggero: brand, URL di base, prefisso della chiave, ogni ambito ed ogni endpoint con metodo, percorso, ambito e se richiede un `Idempotency-Key`. | ```bash curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40 curl -sO https://cloud.example.com/v1/public/openapi.yaml ``` In Postman seleziona **Import › Link** e incolla `https://cloud.example.com/v1/public/postman.json`. La pagina di riferimento offre anche client API a file singolo per JavaScript e Python. ### Autenticazione {#authentication} Invia la chiave nell'intestazione `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - Le chiavi dei clienti iniziano con `vk_`. Le chiavi sono **vincolate al sito**: una chiave creata su `cloud.example.com` non funziona sul dominio di un rivenditore. - I token di sessione del browser (`pt_...`) sono riservati al portale; usa una chiave per l'automazione. - Gli **ambiti** della chiave determinano cosa può chiamare; un ambito mancante risponde con HTTP 403 `scope_required`. Vedi [API keys](https://nexcmp.com/it/docs/developers/api-keys/). - Verifica una chiave con `GET /v1/apikeys/self`: restituisce il nome, gli ambiti, la scadenza e il residuo del limite di velocità della chiave chiamante (ciascuna chiave può chiamarla). ### Esempi {#examples} ```bash # List virtual machines curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX" # Start one (needs vm:write) curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \ -H "Authorization: Bearer vk_XXXX" # Create a VM (paid: needs vm:create and an Idempotency-Key) curl -s -X POST https://cloud.example.com/v1/vm \ -H "Authorization: Bearer vk_XXXX" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @vm.json ``` Prendi i campi di richiesta esatti di ciascuna operazione da `/apidoc`. ### Errori {#errors} Ogni errore è in formato JSON con un `code` stabile e un `message` leggibile dall'utente: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | Tipico `code` | Significato | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Chiave mancante o sconosciuta, revocata, scaduta, IP del chiamante al di fuori dell'elenco consentito della chiave, chiave proveniente da un altro sito o chiavi API disattivate. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | La chiave non ha l'ambito; l'endpoint non è disponibile per le chiavi; l'account è bloccato; è stata raggiunta una [quota](https://nexcmp.com/it/docs/billing/quotas/); azione non consentita in una sessione impersonata. | | 404 | `not_found` | Non trovato — restituito anche per risorse che appartengono a qualcun altro. | | 422 | `invalid_argument` | Errore di validazione (campo specificato nella risposta). | | 429 | `rate_limited` | Troppe richieste; attendi per `Retry-After`. | | 503 | `maintenance` | La modalità di manutenzione è attiva: le letture funzionano, le scritture vengono rifiutate. | ### Limiti di velocità {#rate-limits} | Limite | Predefinito | |---|---| | Per chiave | 120 richieste al minuto | | Per account (tutte le chiavi insieme) | 300 richieste al minuto | Ogni risposta contiene `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`; un errore 429 aggiunge `Retry-After`. ### Idempotency {#idempotency} I comandi che comportano costi o non possono essere ripetuti (creazione, cambio piano, acquisto, eliminazione...) **richiedono** un'intestazione `Idempotency-Key` (qualsiasi stringa fino a 200 caratteri; un UUID funziona bene). Invia nuovamente la stessa chiave dopo un timeout e il server restituirà il risultato **originale** (con `Idempotency-Replayed: 1`) anziché ripetere l'operazione. Il riutilizzo di una chiave per un comando diverso risponde con 422; una richiesta ancora in corso risponde con 409/`Retry-After`. Senza l'intestazione, una chiamata a pagamento viene rifiutata. ## Verifica {#verify} 1. Crea una chiave con ambito `vm:read` nel portale (**API keys › Create key**). 2. Esegui: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Ricevi HTTP 200 e le intestazioni relative al limite di velocità. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` elenca le macchine virtuali dell'account. Nel portale, la colonna **Last used** della chiave e il **Key usage log** mostrano le chiamate. ## Limiti e note {#limits-notes} - **Mai accessibili con una chiave:** ricariche, prelievi, modifica delle carte o ricarica automatica, modifica della password, e-mail o 2FA, eliminazione dell'account, creazione, modifica o revoca di altre chiavi. Queste operazioni richiedono una sessione browser attiva. - **Moduli nascosti:** il riferimento e il documento OpenAPI elencano solo le funzionalità abilitate su quel sito. - **Dimensione della risposta e paginazione:** gli endpoint di elenco sono paginati (`page`, `per_page`); leggi il documento OpenAPI per ogni endpoint. - **Tempo e denaro:** gli importi sono espressi in centesimi di USD, salvo diversa indicazione nel nome del campo. - **API di amministrazione:** la console di amministrazione ha la sua pagina **System › Admin › API** e chiavi di amministratore (`ofw_...`) per la gestione; sono separate dalle API per i clienti descritte qui. - **Controllo delle versioni:** il prefisso del percorso `/v1` è stabile; è possibile che vengano aggiunti nuovi campi alle risposte. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | 401 su una nuova chiave | Chiave proveniente da un altro dominio, scaduta o inserita con spazi | Crea la chiave sul dominio che chiami; verifica l'header `Authorization: Bearer vk_...`. | | 403 `scope_required` | Scope mancante | Modifica la chiave nel portale e aggiungi lo scope. | | 401 `key_ip_denied` o `site_mismatch` | Chiave limitata ad altri IP ("allowed IPs") o creata su un altro dominio | Aggiungi l'IP del tuo server agli IP consentiti della chiave oppure chiama il dominio su cui è stata creata. | | 404 su una VM esistente | La VM appartiene a un altro account | Usa una chiave del proprietario. | | 400/422 con richiesta di `Idempotency-Key` | Operazione a pagamento senza l'header | Aggiungi `Idempotency-Key: `. | | 429 | Limite superato | Riduci la frequenza; usa `Retry-After`. | | `/apidoc` mostra meno del previsto | Modulo disattivato | Attiva il modulo in License & updates. |