CEEB-Integracja

Proces integracji z systemem

CEEB-Integracja

Aby zintegrować się z naszym systemem, 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 do pobrania), która została udostępniona na stronie wraz z przykładami poprawnych Pliki do Pobrania)
  3. Przesłać plik z danymi
  4. Sprawdzić wyniki walidacji
  5. Ponowić kroki 2-4 lub przekazać dane z pośrednictwem aplikacji webowej

Szczegółowy opis przekazania danych znajduje się w instrukcja dla użytkowników

Interakcja z API wymaga podania również tokena jako nagłówka zapytania

Środowisko Key Value
Testowe Authorization fmetoken token=99140591b5904d5d51e3c9ecf60d2c453d27a075

Najczęściej zadawane pytania:

1. Gdzie wysłać zapytanie

W razie pytań proszę wysłać mail na adres: "pomoc.ceeb@gunb.gov.pl" w tytule: "Integracja API".

Ceeb Documentation Block

CSS and JavaScript Example
Wprowadzenie

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.


wniosek.pdf
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. Należy jednak 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.

Przygotowanie danych

API systemu CEEB wymaga wcześniejszego przygotowania danych do integracji. Aby dane mogły zasilić system, muszą być zgodne pod względem struktury oraz być zgodne z rejestrem TERYT i referencyjną bazą adresową CEEB.


API umożliwia przekazywanie danych jedynie zgodnych z referencyjną bazą adresową, której podstawę stanowi Państwowy Rejestr Granic prowadzony przez Głównego Geodetę Kraju.

Rekomendujemy zatem dokonanie wstępnej walidacji samego adresu i jego ewentualną aktualizację.
W przypadku adresu spoza bazy referencyjnej jego przekazanie jest możliwe jedynie za pośrednictwem interfejsu https://zone-web.gunb.gov.pl/

Przykładowe zapytanie walidujące (test)

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'

Przykładowe zapytanie walidujące (prod)

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=99140591b5904d5d51e3c9ecf60d2c453d27a075'

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 ze strony GUNB

Walidacja plików XML system Windows

Walidację struktury Twojego pliku można przeprowadzić 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

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ć.
Walidacja InstytucjeFinansujace xmllint --noout --schema ./instytucjeFinansujace.xsd Przyklad-InstytucjeFinansujace.gml Walidacja Przyklad-PomocSpoleczna xmllint --noout --schema ./pomocSpoleczna.xsd Przyklad-PomocSpoleczna.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.

Wysłanie pliku

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 GUNB
  • file_name – nazwa pliku, który przekazujesz wraz rozszerzeniem
  • lokalizacja pliku – plik. @/C:/ Przyklad-InstytucjeFinansujace.gml
  • 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 ze strony 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 walidacji

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.

Podsumowanie

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 do pobrania), która została udostępniona na stronie wraz z przykładami poprawnych zapytań (Pliki do Pobrania)
  3. Przesłać plik z danymi.
  4. Sprawdzić wyniki walidacji.
  5. Ponowić kroki 2-4 lub przekazać dane z pośrednictwem aplikacji webowej.

Szczegółowy opis przekazania danych znajduje się w instrukcja dla użytkowników

Interakcja z API wymaga podania również tokena jako nagłówka zapytania.

Środowisko Key Value
Testowe Authorization fmetoken token=99140591b5904d5d51e3c9ecf60d2c453d27a075
Produkcja Authorization fmetoken token=c1082ded1c00598b01c14cd9187a5e57b7f21765
Najczęściej zadawane pytania

1. Gdzie wysłać zapytanie

W razie pytań proszę wysłać e-mail na adres: w tytule: "Integracja API".