Instrukcja integracji za pośrednictwem API

z CENTRALNĄ EWIDENCJĄ EMISYJNOŚCI BUDYNKÓW

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.

Przekazywanie danych z wykorzystaniem API przeznaczone jest dla uprawnionych podmiotów: finansujących i pomocy społecznej

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=************************'
            

curl --location 'https://zone-int.gunb.gov.pl/fmedatastreaming/Uniwersalne_API_data_upload/walidator_wystepowania_w_PRG.fmw?simc=0973524&ulic=17918&nr=9&token=************************'
            

Do zapytania należy wprowadzić następujące parametry i nagłówki:

• SIMC – identyfikator miejscowości z rejestru TERYT
• ULIC – identyfikator ulicy z rejestru TERYT
• NR – numer budynku
• TOKEN 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

					├── 1.6_przyklady
					              │   ├── Redame.md
					              │   ├── dofinansowanie-aktualizacja.gml
					              │   ├── dofinansowanie-nowy.gml
					              │   ├── dofinansowanie-usun.gml
					              │   ├── pomoc-aktualizacja.gml
					              │   ├── pomoc-nowy.gml
					              │   └── pomoc-usun.gml
					              └── 1.6_walidacja
					                  ├── 1.3
					                  │   ├── zone-finansowe.xsd
					                  │   └── zone-wspolne.xsd
					                  └── 1.6
					                      ├── instytucjeFinansujace.xsd
					                      └── pomocSpoleczna.xsd

            

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:

1. Otwórz terminal w macOS.
2. Użyj poniższych poleceń w zależności od pliku, który chcesz zweryfikować.

xmllint --noout --schema ../1.6_walidacja/1.6/instytucjeFinansujace.xsd  dofinansowanie-nowy.gml
            

xmllint --noout --schema ../1.6_walidacja/1.6/instytucjeFinansujace.xsd  dofinansowanie-aktualizacja.gml
            

xmllint --noout --schema ../1.6_walidacja/1.6/instytucjeFinansujace.xsd  dofinansowanie-usun.gml
            

xmllint --noout --schema ../1.6_walidacja/1.6/pomocSpoleczna.xsd pomoc-nowy.gml
            

xmllint --noout --schema ../1.6_walidacja/1.6/pomocSpoleczna.xsd pomoc-aktualizacja.gml
            

xmllint --noout --schema ../1.6_walidacja/1.6/pomocSpoleczna.xsd pomoc-usun.gml
            

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.

W celu integracji z CEEB, należy przygotować plik XML zgodny z wymaganiami określonymi w schemacie XSD. Poniżej znajduje się pełen opis atrybutów, które powinny być zawarte w pliku XML. Atrybuty te są niezbędne do prawidłowego przesyłania danych do CEEB.

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=******************r&file_name=nazwa_pliku.xml&email_sending=tak' \
--header 'Authorization: fmetoken token=**********************************' \
--header 'Content-Type: application/gml+xml' \
--data-raw '<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ps:FeatureCollection xmlns:ps="urn:example:ps" example_attribute="value">
  <!-- Feature data would go here -->
</ps:FeatureCollection>'
            

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=******************&file_name=nazwa_pliku.xml&email_sending=tak' \
--header 'Authorization: fmetoken token=**********************************' \
--header 'Content-Type: text/plain' \
--data-raw '<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ps:FeatureCollection xmlns:ps="urn:example:ps" example_attribute="value">
  <!-- Feature data would go here -->
</ps:FeatureCollection>'
			

Do zapytania należy wprowadzić następujące parametry i nagłówki:

• user_id – identyfikator otrzymany od GUNB
• file_name – nazwa pliku, który przekazujesz wraz rozszerzeniem
• email_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 walidacji
• token 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": "****************************************",
"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=gunb*********&id_sesji=33e55e9217-5f4b-4230-8bd8-412d9c2c26350ad
&token=************************",
"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.fmw?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:

1. Wystąpić z wnioskiem o możliwość przekazywania do Centralnej Ewidencji Emisyjności Budynków danych poprzez API.
2. 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ń.
3. 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).