Integratorzy

API EV24® umożliwia integrację server-to-server dla partnerów i klientów, którzy mają włączony dostęp do API w swoim profilu.

Dla kogo jest API EV24®

API integracyjne EV24® jest przeznaczone dla:

partnerów, którzy zarządzają klientami lub chcą zautomatyzować wybrane procesy w swojej organizacji,
klientów, którzy potrzebują programowego dostępu do funkcji udostępnionych w ramach integracji,
zespołów technicznych realizujących integracje system-system z platformą EV24®.

Dwa rodzaje API

EV24® udostępnia dwa uzupełniające się mechanizmy integracji. REST API służy do aktywnego odpytywania platformy i wykonywania operacji, a webhooki dostarczają powiadomienia o zdarzeniach automatycznie, gdy coś wydarzy się po stronie EV24®.

Rodzaj	Kierunek	Model komunikacji	Zastosowanie
REST API	Ty → EV24®	żądanie / odpowiedź (pull)	odczyt i zapis danych na żądanie: stacje, tokeny, klienci
Webhooki	EV24® → Ty	powiadomienia o zdarzeniach (push)	reagowanie na zdarzenia w czasie zbliżonym do rzeczywistego, np. zakończenie ładowania

W praktyce integracje korzystają z obu mechanizmów jednocześnie: webhook informuje o zdarzeniu, a REST API pozwala pobrać powiązane szczegóły.

Warunki dostępu

Aby korzystać z API EV24®:

konto partnera lub klienta musi mieć włączoną usługę API,
użytkownik musi mieć dostęp do sekcji Ustawienia → API w swoim profilu,
token API musi zostać wygenerowany w portalu EV24®.

Włączenie dostępu do API może wymagać wcześniejszej aktywacji usługi przez administratora EV24®.

Jak uzyskać token

Włącz dostęp do API

Administrator EV24® włącza dostęp do API dla profilu partnera lub klienta i przypisuje odpowiednie zakresy (scope).

Otwórz sekcję API

Zaloguj się do portalu EV24® i przejdź do zakładki Ustawienia → API w profilu partnera lub klienta.

Wygeneruj token

Użyj opcji Generuj nowy token. Token jest widoczny tylko raz bezpośrednio po wygenerowaniu.

Zapisz token w bezpiecznym miejscu

Po zamknięciu widoku token nie będzie już ponownie wyświetlany.

REST API

REST API pozwala Twojemu systemowi odczytywać i zapisywać dane w EV24® na żądanie — obejmuje m.in. zarządzanie stacjami ładowania, tokenami RFID / PIN oraz klientami partnera. Każde żądanie jest uwierzytelniane tokenem Bearer, a dostęp do poszczególnych operacji jest ograniczony przypisanymi do tokena zakresami (scope) widocznymi w portalu.

Adres bazowy API to https://api.ev24.cloud. Pełna, interaktywna specyfikacja OpenAPI z listą wszystkich endpointów, parametrów i przykładów jest dostępna w dedykowanej dokumentacji API:

Dokumentacja API EV24®

Webhooki

Webhooki dostarczają powiadomienia o zdarzeniach z platformy EV24® pod wskazany przez Ciebie adres URL. Zamiast cyklicznie odpytywać REST API, otrzymujesz żądanie POST w momencie, gdy zdarzenie wystąpi.

Konfiguracja

W sekcji Webhooki wskaż:

Endpoint URL — adres, pod który EV24® będzie wysyłać powiadomienia (metoda POST),
Nazwę i wartość nagłówka autoryzacyjnego — dowolny nagłówek (np. X-Webhook-Secret), który EV24® dołączy do każdego żądania, aby usługa odbierająca powiadomienia mogła potwierdzić ich pochodzenie. Wartość jest przechowywana bezpiecznie i nie jest wyświetlana ponownie — przy edycji podaj ją ponownie, aby ją zmienić, lub pozostaw puste pole, aby zachować dotychczasową,
Zdarzenia, które chcesz otrzymywać.

Dostępne zdarzenia

Zdarzenie	Opis	Wymagany zakres
`charging.finished`	wysyłane po zakończeniu sesji ładowania	`charging:read`

Lista dostępnych do subskrypcji zdarzeń zależy od zakresów przypisanych do profilu — widoczne są wyłącznie zdarzenia, do których profil ma uprawnienia.

Powiadomienie jest wysyłane jako POST z ładunkiem w formacie JSON. Szczegółowa struktura ładunku dla każdego zdarzenia jest opisana w dokumentacji API EV24® .

Dostarczanie i ponawianie

Powiadomienia są kolejkowane i wysyłane asynchronicznie. W razie niepowodzenia dostarczenia (np. błąd sieci lub kod odpowiedzi inny niż 2xx) EV24® ponawia próby zgodnie z polityką ponawiania. Usługa odbierająca powinna odpowiadać kodem 2xx po pomyślnym przyjęciu powiadomienia oraz obsługiwać je w sposób idempotentny — to samo zdarzenie może zostać dostarczone więcej niż raz.

Zasady bezpieczeństwa

token należy przekazywać w nagłówku Authorization jako Bearer,
wygenerowanie nowego tokena natychmiast unieważnia poprzedni,
token można ręcznie unieważnić z poziomu profilu (Odwołaj token),
po wyłączeniu dostępu do API wszystkie powiązane tokeny przestają działać,
w usłudze odbierającej webhooki weryfikuj nagłówek autoryzacyjny dołączany przez EV24®.

Jak używać tokena

Przykładowy nagłówek autoryzacyjny:


Authorization: Bearer ev24_live_xxxxx.yyyyy

Adres bazowy API:


https://api.ev24.cloud

Dokumentacja endpointów jest dostępna tutaj:

API EV24®