Elektrikli Araç Şarj API'si ve Webhook'lar: Entegrasyon Rehberi

Şarj verileri nadiren şarj platformunun içinde kalır. Finans ekibi enerji maliyetlerini muhasebe sisteminde görmek ister, filo yöneticileri araç bazındaki tüketimi telematik verilerinin yanında görmek ister, yönetim ise şarj rakamlarını diğer tüm göstergelerle aynı panolarda izlemek ister. Her ay CSV dosyalarını kopyalamak bir süre işe yarar, ancak ölçeklenmez.

Elektrikli araç şarj API'si, diğer sistemlerin şarj verilerini okumasını ve şarj olaylarına otomatik olarak tepki vermesini sağlayarak bu sorunu çözer. Bu rehber neden ve nerede entegrasyon yapılacağını, REST API ile webhook arasındaki farkı, genellikle hangi verilerin sunulduğunu, webhook'ların HMAC imzalarıyla nasıl güvence altına alınacağını ve bir entegrasyonun güvenle nasıl devreye alınacağını açıklıyor. Ayrıca herhangi bir programlama diline uyarlayabileceğiniz genel bir sözde kod (pseudo-code) örneği içeriyor.

Şarj verilerini neden entegre etmelisiniz?

Bir şarj istasyonu yönetim sistemi (CSMS), oturumlar, enerji ve şarj cihazı durumu için tek doğru kaynaktır. Diğer sistemler bu verilerin belirli kısımlarına ihtiyaç duyar:

• ERP ve muhasebe: Şarj maliyetlerini lokasyon, departman veya masraf merkezi bazında elle veri girişi yapmadan kaydedin.
• Filo yönetimi: Araç ve sürücü bazındaki enerjiyi araç kayıtlarına ekleyin. Maliyet dağıtımının nasıl işlediğini görmek için filo şarj yönetimi rehberimize göz atın.
• İş zekâsı (BI): Kullanım ve enerji verilerini diğer iş verileriyle tek bir raporlama aracında birleştirin.
• Mülk ve tesis yönetim sistemleri: Şarj enerjisini kiracılara, site sakinlerine veya otel misafirlerine paylaştırın.
• Dahili bildirimler: Bir aracın şarjı tamamlandığında sevkiyat sorumlusunu bilgilendirin veya bir şarj cihazı arızalandığında otomatik olarak destek kaydı açın.

Entegrasyon tekrarlayan manuel işleri ortadan kaldırır, veri aktarım hatalarını azaltır ve verilerin daha erken kullanılabilir olmasını sağlar.

REST API ve webhook karşılaştırması

Çoğu şarj platformu birbirini tamamlayan iki entegrasyon yöntemi sunar.

Pratikte sağlam entegrasyonlar ikisini birlikte kullanır. Webhook'lar olayları hızla iletir; periyodik bir REST çağrısı ise verileri mutabık kılar ve örneğin uç noktanız bakım nedeniyle kapalıyken oluşan boşlukları doldurur.

Elektrikli araç şarj API'sinde tipik veriler

• Oturumlar: Başlangıç ve bitiş zamanı, istasyon, konnektör, kWh cinsinden enerji, tanımlayıcı (kart) ve varsa sürücü ile araç plakası.
• İstasyonlar ve konnektörler: Tanımlayıcılar, konum, OCPP sürümü, güncel durum.
• Sürücüler ve kartlar: Hangi kartın hangi sürücüye ait olduğu ve kartın aktif mi yoksa engelli mi olduğu.
• Araçlar: Plakalar ve bağlı oldukları sürücüler.
• Enerji özetleri: İstasyon, sürücü, araç veya dönem bazında toplamlar.

Kaynaklar, alan adları ve filtreler platformdan platforma farklılık gösterir; bu nedenle her zaman resmi API dokümantasyonunu esas alın.

Webhook güvenliği: imzalar, idempotency ve yeniden denemeler

Bir webhook uç noktası herkese açık bir URL'dir. Adresi bilen herkes ona istek gönderebilir. Üç uygulama, webhook işlemeyi güvenli ve güvenilir hâle getirir.

1. HMAC imzasını doğrulayın

HMAC imzalamada platform ile sisteminiz ortak bir gizli anahtar (secret) paylaşır. Platform her gönderimde bu anahtarı kullanarak istek gövdesi üzerinden bir HMAC-SHA256 değeri hesaplar ve bunu bir imza başlığında gönderir. Sisteminiz aynı değeri hesaplar ve ikisini karşılaştırır. Eşleşiyorlarsa istek, gizli anahtarı bilen biri tarafından gönderilmiştir ve gövde yolda değiştirilmemiştir.

• HMAC değerini ham istek gövdesi üzerinden, tam olarak alındığı hâliyle hesaplayın. JSON'u ayrıştırıp yeniden serileştirmek boşlukları veya anahtar sırasını değiştirebilir ve imzayı bozabilir.
• Zamanlama saldırılarını önlemek için imzaları sabit zamanlı bir fonksiyonla karşılaştırın.
• Gizli anahtarı bir parola gibi saklayın: kaynak kodda değil, bir gizli bilgi yöneticisinde veya ortam değişkeninde.
• Platform imzalanan veriye bir zaman damgası ekliyorsa, tekrar oynatma (replay) saldırılarını sınırlamak için eski gönderimleri reddedin.

2. İşleyicileri idempotent yapın

Webhook iletimi genellikle "en az bir kez" esasına dayanır. Aynı olay, örneğin yanıtınız ağda kaybolduğunda, iki kez gelebilir. İşlenen her olay için bir tanımlayıcı saklayın (yük içinde varsa bir olay kimliği ya da oturum kimliği ile olay tipinin birleşimi) ve yinelenen olayları yok sayın.

3. Hızlı yanıt verin ve yeniden denemeleri yönetin

Başarılı bir durum kodunu (2xx) hızla döndürün ve ağır işleri bir arka plan görevinde yapın. Yavaş işleyiciler zaman aşımına uğrayıp yeniden gönderimleri tetikleyebilir. Platformun yeniden deneme davranışını dokümantasyonundan kontrol edin ve kaçırılan her şeyi mutabık kılmak için zamanlanmış REST çağrıları kullanın.

Sözde kodla örnek akış

Aşağıdaki örnek; imzayı doğrulayan, yinelenen olayları ayıklayan ve bir "oturum durduruldu" olayını işlenmek üzere kuyruğa ekleyen genel bir webhook işleyicisini gösteriyor. Başlık adı, olay adları ve yük alanları yer tutucudur; platformunuzun API dokümantasyonunda verilen değerleri kullanın.

function handle_webhook(request):    raw_body  = request.raw_body            # bayt; JSON ayrıştırılmadan önce    received  = request.header(SIGNATURE_HEADER)   # API dokümantasyonuna bakın    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)       # yinelenen olay, zaten işlendi    processed_events.add(event_key)    queue.push(event)                       # ağır iş daha sonra yapılır    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)   # REST API, API anahtarı    for session in sessions:        if not erp.has_session(session.id):            erp.post_energy(...)

Çoğu programlama dili, standart kütüphanesinde veya yaygın bir kriptografi paketinde HMAC-SHA256 fonksiyonu ve sabit zamanlı karşılaştırma fonksiyonu sunar. Kendi fonksiyonunuzu yazmak yerine bunları kullanın.

Üreticy ile entegrasyon

Üreticy, panelden oluşturup yönettiğiniz API anahtarlarıyla çalışan bir REST API ve oturum başladı, oturum durduruldu gibi olaylar için HMAC ile imzalanmış webhook'lar sunar. Herkese açık API dokümantasyonu; kaynakları, olay tiplerini, yük yapılarını ve doğrulama için kullanılan imza başlığını açıklar.

Üreticy OCPP 1.6J, 2.0.1 ve 2.1 şarj cihazlarını tek panelde yönettiği için tek bir entegrasyon, karma bir şarj cihazı parkını kapsayabilir. Ayrıntılar için şarj API'si ve webhook'lar sayfasına göz atın.

Devreye alma ipuçları

1. Tek bir kullanım senaryosuyla başlayın. Örneğin masraf merkezi bazında aylık enerjinin ERP sistemine aktarılması.
2. Her entegrasyon için ayrı API anahtarı kullanın. Böylece bir entegrasyonun erişimini diğerlerini etkilemeden iptal edebilirsiniz.
3. Yalnızca gereken en düşük erişimi verin. Bir raporlama entegrasyonu yapılandırma değiştirebilmemelidir.
4. Gerçek oturumlarla test edin. Canlıya geçmeden önce API sonuçlarını panel ve dışa aktarılan raporlarla karşılaştırın.
5. Her webhook gönderimini kaydedin. Arıza gidermeyi kolaylaştırmak için zamanı, olay tipini ve imza doğrulamasının sonucunu kaydedin.
6. Anahtar yenilemeyi planlayın. API anahtarlarını ve webhook gizli anahtarlarını kesinti yaşamadan nasıl değiştireceğinizi bilin.
7. Entegrasyonu izleyin. Olağandışı uzun bir süre webhook gelmediğinde veya mutabakat boşluklar bulduğunda alarm üretin.

Şarj platformlarını karşılaştırırken API ve webhook kalitesi kontrol listenizde yer almalıdır. Eksiksiz bir değerlendirme listesi için OCPP yazılımı nasıl seçilir yazımıza göz atın.

Sıkça sorulan sorular

REST API ve HMAC ile imzalanmış webhook'larla şarj oturumlarını ERP, filo veya BI araçlarınıza bağlayın. Üreticy şarj API'sini inceleyin ya da API dokümantasyonunu okuyun.