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

# Panoramica dell'API

> API con chiave di servizio per l'analisi del consumo di ACU, la gestione dei gruppi e i limiti ACU nelle distribuzioni federali.

<Info>
  Questa documentazione riguarda le distribuzioni federali di Devin. [Torna alla documentazione di Devin](/it/get-started/devin-intro)
</Info>

Gli amministratori Enterprise federali possono recuperare programmaticamente il consumo di ACU e gestire [gruppi](/it/federal/groups), [disponibilità dei modelli](/it/federal/model-provisioning) e [limiti ACU](/it/federal/acu-limits) tramite un'API con chiave di servizio. Un [SDK Python](/it/federal/api/python-sdk) fornisce un wrapper per ogni endpoint descritto in questa sezione.

Gli endpoint per la gestione dei gruppi e i limiti ACU sono disponibili solo nelle distribuzioni federali self-hosted multi-tenant. Non sono esposti nelle distribuzioni commerciali. Gli endpoint di analisi (`/Analytics`, `/UserPageAnalytics` e `/CascadeAnalytics`) verificano anche il livello di accesso all'analisi della distribuzione; un team senza accesso all'analisi riceve `permission_denied`.

***

<div id="base-url">
  ## Base URL
</div>

Tutte le richieste JSON `POST` vengono inviate al server API della tua distribuzione:

```
https://<your-server>/api/v1/<Method>
```

Sostituisci `<your-server>` con il dominio dell'API della tua distribuzione federale.

<div id="authentication">
  ## Autenticazione
</div>

Ogni richiesta viene autenticata con una **chiave di servizio** inclusa nel corpo della richiesta:

```json theme={null}
{
  "service_key": "your_service_key_here"
}
```

Per creare una chiave di servizio, accedi al portale federale come amministratore del team e vai a **Settings → Service Keys**, quindi crea una chiave con le autorizzazioni richieste dagli endpoint che intendi chiamare.

<Warning>Conserva le chiavi di servizio in modo sicuro. Non esporle mai nel codice lato client né includerle nei commit ai repository.</Warning>

<div id="required-permissions">
  ### Autorizzazioni richieste
</div>

| Endpoint                                                                                                                     | Autorizzazione richiesta |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| [Report legacy sull'utilizzo](/it/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` e `/CascadeAnalytics`) | Teams Read-Only          |
| [Consumo di ACU](/it/federal/api/acu-consumption) (`/Analytics`)                                                             | Analytics Read           |
| [Elencare i gruppi](/it/federal/api/group-management#list-groups) (`/ListGroups`)                                            | Teams Read-Only          |
| [Ottenere un gruppo](/it/federal/api/group-management#get-group) (`/GetGroup`)                                               | Teams Read-Only          |
| [Creare un gruppo](/it/federal/api/group-management#create-group) (`/CreateGroup`)                                           | Teams Update             |
| [Aggiornare un gruppo](/it/federal/api/group-management#update-group) (`/UpdateGroup`)                                       | Teams Update             |
| [Eliminare un gruppo](/it/federal/api/group-management#delete-group) (`/DeleteGroup`)                                        | Teams Update             |
| [Elencare i membri di un gruppo](/it/federal/api/group-management#list-group-members) (`/ListGroupMembers`)                  | Teams Read-Only          |
| [Aggiungere membri a un gruppo](/it/federal/api/group-management#add-group-members) (`/AddGroupMembers`)                     | Teams Update             |
| [Rimuovere membri da un gruppo](/it/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`)               | Teams Update             |
| [Ottenere il limite di ACU di un utente](/it/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`)                    | Teams Read-Only          |
| [Aggiornare il limite di ACU di un utente](/it/federal/api/acu-caps#set-or-clear-a-users-acu-cap) (`/UpdateUserAcuCap`)      | Teams Update             |

<div id="team-scoped-and-group-scoped-keys">
  ### Chiavi con ambito team e gruppo
</div>

Le chiavi di servizio vengono associate a un ambito al momento della creazione:

* Le **chiavi con ambito team** possono recuperare dati dell'intero team e gestire tutti i gruppi del team.
* Le **chiavi con ambito gruppo** sono limitate al gruppo assegnato. Possono leggere il totale aggregato di ACU del gruppo e le righe degli utenti, elencare e leggere solo quel gruppo, nonché leggere o aggiornare i limiti di ACU solo per i membri attuali di quel gruppo. Non possono leggere i totali dell'intero team o le righe degli utenti, visualizzare altri gruppi né creare gruppi.

<div id="pagination">
  ## Paginazione
</div>

L'elenco dei gruppi, dei membri dei gruppi e delle righe ACU per utente è suddiviso in pagine:

* `page_size` — facoltativo; il valore predefinito è 100, con un massimo di 1.000. Se omesso o impostato su `0`, viene usato il valore predefinito.
* `next_page_token` — restituito quando sono disponibili altri risultati. Passalo come `page_token` in una richiesta per il resto identica (incluso lo stesso `page_size`) per recuperare la pagina successiva.

I token di pagina sono opachi e crittografati. Scadono dopo 24 ore. I token relativi al consumo di ACU sono associati all'endpoint, al team, all'ambito, al periodo, alla selezione dei gruppi e alla dimensione della pagina. I token per l'elenco dei gruppi e dei membri sono associati all'endpoint, al team, all'ambito e alla dimensione della pagina. La modifica di un valore associato tra una pagina e l'altra restituisce un errore `invalid_argument`.

<div id="errors">
  ## Errori
</div>

Gli errori vengono restituiti in formato JSON con un codice e un messaggio:

```json theme={null}
{
  "code": "permission_denied",
  "message": "service key role is missing the required permission"
}
```

| Codice                | Significato                                                                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthenticated`     | La chiave di servizio è assente, non valida o scaduta.                                                                                                                                                                 |
| `permission_denied`   | Il ruolo della chiave di servizio non dispone dell'autorizzazione richiesta.                                                                                                                                           |
| `invalid_argument`    | La richiesta non è valida — ad esempio, un periodo non valido, un recupero di Custom Analytics che combina campi tipizzati e personalizzati, un aggiornamento vuoto o un token di pagina scaduto o non corrispondente. |
| `not_found`           | La risorsa non esiste, appartiene a un altro team o non rientra nell'ambito della chiave di servizio. Le risorse di altri team e quelle fuori ambito sono indistinguibili da quelle mancanti.                          |
| `failed_precondition` | La richiesta è valida ma non può essere completata nello stato corrente, ad esempio se si imposta un limite ACU per un team che non usa la fatturazione in ACU o si seleziona un indirizzo email utente ambiguo.       |
| `already_exists`      | Il nome del gruppo richiesto è già utilizzato dal team.                                                                                                                                                                |
| `internal`            | Il servizio non è riuscito a completare la richiesta.                                                                                                                                                                  |