Introduzione

Le API Shellrent permettono di accedere in modo programmatico ai dati e alle funzionalità del proprio account, ad esempio account utente, domini, hosting, server, fatture, acquisti e molti altri servizi esposti dalla piattaforma.

L'URL base dell'API è:

https://api.shellrent.com

Tutte le chiamate applicative sono esposte sotto /api/v3/... e usano autenticazione OAuth2. Prima di invocare un endpoint è quindi necessario ottenere un access_token valido.

SDK ufficiali

Se sviluppi in PHP o in Python, il modo più semplice per usare le API è partire da uno degli SDK ufficiali, open source e generati dalla stessa specifica OpenAPI di questa documentazione:

Linguaggio	Repository	Installazione
PHP 8.1+	shellrent/shellrent-sdk-php	`composer require shellrent/sdk`
Python 3.11+	shellrent/shellrent-sdk-python	`pip install shellrent-sdk`

Gli SDK gestiscono già per te:

la richiesta dell'access_token e il suo rinnovo poco prima della scadenza;
una nuova richiesta del token e un solo nuovo tentativo quando l'API risponde 401;
i nuovi tentativi, dopo l'attesa indicata dall'header Retry-After, quando l'API risponde 429 Too Many Requests;
la cache del token, anche condivisa tra più processi;
i modelli tipizzati di richieste e risposte, con un metodo per ogni endpoint.

Ad esempio, per leggere gli acquisti con l'SDK PHP:

<?php

require 'vendor/autoload.php';

use Shellrent\Sdk\Auth\ClientCredentials;
use Shellrent\Sdk\Client;

$client = Client::create(new ClientCredentials('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET'));

$purchases = $client->purchases()->listPurchases(page: 1, per_page: 50);

foreach ($purchases->getData() as $purchase) {
    printf("%d %s\n", $purchase->getPurchaseId(), $purchase->getPurchaseName()->getFullName());
}

E con l'SDK Python:

from shellrent_sdk import ClientCredentials, create_client, unwrap
from shellrent_sdk.client.api.purchases import list_purchases

credentials = ClientCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

with create_client(credentials) as client:
    purchases = unwrap(list_purchases.sync_detailed(client=client, page=1, per_page=50))
    for purchase in purchases.data:
        print(purchase.purchase_id, purchase.purchase_name)

Il pacchetto Python installa anche il comando shellrent, utile per provare le API dal terminale o negli script:

export SHELLRENT_CLIENT_ID=YOUR_CLIENT_ID
export SHELLRENT_CLIENT_SECRET=YOUR_CLIENT_SECRET

shellrent api GET /api/v3/purchases

Il README di ciascun repository descrive tutte le opzioni: credenziali da variabili d'ambiente, cache del token, gestione degli errori e download dei file.

Specifica OpenAPI

La specifica OpenAPI delle API pubbliche descrive tutti gli endpoint, con parametri, scope richiesti e schemi di richieste e risposte. Puoi scaricarla in due formati:

YAML
JSON

È utile per generare un client in un linguaggio per cui non c'è un SDK ufficiale, oppure per importare le API in strumenti come Postman o Insomnia. Le pagine di riferimento degli endpoint, in questa documentazione, sono generate dalla stessa specifica.

Il resto di questa pagina spiega come funzionano autenticazione e chiamate a livello HTTP: è utile se usi un altro linguaggio o se vuoi capire cosa fanno gli SDK.

Come funziona OAuth2 in questa API

OAuth2 è uno standard usato per consentire a un'applicazione di accedere a un'API in modo controllato, senza dover usare username e password dell'utente finale a ogni richiesta.

L'API supporta il solo flusso client_credentials, pensato per le integrazioni server-to-server:

l'applicazione che consuma le API usa un client_id e un client_secret, che crei nel Manager (vedi Creare e gestire un client OAuth2);
con queste credenziali richiede un access_token;
il token viene poi inviato nelle chiamate API tramite header Authorization: Bearer ....

In pratica:

il tuo software si autentica con client_id e client_secret;
ottiene un token temporaneo, valido 10 minuti;
usa quel token per chiamare gli endpoint consentiti;
quando il token scade, ne richiede uno nuovo con le stesse credenziali.

Nessun refresh token

Il grant refresh_token non è supportato e la risposta del token non contiene un refresh_token: quando il token scade, se ne richiede semplicemente uno nuovo con client_id e client_secret.

Requisiti dell'account

Per ottenere un token, l'account a cui appartiene il client deve:

essere attivo e validato;
avere l'autenticazione a due fattori attiva: senza, l'endpoint del token risponde 400 con l'errore unauthorized_client.

Un token già emesso smette di funzionare se l'account viene disattivato.

Credenziali e scope

Ogni client OAuth2 ha i propri permessi. In OAuth2 questi permessi si chiamano scope.

Gli scope vanno considerati in due momenti:

nella richiesta del token, per scegliere quali permessi ottenere tra quelli assegnati al client;
nella chiamata API, perché il token deve includere gli scope richiesti da quello specifico endpoint.

Ad esempio:

GET /api/v3/account richiede account:read;
GET /api/v3/domains richiede domains:read.

Se nella richiesta del token non indichi alcuno scope, il token riceve tutti gli scope assegnati al client. Lo stesso risultato si ottiene richiedendo lo scope speciale api:full.

Trovi tutti i dettagli nella guida Scope e autorizzazioni.

Ottenere un access token

L'endpoint OAuth2 per ottenere un token è:

POST https://api.shellrent.com/oauth/token

Il corpo della richiesta è in formato application/x-www-form-urlencoded, con questi parametri:

Parametro	Obbligatorio	Descrizione
`grant_type`	Sì	Sempre `client_credentials`
`client_id`, `client_secret`	Sì	Credenziali del client. In alternativa puoi inviarle con l'autenticazione HTTP Basic
`scope`	No	Scope richiesti, separati da spazi. Se manca, il token riceve tutti gli scope del client
`audience`	No	Per le API pubbliche è `api-public`. Se manca, il token riceve l'audience del client

Un parametro inviato senza valore, ad esempio scope=, viene trattato come assente.

Esempio con curl

curl --request POST \
  --url 'https://api.shellrent.com/oauth/token' \
  --user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=account:read domains:read'

Esempio in PHP: richiesta del token

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.shellrent.com',
]);

$response = $client->post('/oauth/token', [
    'auth' => ['YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET'],
    'form_params' => [
        'grant_type' => 'client_credentials',
        'scope' => 'account:read domains:read',
        // Senza 'scope', il token riceve tutti gli scope assegnati al client
    ],
]);

$token = json_decode((string) $response->getBody(), true);

print_r($token);

Una risposta tipica contiene:

{
  "token_type": "Bearer",
  "expires_in": 600,
  "access_token": "eyJhbGciOi...",
  "scope": "account:read domains:read",
  "audience": "api-public"
}

I campi scope e audience indicano i permessi e l'audience effettivamente concessi.

Come gestire l'access token

L'access_token ha una durata limitata, attualmente 10 minuti. Il campo expires_in indica per quanti secondi il token resta valido.

La gestione consigliata è:

salva access_token e expires_in;
calcola il momento di scadenza;
riusa lo stesso token per tutte le chiamate finché è valido, invece di chiederne uno nuovo a ogni chiamata;
quando è scaduto, oppure sta per scadere, richiedine uno nuovo con client_credentials.

Una buona pratica è rinnovare il token con un piccolo anticipo, ad esempio 30-60 secondi prima della scadenza effettiva.

L'endpoint del token ha un proprio limite: 5 richieste ogni 15 secondi per IP e client. Se più processi o più richieste web usano lo stesso client, conviene condividere il token in una cache, come fanno gli SDK.

Come effettuare una chiamata API autenticata

Una volta ottenuto l'access_token, devi inviarlo nell'header HTTP Authorization come Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Ricorda che il token deve essere stato emesso con gli scope richiesti dall'endpoint che stai chiamando. Se, ad esempio, vuoi leggere i domini, il token deve includere domains:read.

Esempio in PHP: leggere il profilo account

L'endpoint:

GET /api/v3/account

richiede lo scope account:read.

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.shellrent.com',
]);

$accessToken = 'YOUR_ACCESS_TOKEN';

$response = $client->get('/api/v3/account', [
    'headers' => [
        'Authorization' => 'Bearer ' . $accessToken,
        'Accept' => 'application/json',
    ],
]);

$data = json_decode((string) $response->getBody(), true);

print_r($data['data']);

Esempio in PHP: elencare i domini

L'endpoint:

GET /api/v3/domains

richiede lo scope domains:read.

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.shellrent.com',
]);

$accessToken = 'YOUR_ACCESS_TOKEN';

$response = $client->get('/api/v3/domains', [
    'headers' => [
        'Authorization' => 'Bearer ' . $accessToken,
        'Accept' => 'application/json',
    ],
    'query' => [
        'page' => 1,
        'per_page' => 20,
    ],
]);

$data = json_decode((string) $response->getBody(), true);

print_r($data['data']);
print_r($data['meta']);

La struttura delle risposte è descritta in Convenzioni comuni delle risposte, la paginazione in Gestione della paginazione.

Limiti di utilizzo

Per garantire la stabilità del servizio, le API applicano alcuni limiti:

60 richieste al minuto per ciascun client;
limiti più stretti su alcuni endpoint particolarmente onerosi, ad esempio la verifica di disponibilità dei domini (GET /api/v3/domains/availability);
5 richieste ogni 15 secondi all'endpoint del token, per IP e client;
un tetto alle risposte 401 per IP: un indirizzo che invia molte richieste con token mancanti o non validi (più di 30 al minuto) riceve 429 per il resto del minuto, anche con un token valido.

Quando superi un limite, la risposta è 429 Too Many Requests con l'header Retry-After, che indica quanti secondi attendere prima di riprovare.

Errori più comuni

Gli errori più frequenti in fase di integrazione sono:

401 Unauthorized: token assente, scaduto, revocato o non valido. Richiedi un nuovo token e ripeti la chiamata una sola volta;
403 Forbidden: il token è valido ma non basta, ad esempio perché non include gli scope richiesti, perché la funzione non è disponibile per il tuo account o perché la richiesta arriva da un IP non autorizzato. Un nuovo token non cambia l'esito: non ripetere la chiamata;
404 Not Found: la risorsa non esiste oppure non appartiene al tuo account;
429 Too Many Requests: hai superato un limite di utilizzo. Attendi i secondi indicati da Retry-After.

Se ricevi un errore OAuth2 da /oauth/token, la risposta segue il formato OAuth2 e può contenere campi come:

error, ad esempio invalid_client o invalid_scope;
error_description;
error_uri.

Ogni risposta delle API, comprese quelle di errore, ha l'header X-Request-Id, che identifica la richiesta. Se devi contattare l'assistenza per una chiamata non andata a buon fine, indica questo valore: permette di ritrovare subito la richiesta nei log.

Buone pratiche

Conserva client_secret e access_token in modo sicuro.
Non inserire credenziali o token direttamente nel codice sorgente: usa variabili d'ambiente o un sistema di gestione dei segreti.
Richiedi solo gli scope realmente necessari.
Gestisci centralmente il token, così da riusarlo in tutte le chiamate API finché è valido.
Rispetta l'header Retry-After quando ricevi un 429.
Se sviluppi in PHP o Python, valuta l'uso degli SDK ufficiali.

In sintesi

Per usare le API Shellrent:

crea un client OAuth2 nel Manager e salva client_id e client_secret;
attiva l'autenticazione a due fattori sul tuo account, se non lo è già;
richiedi un token a /oauth/token con gli scope necessari;
invia l'access_token come Bearer token nelle chiamate /api/v3/...;
quando il token scade, richiedine uno nuovo con le stesse credenziali.

Questa pagina è pensata come introduzione generale. Nelle guide successive potrai approfondire client, scope, formato delle risposte, paginazione, upload e download di file; nelle pagine di riferimento trovi i dettagli di ogni singolo endpoint.

SDK ufficiali​

Specifica OpenAPI​

Come funziona OAuth2 in questa API​

Requisiti dell'account​

Credenziali e scope​

Ottenere un access token​

Esempio con curl​

Esempio in PHP: richiesta del token​

Come gestire l'access token​

Come effettuare una chiamata API autenticata​

Esempio in PHP: leggere il profilo account​

Esempio in PHP: elencare i domini​

Limiti di utilizzo​

Errori più comuni​

Buone pratiche​

In sintesi​