API di amministrazione dello spazio di lavoro

L'API di amministrazione dello spazio di lavoro consente alle integrazioni server-to-server di amministrare un singolo spazio di lavoro EVCharge. Questa documentazione è destinata agli amministratori degli spazi di lavoro e agli integratori API esterni. Usa token di accesso revocabili, vincolati a uno spazio di lavoro, e ambiti granulari; i token di accesso dei clienti e le sessioni del browser non sono accettati.

Questa directory è il riferimento canonico per gli sviluppatori dell'API /v2/admin implementata da app-api. Non documenta le route dei clienti/mobile né le route HTTP del portale di amministrazione stesso.

• Richieste e risposte degli endpoint elenca tutti gli 87 endpoint registrati, gli ambiti, i parametri, i corpi delle richieste e i corpi delle risposte di successo.
• Schemi ed esempi definisce i tipi riutilizzabili delle richieste/risposte e i payload JSON rappresentativi.
• Contratto delle risposte e degli errori definisce ogni corpo di errore comune e specifico degli endpoint.

URL di base e confine delle risorse

Tutti i percorsi sono relativi all’origine del servizio app-api distribuito:

https://api.evcharge.mobi/v2/admin/...

L'ID dello spazio di lavoro non è accettato nell'URL, nella stringa di query o nel corpo della richiesta. Ogni token di accesso è vincolato esattamente a uno spazio di lavoro e l'API ricava cpoId dall'identità autenticata del token. Se un sito, caricatore, utente, tariffa, profilo, assegnazione o transazione annidato non appartiene a quello spazio di lavoro, l'API restituisce la stessa risposta 404 RESOURCE_NOT_FOUND che non consente l'enumerazione delle risorse.

Ottenere un token di accesso

Un amministratore dello spazio di lavoro crea i token nelle Impostazioni dello spazio di lavoro, alla voce Accesso API. La gestione dei token non è intenzionalmente accessibile ai token dello spazio di lavoro.

• L’accesso API è incluso in ogni piano, anche Free. L’amministratore deve avere il permesso di modificare lo spazio di lavoro.
• L'host dello spazio di lavoro deve abilitare l'API di amministrazione tramite adminApiEnabled; altrimenti un token valido riceve da app-api una risposta 404 che non consente l'enumerazione delle risorse.
• L'amministratore può concedere soltanto gli ambiti consentiti dai propri permessi correnti e dalle abilitazioni dello spazio di lavoro.
• I nuovi token possono essere senza scadenza (valore predefinito nelle Impostazioni dello spazio di lavoro) oppure avere una durata scelta dall'amministratore tra 1 e 365 giorni interi; il server calcola le scadenze assolute finite. I token senza scadenza rimangono validi fino alla revoca.
• Uno spazio di lavoro può avere al massimo 50 token attivi.
• La credenziale in chiaro viene mostrata una sola volta. Salvala immediatamente in un gestore di segreti.
• Nome, ambiti e scadenza sono immutabili. Per la rotazione, crea un token sostitutivo, distribuiscilo, verificalo e revoca quello precedente.
• La revoca è immediata; le righe revocate rimangono visibili come cronologia immutabile dello spazio di lavoro con i dati sensibili oscurati e non sono disponibili endpoint per l'introspezione dei token Bearer o per l'eliminazione definitiva.

app-api non dispone di un endpoint che emetta, rinnovi, elenchi o revochi queste credenziali. Ottenere il token è quindi un prerequisito da soddisfare tramite il portale di amministrazione per utenti umani, non tramite un altro endpoint di questo riferimento.

Non inserire mai il token nel controllo versione, negli URL, nelle stringhe di query, nei cookie, nei registri, nelle analisi o nei report degli errori.

Autenticazione

Invia esattamente un'intestazione in stile RFC 6750 in ogni richiesta:

Authorization: Bearer evc_ws_<selector>.<secret>

La credenziale opaca esatta è evc_ws_ seguito da un selettore base64url canonico di 16 caratteri, . e un segreto base64url canonico di 43 caratteri. Invia la credenziale completa così com'è; non codificarla nuovamente in base64.

L'API rifiuta intestazioni di autorizzazione duplicate, valori uniti da virgole, altri schemi, valori Bearer vuoti, JWT dei clienti e credenziali fornite in qualsiasi posizione diversa da questa intestazione.

I token con formato errato, sconosciuti, scaduti, revocati o comunque non validi ricevono tutti la stessa risposta:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": "INVALID_WORKSPACE_TOKEN"
}

Il servizio controlla lo stato del token e le abilitazioni correnti dello spazio di lavoro a ogni richiesta. La rimozione di un'abilitazione può quindi disabilitare gli ambiti interessati prima della scadenza del token.

I token dello spazio di lavoro sono credenziali opache, non JWT. Non hanno un token di aggiornamento e non esiste un endpoint di aggiornamento. Un token con scadenza smette di autenticare alla sua scadenza assoluta expiresAt; un token senza scadenza rimane valido fino alla revoca. La rotazione consiste nel creare una credenziale sostitutiva nel portale, distribuirla al client e revocare quella precedente.

Convenzioni delle richieste

• Usa Content-Type: application/json per le richieste con un corpo JSON.
• Gli spazi iniziali e finali dei valori facoltativi X-Request-Id della richiesta vengono rimossi; i valori sono accettati solo se contengono da 1 a 128 caratteri tra A-Z, a-z, 0-9, ., _, : o -; altrimenti il server genera un UUID. Ogni risposta restituisce il valore selezionato come X-Request-Id.
• Il parametro facoltativo X-Error-Format: envelope converte ogni risposta di errore JSON nella struttura documentata in Contratto delle risposte e degli errori. Qualsiasi altro valore mantiene il corpo predefinito per compatibilità.
• Gli ID nei parametri del percorso sono interi positivi. Gli ID dei token di accesso restituiti dal portale sono stringhe decimali perché corrispondono a valori di database a 64 bit senza segno.
• Le date e gli orari sono stringhe RFC 3339 con un offset esplicito, per esempio 2026-08-13T12:30:00Z.
• Le eliminazioni riuscite restituiscono normalmente 204 No Content.
• Le operazioni di creazione normalmente restituiscono 201 Created.
• Un'attività OCPP soltanto accodata può restituire 202 Accepted; non interpretarlo come una conferma del caricatore, a meno che la risposta lo indichi esplicitamente.
• Le risposte autenticate usano Cache-Control: no-store. Gli endpoint QR e di esportazione dei report restituiscono corpi binari con intestazioni del contenuto esplicite.
• Le origini del browser consentite possono leggere X-Request-Id, Idempotency-Replayed, Retry-After e Content-Disposition tramite CORS. I client web possono così correlare le richieste, rilevare le ripetizioni idempotenti, rispettare i tempi dei nuovi tentativi e mantenere i nomi dei file di download scelti dal server.

Idempotenza

Tutte le richieste amministrative POST, PUT, PATCH e DELETE devono includere un’intestazione Idempotency-Key. Le chiavi contengono da 1 a 255 caratteri visibili e sono legate al token, al metodo e al percorso.

Idempotency-Key: provisioning-2026-08-13-site-42

Riutilizzare una chiave completata con URL e corpo identici riproduce la risposta memorizzata e aggiunge:

Idempotency-Replayed: true

Riutilizzare una chiave con una richiesta diversa restituisce 409 IDEMPOTENCY_CONFLICT. Una richiesta ancora in elaborazione restituisce 409 IDEMPOTENT_REQUEST_PROCESSING con Retry-After: 5.

Le risposte completate e gli esiti definitivi vengono conservati per ripetizione o riconciliazione per sette giorni dall’ultimo aggiornamento. Dopo tale periodo, la stessa chiave può essere trattata come un nuovo comando: i client devono quindi usare chiavi globalmente univoche e non riutilizzarle intenzionalmente.

Se scade il periodo di riserva dell'elaborazione, la connessione si chiude dopo l'avvio dell'esecuzione o l'operazione restituisce un errore del server, l'API non può determinare con certezza se si sia verificato un effetto esterno. Durante il periodo di conservazione di sette giorni, la chiave rimane in uno stato indeterminato definitivo e restituisce 409 IDEMPOTENCY_OUTCOME_UNKNOWN; non viene riacquisita né eseguita nuovamente in automatico. Verifica gli effetti dell'operazione prima di procedere al ripristino manuale e non inviare la stessa operazione con una nuova chiave finché la verifica non è conclusa.

Tutti gli endpoint amministrativi che modificano dati, incluso POST /reports/send, richiedono Idempotency-Key.

Limiti di frequenza delle richieste

I limiti si applicano sia al singolo token sia al suo spazio di lavoro. I valori predefiniti definiti nel codice sono:

Una richiesta soggetta al limite restituisce 429 Too Many Requests e un’intestazione Retry-After. Le singole installazioni possono sostituire questi valori.

Errori

Gli errori JSON usano un code stabile quando il chiamante deve distinguere i casi:

{
  "error": "Insufficient workspace-token scope",
  "code": "INSUFFICIENT_SCOPE"
}

Gli errori di convalida usano array associati ai campi:

{
  "validationErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Gli stati più comuni sono:

Catalogo degli ambiti

Il seguente catalogo degli ambiti viene usato quando un amministratore crea un token. Un ambito di scrittura o ad alto impatto può implicare il corrispondente ambito di lettura, ma gli ambiti di lettura non concedono mai la scrittura. Gli ambiti disponibili dipendono dai permessi dell'amministratore e dalle funzionalità abilitate nello spazio di lavoro.

L’accesso API in sé è incluso in ogni piano ed è controllato dall’impostazione adminApiEnabled dell’host. I diritti aggiuntivi alle funzioni indicati sopra restano validi; l’accesso API non concede funzioni esterne al piano dello spazio di lavoro.

Riferimento degli endpoint

Le tabelle seguenti elencano tutte le 87 route di amministrazione dello spazio di lavoro. Se una cella contiene più ambiti, sono tutti obbligatori.

Spazio di lavoro

Campi di aggiornamento parziale dello spazio di lavoro: name, email, website, addressLine1, addressLine2, postalCode, city, state e countryId. È richiesto almeno un campo. Le stringhe vuote che ammettono null vengono normalizzate a null.

Siti e gestione della potenza

I corpi di creazione e aggiornamento parziale dei siti usano:

{
  "name": "Main depot",
  "description": null,
  "addressLine1": "1 Example Street",
  "addressLine2": null,
  "postalCode": "LV-1001",
  "city": "Riga",
  "state": null,
  "countryId": 1,
  "timezoneId": 1,
  "latitude": 56.9496,
  "longitude": 24.1052
}

La geocodifica dei siti accetta i campi di query facoltativi street, city, state, country e countryCode di due lettere, oltre all'intestazione di richiesta Accept-Language. La ricerca combinata di via/città/stato o regione deve contenere almeno due caratteri. Le risposte contengono solo placeId, displayName, latitude e longitude; le credenziali e i metadati specifici del fornitore non vengono esposti. Il server applica la coda condivisa del fornitore di una richiesta al secondo, un timeout di otto secondi, una cache limitata di 24 ore e i limiti globali di frequenza dei token dello spazio di lavoro.

La gestione della potenza accetta { "pools": [...] }. Un gruppo contiene id, name, limit, meterSources facoltativo e children ricorsivo. Un caricatore figlio contiene chargepointId e priority. L'API limita le dimensioni dell'albero e il numero di contatori ed esegue la cancellazione OCPP e la nuova convalida in due fasi quando sostituisce lo stato installato. Una modifica rifiutata, scaduta o interessata da una modifica concorrente restituisce 409 POWER_MANAGEMENT_CONFLICT, mantenendo la configurazione precedente.

Caricatori

I parametri di query dei log del caricatore sono cursor, limit (50 predefinito, massimo 200), from, to, action, direction e levelId. I parametri delle sessioni sono page, limit (25 predefinito, massimo 100), from, to e customerId (un ID positivo o unknown). La cronologia delle programmazioni composite usa cursor, limit (20 predefinito, massimo 50) e connectorId facoltativo.

Report

I filtri per i dati e l'esportazione dei report sono from, to, siteId, chargerId, userId, anonymous e active. from/to usano per impostazione predefinita gli ultimi 90 giorni e non possono coprire più di 90 giorni. userId non può essere combinato con anonymous=true.

• Paginazione dei dati: cursor opaco, limit=50 predefinito, massimo 100.
• Misurazioni: transactionLogId obbligatorio, cursor opaco, valore predefinito limit=500, massimo 1.000.
• Esportazione: format=csv|pdf, valore predefinito csv, limite massimo di 2.000 righe.
• Le risposte di esportazione usano Content-Disposition: attachment, Cache-Control: private, no-store e X-Content-Type-Options: nosniff.

Corpo della pianificazione:

{
  "enabled": true,
  "recipientEmail": "reports@example.com",
  "format": "csv",
  "sendDay": 5,
  "sendTime": "08:30"
}

sendDay è compreso tra 1 e 28 e sendTime viene interpretato in UTC. Lo scheduler recupera un minuto pianificato saltato nel mese di consegna corrente. Le generazioni non riuscite prima del passaggio al servizio SMTP vengono ritentate dopo 5 e 10 minuti, un'acquisizione building interrotta può essere ripresa dopo 30 minuti e la consegna automatica si arresta dopo tre tentativi. Lo scheduler salva indeterminate immediatamente prima del passaggio al servizio SMTP; sia indeterminate sia lo stato precedente sending sono definitivi, perché un nuovo tentativo automatico in entrambi i casi potrebbe inviare un allegato duplicato. Gli operatori devono riconciliare questi esiti manualmente prima di modificare lo stato della pianificazione. Ogni ciclo seleziona al massimo dieci pianificazioni, smette di avviare attività dopo un budget di 45 secondi e usa timeout SMTP limitati. Il processo è disabilitato per impostazione predefinita e deve essere abilitato esplicitamente dopo la verifica SMTP e della capacità. La pianificazione API appartiene allo spazio di lavoro anziché usare l'identità della persona che ha creato il token.

Tariffe

Il corpo di una tariffa contiene name, esattamente uno tra currencyId, currencyCode o currency, biddingZoneId facoltativo e tax. Il corpo di un’assegnazione è:

{ "tariffId": 17, "connectorId": 0 }

Quando si crea un'assegnazione, la tariffa si applica a tutti i connettori fisici se connectorId viene omesso o impostato esplicitamente su 0. Gli aggiornamenti riguardano una singola assegnazione persistente e richiedono quindi un valore connectorId fisico esplicito e positivo; 0 viene rifiutato.

Un componente contiene i campi obbligatori typeId, seasonId e price; priority e i limiti di validità per mese, giorno della settimana e ora sono facoltativi.

Profili di ricarica

I campi dei metadati del profilo sono label, locationId, stackLevel, purposeId, kindId, recurrencyKindId facoltativo, validFrom, validTo, startSchedule, rateUnitId e minChargingRate facoltativo. Un periodo di pianificazione contiene startPeriod, limit e numberOfPhases facoltativo. Il corpo di un'assegnazione contiene profileId e connectorId (valore predefinito 0).

L'eliminazione dei profili e la sostituzione della gestione della potenza possono attendere la conferma del caricatore. Un rifiuto, un timeout o una modifica di stato concorrente restituisce un conflitto e mantiene la configurazione nel database, senza presumere che la configurazione del caricatore sia stata cancellata.

Utenti, inviti, RFID, accessi e limiti

La paginazione dei veicoli e la paginazione degli utenti status=members usano un cursor numerico positivo. Le pagine degli inviti usano un cursore i2.* opaco, mentre status=all usa un cursore composito a2.* opaco dopo la prima pagina (un cursore numerico rimane valido soltanto come continuazione del flusso dei membri nel formato precedente). La ricerca degli utenti viene fornita nell'intestazione di richiesta X-Admin-User-Search, per evitare che gli indirizzi email compaiano negli URL o nei registri di accesso. limit ha valore predefinito 50 ed è limitato a 100; l'elenco degli utenti supporta status=all|members|invitations. Considera opachi tutti i cursori restituiti e reinviali senza modificarli.

La creazione diretta di un utente non crea una password, un’identità di accesso o una sessione. Collega solo un cliente già registrato. Usa l’endpoint di invito per un’e-mail sconosciuta. L’utente di sistema Tagless protetto non può essere modificato tramite questi percorsi.

Esempi

Imposta i valori nella shell senza stampare il token:

export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"

Elencare i siti:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Crea un sito in sicurezza:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-main-depot-v1" \
  --data '{
    "name":"Main depot",
    "description":null,
    "addressLine1":"1 Example Street",
    "addressLine2":null,
    "postalCode":"LV-1001",
    "city":"Riga",
    "state":null,
    "countryId":1,
    "timezoneId":1,
    "latitude":56.9496,
    "longitude":24.1052
  }' \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Scarica un report CSV per un intervallo UTC esplicito:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -o report.csv \
  "${ADMIN_API_BASE_URL}/v2/admin/reports/export?format=csv&from=2026-07-01T00%3A00%3A00Z&to=2026-08-01T00%3A00%3A00Z"

Esclusioni intenzionali

L'API dei token dello spazio di lavoro non espone operazioni che richiedono un'identità umana o un'autorità più ampia. Tra queste:

• creazione, visualizzazione, rotazione o revoca di token tramite un altro token;
• accesso, reimpostazione della password, sessioni, delega di ruoli o privilegi umani e cambi di proprietà degli spazi di lavoro;
• creazione/eliminazione degli spazi di lavoro e appartenenza agli account di fatturazione;
• impostazioni di pagamento, attivazione Stripe, piani, fatture e fatturazione dell'host;
• operazioni di assistenza a livello di host e webhook dei fornitori;
• notifiche destinate alle persone, reindirizzamenti di navigazione, risorse del marchio e route di sviluppo/test.