I dati di ricarica raramente restano nella piattaforma di ricarica. L'amministrazione vuole i costi energetici nel sistema contabile, i fleet manager vogliono i consumi per veicolo accanto ai dati telematici e la direzione vuole i numeri della ricarica nelle stesse dashboard di tutto il resto. Copiare file CSV ogni mese funziona per un po', ma non è scalabile.
Un'API di ricarica per veicoli elettrici risolve il problema permettendo ad altri sistemi di leggere i dati di ricarica e di reagire automaticamente agli eventi di ricarica. Questa guida spiega perché e dove integrare, la differenza tra API REST e webhook, quali dati sono tipicamente disponibili, come proteggere i webhook con firme HMAC e come avviare un'integrazione in sicurezza. Include un esempio generico in pseudocodice adattabile a qualsiasi linguaggio.
- Usate l'API REST per prelevare i dati su richiesta o a intervalli programmati; usate i webhook per ricevere gli eventi nel momento in cui accadono.
- Verificate sempre le firme dei webhook con HMAC-SHA256 sul corpo grezzo della richiesta e con un confronto a tempo costante.
- Progettate gestori di webhook idempotenti, perché lo stesso evento può essere consegnato più di una volta.
- Iniziate con un solo caso d'uso in sola lettura, ad esempio l'energia mensile per centro di costo, e poi ampliate.
Perché integrare i dati di ricarica?
Un sistema di gestione della ricarica (CSMS) è la fonte di riferimento per sessioni, energia e stato delle colonnine. Altri sistemi hanno bisogno di parte di questi dati:
- ERP e contabilità: registrare i costi di ricarica per sito, reparto o centro di costo senza inserimenti manuali.
- Gestione flotta: aggiungere l'energia per veicolo e per conducente alle schede dei veicoli. Leggete la nostra guida alla gestione della ricarica delle flotte per capire come funziona la ripartizione dei costi.
- Business intelligence (BI): combinare dati di utilizzo e di energia con altri dati aziendali in un unico strumento di reportistica.
- Sistemi immobiliari e di facility management: ripartire l'energia di ricarica tra inquilini, residenti o ospiti dell'hotel.
- Notifiche interne: avvisare un addetto alla logistica quando un veicolo ha terminato la ricarica, oppure aprire un ticket quando una colonnina va in guasto.
L'integrazione elimina il lavoro manuale ripetitivo, riduce gli errori di trascrizione e rende i dati disponibili prima.
API REST e webhook a confronto
La maggior parte delle piattaforme di ricarica offre due metodi di integrazione complementari.
| API REST | Webhook | |
|---|---|---|
| Direzione | Il vostro sistema richiede i dati alla piattaforma (pull) | La piattaforma invia i dati al vostro sistema (push) |
| Tempistica | Quando li richiedete, ad esempio ogni notte o su azione dell'utente | Poco dopo che si verifica un evento |
| Uso tipico | Report, riconciliazione, esportazioni massive, consultazioni | Reazioni in tempo reale come notifiche o dashboard live |
| Autenticazione | Chiave API inviata dal vostro sistema | Firma inviata dalla piattaforma e verificata dal vostro sistema |
| Cosa dovete gestire | Un client o un job programmato | Un endpoint HTTPS raggiungibile pubblicamente |
In pratica, le integrazioni robuste usano entrambi. I webhook consegnano rapidamente gli eventi e una chiamata REST periodica riconcilia i dati e colma eventuali lacune, ad esempio se il vostro endpoint è rimasto fermo per manutenzione.
Dati tipici di un'API di ricarica per veicoli elettrici
- Sessioni: ora di inizio e fine, stazione, connettore, energia in kWh, identificativo (tessera), conducente e targa del veicolo, se disponibili.
- Stazioni e connettori: identificativi, posizione, versione OCPP, stato attuale.
- Conducenti e tessere: quale tessera appartiene a quale conducente e se è attiva o bloccata.
- Veicoli: targhe e conducenti a cui sono associati.
- Riepiloghi energetici: totali per stazione, conducente, veicolo o periodo.
Risorse, nomi dei campi e filtri esatti variano da una piattaforma all'altra, quindi lavorate sempre partendo dalla documentazione API ufficiale.
Sicurezza dei webhook: firme, idempotenza e retry
Un endpoint webhook è un URL pubblico: chiunque lo conosca può inviargli richieste. Tre pratiche rendono la gestione dei webhook sicura e affidabile.
1. Verificate la firma HMAC
Con la firma HMAC, la piattaforma e il vostro sistema condividono un segreto. Per ogni consegna, la piattaforma calcola un valore HMAC-SHA256 sul corpo della richiesta usando quel segreto e lo invia in un header di firma. Il vostro sistema calcola lo stesso valore e confronta i due. Se coincidono, la richiesta proviene da qualcuno che conosce il segreto e il corpo non è stato modificato durante il transito.
- Calcolate l'HMAC sul corpo grezzo della richiesta, esattamente come ricevuto. Analizzare e riserializzare il JSON può cambiare spaziature o ordine delle chiavi e invalidare la firma.
- Confrontate le firme con una funzione a tempo costante per evitare attacchi basati sui tempi di risposta (timing attack).
- Custodite il segreto come una password: in un secrets manager o in una variabile d'ambiente, mai nel codice sorgente.
- Se la piattaforma include un timestamp nei dati firmati, rifiutate le consegne troppo vecchie per limitare gli attacchi di replay.
2. Rendete idempotenti i gestori
La consegna dei webhook è di solito di tipo "at least once" (almeno una volta). Lo stesso evento può arrivare due volte, ad esempio quando la vostra risposta si è persa in rete. Memorizzate un identificativo per ogni evento elaborato, come un ID evento se il payload lo fornisce, oppure una combinazione di ID sessione e tipo di evento, e ignorate i duplicati.
3. Rispondete rapidamente e gestite i retry
Restituite rapidamente uno stato di successo (un codice 2xx) ed eseguite le elaborazioni pesanti in un job in background. I gestori lenti possono andare in timeout e provocare nuove consegne. Consultate la documentazione della piattaforma per il suo comportamento in caso di retry e usate chiamate REST programmate per riconciliare ciò che è andato perso.
Esempio di flusso in pseudocodice
L'esempio seguente mostra un gestore di webhook generico che verifica la firma, elimina i duplicati e mette in coda un evento di "sessione terminata" per l'elaborazione. Nome dell'header, nomi degli eventi e campi del payload sono segnaposto; usate i valori indicati nella documentazione API della vostra piattaforma.
function handle_webhook(request): raw_body = request.raw_body # byte, prima di qualsiasi parsing JSON received = request.header(SIGNATURE_HEADER) # vedi la documentazione API secret = env("WEBHOOK_SECRET") expected = hex(hmac_sha256(key = secret, message = raw_body)) if not constant_time_equals(expected, received): return response(status = 401) event = json_parse(raw_body) event_key = event.id or (event.session_id + ":" + event.type) if processed_events.contains(event_key): return response(status = 200) # duplicato, già gestito processed_events.add(event_key) queue.push(event) # l'elaborazione pesante avviene dopo return response(status = 200)function worker(event): if is_session_stopped(event): cost_center = lookup_cost_center(event.driver, event.vehicle) erp.post_energy(cost_center, event.energy_kwh, event.ended_at)function nightly_reconciliation(): sessions = api.get_sessions(date = yesterday) # API REST, chiave API for session in sessions: if not erp.has_session(session.id): erp.post_energy(...)La maggior parte dei linguaggi offre una funzione HMAC-SHA256 e una funzione di confronto a tempo costante nella libreria standard o in un noto pacchetto di crittografia. Usate quelle invece di scriverne di vostre.
Integrazione con Üreticy
Üreticy fornisce un'API REST con chiavi API che create e gestite nella dashboard, e webhook firmati HMAC per eventi come sessione avviata e sessione terminata. La documentazione API pubblica descrive risorse, tipi di evento, payload e l'header di firma usato per la verifica.
Poiché Üreticy gestisce colonnine OCPP 1.6J, 2.0.1 e 2.1 in un'unica dashboard, una sola integrazione può coprire un parco colonnine misto. Approfondite nella pagina su API di ricarica e webhook.
Consigli per l'avvio
- Iniziate con un solo caso d'uso. Ad esempio, l'energia mensile per centro di costo registrata nel sistema ERP.
- Usate chiavi API separate per ogni integrazione. Così potete revocarne una senza influire sulle altre.
- Concedete solo gli accessi strettamente necessari. Un'integrazione di reportistica non dovrebbe poter modificare la configurazione.
- Testate con sessioni reali. Confrontate i risultati dell'API con la dashboard e con i report esportati prima di andare in produzione.
- Registrate ogni consegna di webhook. Annotate orario, tipo di evento ed esito della verifica della firma per semplificare la diagnosi.
- Pianificate la rotazione delle chiavi. Sappiate come sostituire chiavi API e segreti dei webhook senza interruzioni del servizio.
- Monitorate l'integrazione. Impostate un avviso quando non arrivano webhook per un periodo insolito o quando la riconciliazione trova lacune.
Quando confrontate le piattaforme di ricarica, la qualità dell'API e dei webhook merita un posto nella checklist. Leggete come scegliere un software OCPP per un elenco di valutazione completo.
Domande frequenti
Cos'è un'API di ricarica per veicoli elettrici?
Un'API di ricarica per veicoli elettrici è un'interfaccia che permette ad altri software di leggere i dati di una piattaforma di gestione della ricarica e di reagire ai suoi eventi. I dati tipici comprendono sessioni, energia, stazioni, conducenti e tessere. Si usa per collegare la ricarica a sistemi ERP, di gestione flotta, contabili e di BI.
Meglio usare un'API REST o i webhook?
Usate i webhook quando dovete reagire rapidamente agli eventi, come la fine di una sessione. Usate l'API REST per report, consultazioni e riconciliazione. Le integrazioni robuste di solito combinano entrambi.
Come si verifica la firma di un webhook?
Calcolate un valore HMAC-SHA256 sul corpo grezzo della richiesta usando il vostro segreto del webhook, poi confrontatelo con il valore nell'header di firma tramite un confronto a tempo costante. Rifiutate la richiesta se i valori non coincidono. Non analizzate e riserializzate il corpo prima di calcolare l'HMAC.
Perché ricevo lo stesso webhook due volte?
I webhook vengono di solito consegnati almeno una volta, quindi una consegna può essere ripetuta se la piattaforma non ha ricevuto la vostra risposta in tempo. Memorizzate un identificativo per ogni evento elaborato e ignorate i duplicati. In questo modo il vostro gestore diventa idempotente.
OCPP è la stessa cosa di un'API di ricarica?
No. OCPP collega le colonnine al sistema di gestione della ricarica. Un'API di ricarica collega il sistema di gestione agli altri software aziendali. Operano a livelli diversi e si completano a vicenda.
Collegate le sessioni di ricarica ai vostri strumenti ERP, di gestione flotta o di BI con un'API REST e webhook firmati HMAC. Scoprite l'API di ricarica di Üreticy o leggete la documentazione API.