EIPA

Ewidencja Infrastruktury
Paliw Alternatywnych

Integracja z EIPA po stronie operatora infrastruktury

Opis systemu EIPA-opis-systemu.pdf

Pełna dokumentacja wszystkich operacji dostępna jest w formacie OpenAPI/Swagger 2.0 eipaOpenApi.json

Kilka przykładów komunikacji z REST API EIPA. W przykładach użyto zmiennych w nawiasach {{zmienna}}, do adresu interfejsu REST odnosi się zmienna {{api-url}}. Adres interfejsu przekazywany jest operatorowi w procesie rejestracji.

Pobranie tokenu uwierzytelniającego
Zapytanie POST {{api-url}}/token Content-Type: application/json { "username": "{{username}}", "password": "{{password}}" } {{username}} i {{password}} to dane otrzymane z EIPA
Odpowiedź { "token": "ABCDYT1............" }

token należy użyć przy każdym innym zapytaniu

token ważny jest 60 minut

Pobranie listy baz
Zapytanie GET {{api-url}}/pools Authorization: Bearer {{token}} {{token}} zawiera ciąg znaków zwrócony w zapytaniu uwierzytelniającym powyżej
Odpowiedź [ { "code": "PL-V0J-P12332156", "id": 31, "stations": [] }, { "code": "PL-V0J-P1233215S", "id": 32, "stations": [] }, { "code": "PL-V0J-P19651ELH", "id": 19, "stations": [ { "id": 5 } ] }, { "code": "PL-V0J-P2YWBJBTR", "id": 26, "stations": [ { "id": 61 }, { "id": 67 }, { "id": 68 }, ] } ]

w odpowiedzi zwrócona zostaje tablica obiektów reprezentujących bazy, w tym przypadku są to 4 bazy opisane przez atrybuty:

  • code, unikalny w skali kraju kod bazy,
  • id identyfikator wykorzystywany w komunikacji z API,
  • stations tablica stacji przypisanych do bazy gdzie każda stacja opisana jest przez atrybut id identyfikujący stację w API,
Pobranie danych określonej bazy
Zapytanie GET {{api-url}}/pools/{{poolId}} Authorization: Bearer {{token}} {{poolId}} zawiera identyfikator bazy, której dane chcemy pobrać
Odpowiedź { "code": "PL-V0J-PUNT8JONC", "id": 28, "name": "MOP Błaszczyk s. c.", "latitude": 51.653251, "longitude": 19.242832, "elevation": 229, "street": "Fiołkowa", "stations": [ { "id": 56 }, { "id": 60 }, { "id": 78 } ], "house_number": "138", "postal_code": "73-477", "city": "Mońki", "teryt": "3914544", "accessibility": "Baza zlokalizowana przy drodze krajowej nr 12, w okolicy miejscowości Mońki. Wjazd z drogi krajowej zarówno z kierunku wschodniego jak i zachodniego.", "operating_hours": [ { "from_time": "00:15", "to_time": "12:45", "id": 5, "weekday": 3 }, { "from_time": "13:15", "to_time": "23:45", "id": 60, "weekday": 1 }, { "from_time": "10:00", "to_time": "20:00", "id": 101, "weekday": 2 } ], "closing_hours": [ { "id": 102, "from_time": "2019-10-01T20:22:00+02:00", "to_time": "2019-10-01T23:22:00+02:00" }, { "id": 103, "from_time": "2019-10-01T20:22:00+02:00", "to_time": "2019-10-01T23:22:00+02:00" }, { "id": 104, "from_time": "2019-10-01T20:22:00+02:00", "to_time": "2019-10-01T23:22:00+02:00" } ], "images": [ { "id": 224, "uri": "http://eipa.udt.gov.pl/.../fa2215b.jpg", "type": "jpeg", "ts": "2018-04-12T14:13:47+02:00", "thumbnail_uri": "http://eipa.udt.gov.pl/.../42b45b_thumb.jpg" }, { "id": 274, "uri": "http://eipa.udt.gov.pl/.../0d00cf7e25e.jpg", "type": "jpeg", "ts": "2018-02-14T16:58:13+01:00", "thumbnail_uri": "http://eipa.udt.gov.pl/.../f725e_thumb.jpg" } ], "ts": "2018-10-23T16:46:05+02:00" }

w odpowiedzi zwrócony zostaje obiekt reprezentujący bazę opisaną przez atrybuty:

  • code, unikalny w skali kraju kod bazy,
  • id identyfikuje bazę w innych zapytaniach API,
  • stations tablica stacji przypisanych do bazy gdzie każda stacja opisana jest przez atrybut id identyfikujący stację w API,
  • dane teleadresowe bazy,
  • elevation - położenie nad poziomem morza,
  • współrzędne geograficzne,
  • operating_hours - tablica godzin otwarcia bazy dla poszczególnych dni tygodnia,
  • closing_hours - tablica wyłączeń bazy,
  • images - tablica zdjęć bazy (pełna wersja i miniatura),
  • ts - data wprowadzenia lub zmiany danych,
Dodanie nowej bazy
Zapytanie POST {{api-url}}/pools Authorization: Bearer {{auth_token}} Content-Type: application/json { "code": "P882GA125", "name": "Baza paliw XYZ", "latitude": 51.80624, "longitude": 16.546816, "elevation": 45, "street": "Zielona", "house_number": "16", "house_number_addition": "A", "postal_code": "59-216", "city": "Legnica", "teryt": "0209042", "accessibility": "Testing", "ts": "2017-06-12T10:23:00+02:00" }

dane przekazywane są w formacie JSON

code - unikalny kod bazy w systemie operatora

Odpowiedź { "id": 33, "code": "PL-V0J-P882GA125" }

id - identyfikator nowej bazy wykorzystywany w komunikacji z API,

code - pełny kod bazy, unikalny w skali kraju,

Aktualizacja danych bazy
Zapytanie PUT {{api-url}}/pools/{{poolId}} Authorization: Bearer {{auth_token}} Content-Type: application/json { "accessibility": "Wjazd od strony dworca kolejowego zamknięty. Czynny wjazd z ul. Zielonej." }

w przykładzie aktualizowany jest opis dostępności bazy

{{poolId}} zawiera identyfikator bazy, której dane chcemy aktualizować

Odpowiedź w przypadku pomyślnej aktualizacji nie są zwracane żadne dane, tylko status odpowiedzi HTTP 204
Dodanie nowej stacji elektrycznej do bazy
Zapytanie POST {{api-url}}/pools/{{poolId}}/stations Authorization: Bearer {{auth_token}} Content-Type: application/json { "type": "E", "authentication_methods": [1, 2], "payment_methods": [1, 8, 16] }

{{poolId}} zawiera identyfikator bazy, do której chcemy dodać stację

  • type - oznaczenie rodzaju stacji (tutaj: elektryczna)
  • authentication_methods - tablica identyfikatorów metod autentykacji, zgodnie z listą {{api-url}}/dictionaries/station_authentication_methods
  • payment_methods - tablica identyfikatorów metod płatności, zgodnie z listą {{api-url}}/dictionaries/station_payment_methods
Odpowiedź { "id": 102 } w przypadku pomyślnej operacji zwrócony zostanie identyfikator nowej stacji oraz status odpowiedzi HTTP 201
Usunięcie wszystkich godzin działania bazy
Zapytanie DELETE {{api-url}}/pools/{{poolId}}/operating_hours Authorization: Bearer {{auth_token}}

{{poolId}} zawiera identyfikator bazy, z której usunięte mają być godziny

Odpowiedź w przypadku pomyślnej aktualizacji nie są zwracane żadne dane, tylko status odpowiedzi HTTP 204

W zależności od rezultatów wykonania, metody zwracają kod w nagłówku HTTP :

200
pomyślne wykonanie operacji, zwrócenie danych
201
pomyślne wykonanie operacji, utworzenie obiektu
204
pomyślne wykonanie operacji, bez zwracania danych
400
błąd walidacji danych, szczegóły walidacji opisane są w treści odpowiedzi,
w szczególności opis błędu "Ten formularz nie powinien zawierać dodatkowych pól", oznacza, że przekazano nadmiarowy atrybut, którego nie uwzględnia specyfikacja, a takie atrybuty są niedozwolone, przykładowo przekazanie atrybutu max_output w przypadku punktu ładowania energii podczas gdy ten atrybut opisuje tylko punkty tankowania gazu
401
niepoprawna autoryzacja, brak tokenu, token niepoprawny lub token wygasł
404
obiekt nie został znaleziony
500
wyjątek, szczegóły opisane są w treści odpowiedzi