Introduzione

Le API Shellrent permettono di accedere in modo programmatico ai dati e alle funzionalità del proprio account, ad esempio account utente, domini, 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.

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.

In questa API il flusso principale è client_credentials:

l'applicazione che consuma le API riceve un client_id e un client_secret;
con queste credenziali richiede un access_token;
il token viene poi inviato nelle chiamate API tramite header Authorization: Bearer ....

La piattaforma supporta anche il grant refresh_token, che permette di richiedere un nuovo access_token senza ripetere il flusso iniziale, quando è disponibile un refresh_token.

In pratica:

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

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 chiedere quali permessi vuoi ottenere;
nella chiamata API, per usare un token che includa gli scope richiesti da quello specifico endpoint.

Ad esempio:

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

Se il tuo client è autorizzato, puoi anche richiedere lo scope api:full, che consente di usare tutti gli scope disponibili per quella specifica coppia client_id e client_secret.

Ottenere un access token

L'endpoint OAuth2 per ottenere o rinnovare un token è:

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

La specifica prevede:

grant_type=client_credentials per ottenere un nuovo token;
grant_type=refresh_token per rinnovarlo;
scope per dichiarare gli scope richiesti;
audience, con valori supportati api-public oppure api-internal.

Per l'uso normale delle API pubbliche, il valore di riferimento è api-public.

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',
        'audience' => 'api-public',
        'scope' => 'account:read domains:read',
        // In alternativa, se il client lo consente:
        // 'scope' => 'api:full',
    ],
]);

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

print_r($token);

Una risposta tipica contiene:

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

Come gestire access token e refresh token

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

La gestione consigliata è:

salva access_token, expires_in, scope, audience e, se presente, refresh_token;
calcola il momento di scadenza;
prima di ogni chiamata controlla se il token è ancora valido;
se è scaduto, oppure sta per scadere, richiedine uno nuovo.

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

Rinnovo tramite refresh token

Se la risposta OAuth2 include un refresh_token, puoi usarlo per ottenere un nuovo access_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' => 'refresh_token',
        'refresh_token' => 'YOUR_REFRESH_TOKEN',
        'audience' => 'api-public',
        'scope' => 'account:read domains:read',
    ],
]);

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

print_r($newToken);

Se non disponi di un refresh_token, o se non è più valido, puoi sempre richiedere un nuovo token con client_credentials.

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 oppure api:full.

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

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

Errori più comuni

Gli errori più frequenti in fase di integrazione sono:

401 Unauthorized: token assente, scaduto, non valido o client autenticato in modo errato;
403 Forbidden: il token è valido, ma non include gli scope richiesti;
400 Bad Request: parametri mancanti o malformati, ad esempio grant_type o refresh_token non corretti.

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

error;
error_description;
error_uri.

Buone pratiche

Conserva client_secret, access_token e refresh_token in modo sicuro.
Non inserire credenziali o token direttamente nel codice sorgente.
Richiedi solo gli scope realmente necessari.
Usa api:full solo quando serve davvero avere accesso completo agli scope del client.
Gestisci centralmente il rinnovo del token, così da riusarlo in tutte le chiamate API.

In sintesi

Per usare le API Shellrent:

ottieni client_id e client_secret;
richiedi un token a /oauth/token con gli scope necessari;
conserva scadenza ed eventuale refresh_token;
invia l'access_token come Bearer token nelle chiamate /api/v3/...;
rinnova o rigenera il token quando non è più valido.

Questa pagina è pensata come introduzione generale. Nelle guide successive potrai approfondire i singoli gruppi di endpoint e i casi d'uso specifici.

Come funziona OAuth2 in questa API​

Credenziali e scope​

Ottenere un access token​

Esempio in PHP: richiesta del token​

Come gestire access token e refresh token​

Rinnovo tramite refresh token​

Come effettuare una chiamata API autenticata​

Esempio in PHP: leggere il profilo account​

Esempio in PHP: elencare i domini​

Errori più comuni​

Buone pratiche​

In sintesi​