Instrukcja integracji
za pośrednictwem API
z
CENTRALNĄ EWIDENCJĄ
EMISYJNOŚCI BUDYNKÓW
Procedura udzielania dostępów do komunikacji systemowej z CEEB
Aby uzyskać uprawnienia do integracji z Centralną Ewidencją
Emisyjności Budynków (CEEB), należy skierować do Głównego Urzędu Nadzoru Budowlanego wniosek o możliwość
przekazywania danych do CEEB poprzez API. W odpowiedzi podmiot otrzyma dane autoryzacyjne umożliwiające
przekazywanie danych w postaci plików w formacie GML.
We wniosku należy wykazać uprawnienie do wprowadzania danych do
ewidencji wynikające z przepisów ustawy o wspieraniu termomodernizacji i remontów oraz o centralnej ewidencji
emisyjności budynków (Dz.U. z 2023 r. poz. 2496), podając jednocześnie numer REGON podmiotu uprawnionego.
Procedura wnioskowa obejmuje dostęp zarówno do środowiska testowego, jak i produkcyjnego CEEB. Wykonanie
testów integracyjnych jest obowiązkowe i musi poprzedzić integrację na środowisku produkcyjnym.
Wzór wniosku o możliwość przekazywania danych do Centralnej Ewidencji Emisyjności
Budynków poprzez API
Głównym celem działań integracyjnych CEEB z systemami dziedzinowymi jest stworzenie warunków, aby podmiot uprawniony miał możliwość wprowadzania danych do CEEB w sposób zautomatyzowany. W celu uniknięcie błędów w przetwarzaniu (duplikowaniu/nadpisywaniu) danych przez wielu użytkowników wskazane jest aby konto posiadała jedna osoba – w przypadku JST np. wójt, burmistrz, prezydent miasta (wewnętrzne upoważnienia urzędu do dysponowania tokenem nie są przedmiotem wniosku). W przypadku przekazywania wielu danych należy przygotować się na okoliczność pojedynczych przypadków niepowodzenia przekazania danych oraz związanej z tym konieczności obsłużenia takich przypadków. Zespół obsługujący CEEB rekomenduje rozwiązanie, aby w sytuacji odrzucenia danych wprowadzić takie dane do systemu CEEB przez osobę uprawnioną za pomocą interfejsu użytkownika. Podkreślić należy, że zasilanie CEEB jest możliwe za pośrednictwem aplikacji dostępowej udostępnionej podmiotom uprawnionym, natomiast interfejsy systemowe pozwalają w sposób zautomatyzowany osiągać wyznaczane cele.
API systemu CEEB wymaga wcześniejszego przygotowania danych do integracji. W przykładowych plikach do pobrania można odnaleźć wypełniony szablony do zbierania danych. Dopuszczalne i obligatoryjne wartości którymi może lub musi zostać wypełniony dany atrybut opisują dołączone pliki XSD. Kluczowymi elementami w procesie przygotowania danych są:
ID_ZRODLOWE - Unikalny identyfikator rekordu w systemie dostawcy. Na podstawie tego identyfikatora rekordy są aktualizowane w systemie CEEB. Rekomendujemy użycie prefixu Twojej organizacji np. GUNB_1001 przed własnym identyfikatorem lokalnym. W odpowiedzi API może zwracać informacje, że obiekt o danym ID już istnieje w systemie – należy w takich przypadkach upewnić się że podany identyfikator jest unikalny w skali zbioru.
OPERACJA - Określenie jak przekazywany plik za pośrednictwem API ma wpłynąć na system dokonując dodania nowych elementów, aktualizacji istniejących lub przeniesienia do archiwum- atrybut powinien przyjmować odpowiednio wartość: nowy, aktualizacja lub usuń.
Aby dane mogły zasilić system muszą być zgodne nie tylko pod względem struktury ale również z rejestrem TERYT i bazą referencyjną adresową CEEB.
API umożliwia przekazywanie danych jedynie zgodnych z referencyjną bazą adresową, której podstawę stanowi Państwowy Rejestr Granic prowadzony przez Prezesa Głównego Urzędu Geodezji i Kartografii. W przypadku adresu spoza bazy referencyjnej jego przekazanie jest możliwe jedynie za pośrednictwem GUI systemu dostępnego pod adresem zone-web.gunb.gov.pl
Rekomendujemy zatem dokonanie wstępnej walidacji samego adresu i jego ewentualną aktualizację.
Przykładowe, opcjonalne zapytanie umożliwiające wstępne sprawdzenie czy dana kombinacja kodów terc, simc, ulic oraz numeru porządkowego jest poprawna względem aktualnego rejestru TERYT oraz PRG
curl --location 'https://zone-test-fme.gunb.gov.pl/fmedatastreaming/Uniwersalne_API_data_upload/walidator_wystepowania_w_PRG.fmw?simc=0973524&ulic=17918&nr=9&token=99140591b5904d5d51e3c9ecf60d2c453d27a075'
Do zapytania należy wprowadzić następujące parametry i nagłówki:
SIMC – identyfikator miejscowości z rejestru TERYTULIC – identyfikator ulicy z rejestru TERYTNR – numer budynkuTOKEN aktualny token przekazany przez GUNB
Walidacja plików XML system Windows
Aby uniknąć błędów w trakcie importu danych za pośrednictwem API warto dokonać walidacji pliku. Można tego dokonać za pomocą np. darmowego oprogramowania Notepad++ z wtyczką XML Tools (wymaga włączenia/instalacji). Aby to zrobić, należy wybrać polecenie z menu Wtyczk > XML Tools > Validate Now . Otwórz plik XML, który chcesz zweryfikować, a następnie uruchom wspomniane polecenie. Wskaż właściwy plik XSD udostępniony na stronie GUNB i po kilku sekundach wyświetli się informacja o poprawności pliku lub o błędzie walidacji, który zostanie zaznaczony w oknie pliku w Notepad++.
Walidacja plików XML system macOS
Po wypakowaniu plików pobranych z sekcji pliki do pobrania, katalog powinen wygądać następująco:
├── 1.3_przyklady
│ ├── Redame.md
│ ├── dofinansowanie-aktualizacja.gml
│ ├── dofinansowanie-nowy.gml
│ ├── dofinansowanie-usun.gml
│ ├── pomoc-aktualizacja.gml
│ ├── pomoc-nowy.gml
│ └── pomoc-usun.gml
└── 1.3_walidacja
├── 1.1
│ ├── instytucjeFinansujace.xsd
│ ├── pomocSpoleczna.xsd
│ ├── zone-finansowe.xsd
│ └── zone-wspolne.xsd
└── 1.2
├── instytucjeFinansujace.xsd
└── pomocSpoleczna.xsd
5 directories, 13 files
Walidację struktury pliku XML można przeprowadzić za pomocą narzędzia xmllint, które jest
częścią pakietu libxml2. Aby zwalidować plik XML w odniesieniu do odpowiedniego pliku XSD,
wykonaj następujące kroki:
- Otwórz terminal w macOS.
- Użyj poniższych poleceń w zależności od pliku, który chcesz zweryfikować.
Walidacja InstytucjeFinansujace ( dofinansowanie nowy )
xmllint --noout --schema ../1.3_walidacja/1.3/instytucjeFinansujace.xsd dofinansowanie-nowy.gml
Walidacja InstytucjeFinansujace ( dofinansowanie aktualizacja )
xmllint --noout --schema ../1.3_walidacja/1.3/instytucjeFinansujace.xsd dofinansowanie-aktualizacja.gml
Walidacja InstytucjeFinansujace ( dofinansowanie dofinansowanie-usun.gml )
xmllint --noout --schema ../1.3_walidacja/1.3/instytucjeFinansujace.xsd dofinansowanie-usun.gml
Walidacja Pomoc Społeczna ( nowy )
xmllint --noout --schema ../1.3_walidacja/1.3/pomocSpoleczna.xsd pomoc-nowy.gml
Walidacja Pomoc Społeczna ( aktualizacja )
xmllint --noout --schema ../1.3_walidacja/1.3/pomocSpoleczna.xsd pomoc-aktualizacja.gml
Walidacja Pomoc Społeczna ( usuń )
xmllint --noout --schema ../1.3_walidacja/1.3/pomocSpoleczna.xsd pomoc-usun.gml
Interpretacja wyników
Po wykonaniu polecenia xmllint zostanie wyświetlona informacja o poprawności pliku XML. Jeśli
plik jest zgodny ze schematem, nie zobaczysz żadnych komunikatów. W przypadku błędów komunikaty o błędach
zostaną wyświetlone w terminalu, wskazując na konkretne problemy w pliku XML.
Uzyskanie dostępu do integracji poprzez API
Po zakończeniu rejestracji Twojego konta otrzymasz od GUNB identyfikator przypisany
do Twojej organizacji, który będzie jednym z niezbędnych parametrów podczas
konfiguracji połączeń z API.
W celu przekazania danych wystarczy wykonać zapytanie typu (test)
POST:
curl --location 'https://zone-test-
fme.gunb.gov.pl:443/fmedatastreaming/Uniwersalne_API_data_upload/file_send.fmw?
user_id= identyfikator&file_name= nazwa_pliku.xml &email_sending=tak' \
--header 'Authorization: fmetoken token=token' \
--header 'Content-Type: application/gml+xml' \
--data 'lokalizacja pliku'
W celu przekazania danych wystarczy wykonać zapytanie typu (prod)
POST:
curl --location 'https://zone-int.gunb.gov.pl:443/fmedatastreaming/Uniwersalne_API_data_upload/file_send.fmw?
user_id= identyfikator&file_name= nazwa_pliku.xml &email_sending=tak' \
--header 'Authorization: fmetoken token=token' \
--header 'Content-Type: application/gml+xml' \
--data 'lokalizacja pliku'
Do zapytania należy wprowadzić następujące parametry i nagłówki:
identyfikator – identyfikator otrzymany od GUNBfile_name – nazwa pliku, który przekazujesz wraz rozszerzeniemlokalizacja pliku – plik. @/C:/ Przyklad-InstytucjeFinansujace.gmlemail_sending opcjonalny parametr przyjmujący wartości tak lub nie (gdzie nie jest
wartością domyślną) decydujący o wysyłaniu do użytkownika e-maila na wskazany przez
niego w pliku adres wraz z wynikami walidacjitoken aktualny token przekazany przez GUNB
Wysłanie pojedynczego zapytania możliwe jest np. z poziomu aplikacji Postman.
W odpowiedzi na żądanie użytkownik otrzyma informację o
przydzielonej sesji zasilenia.
Identyfikator sesji pozwala na późniejsze sprawdzenie wyniku walidacji. W odpowiedzi
znajduje się również gotowy link do usługi umożliwiającej wyświetlenie raportu z
walidacji. Czas przetwarzania danych zależy od wielkości przesłanego pliku, jednak nie
powinien przekraczać kilku minut.
Przykład odpowiedzi
[ {
"session_id": "33e55e97-5f4b-4230-8bd8-412d9c2c260ad",
"user_id": "885g06d5a352b67bb4b3ee9111bf19sb8a7014c9",
"file_name": "finansowanie_v4.xml",
"report_link": "https://zone-test-
fme.gunb.gov.pl/fmedatastreaming/Uniwersalne_API_data_upload/report_download.fm
w?user_id=gunb88921481&id_sesji=33e55e9217-5f4b-4230-8bd8-412d9c2c26350ad
&token=99140591b5904d5d51e3c9ecf60d2c453d27a075",
"file_body": "<?xml version (...)"
}]
Wyniki procesu walidacji można sprawdzić za pomocą żądania, które
jest dołączone
jako report_link w odpowiedzi zwracanej podczas przesyłania danych.
curl --location https://zone-test-
fme.gunb.gov.pl/fmedatastreaming/Uniwersalne_API_data_upload/report_download.fm
w?file_name= nazwa_pliku &user_id= identyfikator &id_sesji= id_sesji
--header 'Authorization: fmetoken token=token' \
--header 'Accept: application/octet-stream'
W odpowiedzi użytkownik otrzyma raport w formacie JSON zawierający
informacje o
identyfikatorze pliku przesłanego do importu oraz status walidacji. W przypadku
wykrycia niepoprawności w danych raport będzie zawierał również komunikat
wskazujący na możliwą przyczynę błędu.
{
"id" : "44c3cd5a-1a6f-4345-9f9e-d2367422",
"status" : "odrzucony",
"process" : "weryfikacja id",
"reason" : "id rekordu do usunięcia nie istnieje w bazie danych"
},
Do czasu wygenerowania przez system finalnego raportu z walidacji
możesz otrzymać
następujący komunikat „Plik w trakcie generowania spróbuj później” – po kilku minutach
w jego miejscu powinny pojawić się wyniki walidacji.
Jeżeli w zapytaniu przesyłającym dane wybrana została opcja
email_sending z wartością „tak”, na e-mail wskazany w pliku jako adres zwrotny trafi dodatkowy raport z
podsumowaniem i detalami dla zwolenników widoku tabelarycznego zamiast struktury JSON.
Proces integracji z systemem CEEB
Aby zintegrować się z systemem CEEB, należy wykonać poniższe kroki:
- Wystąpić z wnioskiem o możliwość przekazywania do Centralnej Ewidencji Emisyjności Budynków danych poprzez
API.
- Przygotować dane – muszą być zgodne ze strukturą wymaganą przez system (XSD - dostępne w paczce plików do pobrania - Sekcja pliki do pobrania), która została udostępniona na stronie wraz z przykładami poprawnych
zapytań.
- Ponowić kroki 2 lub przekazać dane z pośrednictwem aplikacji webowej.
Interakcja z API wymaga podania również tokena jako nagłówka zapytania (tokeny zostaną wysłane w odpowiedzi na wniosek).
| Środowisko |
Key |
Value |
| Testowe |
Authorization |
fmetoken token=xxxxx |
| Produkcja |
Authorization |
fmetoken token=xxxxx |