I moduli di OCPI 2.2.1 spiegati: Locations, Sessions, CDR, Tariffs e altro

OCPI (Open Charge Point Interface) è il protocollo con cui reti di ricarica e fornitori di servizi di mobilità si scambiano posizioni, sessioni, prezzi e record di fatturazione. La versione 2.2.1 è oggi la più diffusa in Europa. Se colleghi un CSMS a un partner di roaming o a una piattaforma, passerai gran parte del tempo all'interno dei suoi moduli.

Questa guida spiega ogni modulo, chi invia e chi riceve i dati e dove le integrazioni si inceppano più spesso. Per il quadro generale parti da cos'è OCPI e dalla differenza con OCPP.

Come è organizzato OCPI 2.2.1

OCPI è un protocollo REST/JSON. Ogni parte espone endpoint HTTPS e chiama quelli dell'altra. I moduli sono raggruppati per scopo e ciascuno è implementato come coppia di interfacce: il Sender possiede i dati, il Receiver li memorizza o agisce di conseguenza. Un CPO, per esempio, è Sender per Locations e Receiver per Tokens.

La versione 2.2 ha introdotto il supporto esplicito alle piattaforme, ai ruoli e a nuovi moduli; la 2.2.1 ha corretto e chiarito la 2.2. Versioni successive come la 2.3.0 aggiungono funzioni, ma la 2.2.1 resta la base comune tra piattaforme e partner.

Moduli di configurazione

Versions

Il modulo Versions comunica al partner quali versioni di OCPI supporti e, per ciascuna, l'elenco degli endpoint con i rispettivi ruoli. È sempre la prima chiamata di un'integrazione.

Credentials e registrazione

Credentials stabilisce il collegamento sicuro. La parte A riceve un token (spesso chiamato Token A) per altra via, chiama l'endpoint Versions della parte B e invia in POST le proprie credenziali con un nuovo Token B. La parte B risponde con un Token C, che A userà per tutte le chiamate successive. L'oggetto Credentials elenca anche i ruoli di ogni parte, come CPO, EMSP o HUB, con codice paese e party ID.

I moduli funzionali in breve

Locations

Locations segue una gerarchia a tre livelli: una Location (il sito) contiene EVSE, e ogni EVSE contiene connettori. Gli EVSE riportano lo stato visibile nelle app, come AVAILABLE, CHARGING o OUTOFORDER, e devono avere un EVSE ID formattato correttamente. I connettori descrivono standard, formato, tipo di corrente, tensione, amperaggio e tariffe applicabili.

Invia i cambi di stato ai partner appena avvengono. Una colonnina che appare libera nell'app di un partner ma è guasta genera conducenti arrabbiati e ticket di assistenza.

Sessions

Il modulo Sessions permette all'MSP di mostrare al conducente l'avanzamento in diretta: kWh erogati, ora di inizio e costo fino a quel momento. Il CPO crea la sessione all'avvio e la aggiorna durante la ricarica. Le sessioni non servono per fatturare: quello è il compito dei CDR.

CDRs

Un CDR è il record definitivo e immutabile di una sessione: identità, luogo, inizio e fine, energia, periodi di ricarica, tariffe applicate e importo totale. Viene creato una volta e non aggiornato; le correzioni avvengono con un CDR di storno. Approfondisci nella nostra guida ai charge detail record.

Tariffs

Tariffs descrive componenti di prezzo come ENERGY, TIME, PARKING_TIME e FLAT, con restrizioni per fascia oraria, giorno della settimana, kWh minimi o massimi e intervalli di potenza. La struttura è potente ma facile da usare male. Pubblica tariffe che riproducano esattamente ciò che addebiti, altrimenti i partner contesteranno i CDR. Per il disegno commerciale vedi i modelli tariffari.

Tokens

Tokens è l'elenco degli identificativi validi dei conducenti dell'MSP, di solito UID RFID e token di app. Il CPO può memorizzarli in cache per autorizzare rapidamente e richiedere un'autorizzazione in tempo reale per token sconosciuti. Un buon CSMS usa la cache quando il partner è lento o offline, insieme alla logica di autorizzazione RFID della colonnina.

Commands

Commands consente a un MSP di chiedere al CPO START_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION o UNLOCK_CONNECTOR. I comandi sono asincroni: il CPO conferma prima di aver accettato la richiesta, poi invia il risultato effettivo a un URL di risposta quando la colonnina risponde. Internamente il CSMS li traduce in messaggi OCPP come RemoteStartTransaction.

ChargingProfiles

ChargingProfiles permette a un fornitore di smart charging di impostare un limite su una sessione attiva, leggere il profilo attivo o cancellarlo. Anche qui i risultati sono asincroni. È utile quando a ottimizzare la ricarica è un servizio energetico e non il CPO.

HubClientInfo

Se sei collegato tramite una piattaforma, HubClientInfo ti dice quali altre parti sono collegate e raggiungibili. Usalo per evitare richieste verso partner offline.

Push, pull e paginazione

La maggior parte dei moduli supporta il push (il Sender chiama il Receiver a ogni cambiamento) e il pull (il Receiver scarica periodicamente gli elenchi). Il pull usa date_from, date_to, offset e limit, con le informazioni di paginazione negli header Link, X-Total-Count e X-Limit. Usa il push per il tempo reale e il pull come rete di sicurezza per i messaggi persi.

Codici di stato OCPI

Errori di integrazione frequenti

• Codifica del token: OCPI 2.2 si aspetta il token codificato in Base64 nell'header Authorization; un errore genera 401 silenziosi.
• Fusi orari: tutti i timestamp sono in UTC; gli orari locali vanno nel campo fuso orario della Location.
• Party ID: codice paese e party ID devono coincidere su ogni oggetto, altrimenti i partner rifiutano.
• Tariffe incoerenti: un importo di CDR non ricalcolabile dalla tariffa pubblicata porta a contestazioni.
• Nessun nuovo tentativo: un push fallito va ripetuto e i pull periodici devono colmare i vuoti.

Domande frequenti

Üreticy supporta il roaming OCPI insieme a OCPP 1.6J, 2.0.1 e 2.1, con log completi per ogni partner. Scopri la piattaforma oppure parla con il nostro team.