Ortak Şarj Platformu OCPI API'sine
entegrasyon kılavuzu
Şarj ağınızı (CPO) ya da mobilite servisinizi (eMSP) Ortak Şarj Platformu'na OCPI 2.2.1 standardıyla bağlamak için ihtiyacınız olan her şey: handshake, kimlik doğrulama ve endpoint örnekleri.
Ortak Şarj Platformu nedir, ne işe yarar?
Ortak Şarj Platformu, elektrikli araç şarj ekosistemindeki tarafları tek noktadan birbirine bağlayan bir OCPI Hub'ıdır. Her partnerin diğer her partnerle ayrı ayrı entegrasyon yapması yerine, herkes yalnızca Hub ile konuşur.
Tek bağlantı noktası
CPO ve eMSP'ler N×N entegrasyon yükünden kurtulur; herkes yalnızca Hub'a tek bir OCPI bağlantısı kurar.
Standart protokol
OCPI 2.2.1 açık standardını kullanır. Mevcut OCPI uyumlu sisteminizle uyumludur, özel format gerektirmez.
Komut yönlendirme
Şarj başlat/durdur, rezervasyon ve konnektör kilidi açma komutlarını doğru CPO'ya yönlendirir.
CDR & faturalama verisi
Şarj oturumu kayıtları (CDR) Hub üzerinden iletilir; mutabakat ve faturalama tek kaynaktan beslenir.
Canlı partner durumu
HubClientInfo modülü ile bağlı tüm partnerlerin çevrimiçi/çevrimdışı durumunu anlık görürsünüz.
İstek logları
Admin uçları üzerinden gelen isteklerin loglarını filtreleyerek entegrasyon hatalarını hızlıca ayıklayın.
Test ortamı: Bu kılavuz testapiv2.ortaksarjplatformu.com test sunucusu içindir. Burada üretilen veriler gerçek faturalamayı etkilemez; entegrasyonunuzu güvenle test edebilirsiniz.
Hub veriyi nasıl taşır?
CPO (şarj operatörü) ve eMSP (mobilite servis sağlayıcısı) doğrudan birbirine bağlanmaz. Tüm istekler Ortak Şarj Platformu üzerinden geçer ve doğru tarafa yönlendirilir.
İstek akışı
eMSP bir şarj başlatma komutu gönderdiğinde, Hub Ocpi-To-* başlıklarına bakarak isteği ilgili CPO'ya iletir ve yanıtı geri taşır.
Asenkron yanıtlar
Komutlar ve şarj profilleri asenkrondur: Hub önce kabul (ACK) döner, gerçek sonucu daha sonra sizin response_url adresinize POST eder.
Kimlik & yetki
Hub her isteği token ve From başlığıyla doğrular; bir partnerin başka bir partner adına işlem yapması engellenir.
5 adımda OCPI handshake
Hub'a bağlanmak, OCPI'nin "credentials handshake" sürecini tamamlamak demektir. Sonunda iki taraf da kalıcı erişim token'ına sahip olur.
Token A'yı edinin
Ortak Şarj Platformu ekibi sizin için bir kayıt token'ı (Token A) üretir ve sizinle güvenli bir kanaldan paylaşır. Bu token yalnızca ilk kayıt için kullanılır ve tek seferliktir.
POST /admin/credentials-tokens
Authorization: Token <ADMIN_TOKEN>Sürüm bilgisini okuyun
Token A ile Hub'ın versions ucunu çağırın. Desteklenen OCPI sürümlerini ve her sürümün endpoint listesini öğrenirsiniz. 2.2.1 sürümünü seçin.
GET /ocpi/versions
Authorization: Token <TOKEN_A>Credentials gönderin
Token A ile credentials ucuna POST yapın. Gövdede kendi token'ınızı (Hub'ın size erişmesi için), versions URL'inizi ve rollerinizi (CPO/eMSP) bildirirsiniz.
POST /ocpi/2.2.1/credentials
Authorization: Token <TOKEN_A>
Content-Type: application/json
{
"token": "<SIZIN_TOKENINIZ>",
"url": "https://sizin-sisteminiz.com/ocpi/versions",
"roles": [{
"role": "CPO",
"country_code": "TR",
"party_id": "ABC",
"business_details": { "name": "Şirket Adı" }
}]
}Kalıcı token'ı alın
Hub bilgilerinizi doğrular, sizin versions ucunuzu çağırarak endpoint'lerinizi kaydeder ve yanıtta kendi kalıcı token'ını döner. Token A bu noktadan sonra geçersizleşir.
{
"status_code": 1000,
"data": {
"token": "<HUB_KALICI_TOKEN>",
"url": "https://testapiv2.ortaksarjplatformu.com/ocpi/versions"
}
}Artık entegresiniz
Bundan sonra Hub'a yaptığınız her istekte 4. adımda aldığınız kalıcı token'ı kullanırsınız. CDR gönderme, komut iletme ve diğer tüm modüller artık erişiminize açıktır.
GET /ocpi/2.2.1/hubclientinfo
Authorization: Token <HUB_KALICI_TOKEN>
From: TR-ABCToken'ların tam formatı (örn. Token mı Bearer mı, base64 kodlu mu) ve istek/yanıt şemalarının kesin alan adları için her zaman canlı Swagger dokümanını tek doğru kaynak olarak kabul edin.
İstek başlıkları
Handshake dışındaki her istekte üç tür başlık rol oynar: kimlik doğrulama, kaynak partner ve komutlarda hedef partner.
| Başlık | Açıklama |
|---|---|
| Authorization zorunlu | Hub tarafından size verilen erişim token'ı. Her istekte gönderilmelidir; eksik veya hatalı olması 401 döndürür. |
| From zorunlu | İsteği yapan partnerin kimliği (ülke kodu + party ID, örn. TR-ABC). Token ile eşleşmezse 403 alırsınız. |
| Ocpi-To-Country-Code komutlarda | Komut endpoint'lerinde hedef partnerin ülke kodu. Hub isteği bu partnere yönlendirir. |
| Ocpi-To-Party-Id komutlarda | Komut endpoint'lerinde hedef partnerin party ID değeri. |
| Content-Type gövdeli | Gövde gönderen POST/PUT isteklerinde application/json olmalıdır. |
POST /ocpi/2.2.1/commands/START_SESSION
Authorization: Token <HUB_KALICI_TOKEN>
From: TR-ABC
Ocpi-To-Country-Code: TR
Ocpi-To-Party-Id: XYZ
Content-Type: application/jsonGüvenlik: Token'larınızı yalnızca sunucu tarafında, ortam değişkenlerinde saklayın. Asla tarayıcı koduna gömmeyin, log'a yazmayın veya sürüm kontrolüne commit etmeyin. Tüm trafik HTTPS üzerinden gitmelidir.
Modül modül API referansı
Endpoint'ler işlevsel modüllere ayrılmıştır. Bir gruba tıklayarak içindeki uçları görebilirsiniz. Tam parametre ve şema detayı için Swagger'a bakın.
Versions modülü: Yukarıdaki tüm modüllere erişmeden önce /ocpi/versions ve sürüm detay ucu handshake sırasında kullanılır. Bunlar OCPI standardının zorunlu parçasıdır.
Yanıtları yorumlama
OCPI iki katmanlı bir yanıt modeli kullanır: HTTP durum kodu taşıma katmanını, gövdedeki status_code ise OCPI iş mantığı sonucunu belirtir. İkisini birlikte değerlendirin.
HTTP durum kodları
OCPI status_code aralıkları (gövde)
{
"status_code": 1000,
"status_message": "Success",
"data": { ... },
"timestamp": "2026-05-18T10:30:00Z"
}Sık sorulan sorular
Bize ulaşın
Entegrasyon, talep veya sorularınız için formu doldurun; ekibimiz en kısa sürede sizinle iletişime geçsin.
Entegrasyona hazır mısınız?
Tüm endpoint'leri canlı Swagger arayüzünden deneyebilir, istek ve yanıt şemalarının en güncel halini görebilirsiniz.
Swagger Dokümanını Aç