> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ridergy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avvio rapido

> Effettua la tua prima richiesta all'API Energy Management in pochi minuti

Questa guida ti accompagna dall'inizio alla fine: dall'ottenere le credenziali alla pianificazione di un profilo di limite di ricarica e alla sua applicazione.

## Prerequisiti

Ti servono due cose, entrambe dal **dashboard di RiDERgy**:

1. **Credenziali client OAuth** (`client_id` e `client_secret`). Il tuo tenant deve avere l'API Energy Management abilitata. Contatta RiDERgy per abilitarla e creare le tue credenziali — vedi [Autenticazione](/it/authentication).
2. **Gli ID delle risorse che vuoi controllare**: un `locationId`, il `controllerUuid`/`connectorId` di un caricatore, o un `clusterId`. Provengono dal tuo account RiDERgy: se hai un account RiDERgy con una posizione integrata, puoi consultare gli ID nell'**app RiDERgy**. Identificano le stesse posizioni e gli stessi caricatori che vedi lì.

<Note>
  I pannelli interattivi **«Try it»** inviano richieste all'**API di produzione in tempo reale**. Un `POST`/`PUT` qui modifica una posizione reale. Usa solo valori che intendi davvero applicare.
</Note>

## 1. Verificare la connettività

`GET /health` non richiede autenticazione e conferma che l'API è raggiungibile:

```bash theme={null}
curl https://api.ridergy.com/v1/health
```

```json theme={null}
{ "status": "ok" }
```

## 2. Ottenere un token di accesso

Scambia le tue credenziali client per un token Bearer (valido per 1 ora):

```bash theme={null}
curl -X POST https://api.ridergy.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
```

Salva il `access_token` dalla risposta — lo userai nei passaggi seguenti.

## 3. Impostare il limite permanente di una posizione

Il limite permanente è il valore di riserva applicato quando nessun profilo pianificato è attivo.

```bash theme={null}
curl -X PUT https://api.ridergy.com/v1/locations/{locationId}/limit \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limitKw": 100 }'
```

## 4. Pianificare un profilo di priorità

Limita la posizione a 50 kW durante una finestra specifica, con priorità 5:

```bash theme={null}
curl -X POST https://api.ridergy.com/v1/locations/{locationId}/schedules \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-01-01T08:00:00Z",
    "endTime":   "2026-01-01T18:00:00Z",
    "limitKw":   50,
    "priority":  5
  }'
```

Il profilo viene applicato e ripristinato automaticamente ai suoi `startTime`/`endTime` — non sono necessarie ulteriori chiamate API.

## 5. Verificare il limite effettivo

Questo restituisce ogni profilo con uno `status` calcolato (`SCHEDULED`, `ACTIVE`, `EXPIRED`) e il `effectiveLimitKw` attuale:

```bash theme={null}
curl https://api.ridergy.com/v1/locations/{locationId}/limits \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Consulta il [Modello di priorità](/it/concepts/priority-model) per sapere esattamente come viene determinato il limite effettivo.

## Prossimi passi

* [Autenticazione](/it/authentication) — flusso OAuth 2.0, scopes e gestione dei token.
* [Modello di priorità](/it/concepts/priority-model) — come interagiscono profili, priorità e cluster.
* Usa il **Riferimento API** per esplorare ogni endpoint con un ambiente live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.