Dokumentacja Deweloper GOV

1. Powitanie i osoba odpowiedzialna

W menu WordPressa otwórz Deweloper GOV → Konfigurator. Po pierwszej pojedynczej aktywacji nowej instalacji kreator otworzy się automatycznie. Wpisz osobę odpowiedzialną oraz adresy e-mail do kontaktu i powiadomień.

Klikaj Zapisz i przejdź dalej. Jeśli musisz przerwać, zapisz wersję roboczą. Przycisk Wznów konfigurator pozwala wrócić do zapisanego miejsca; samo otwarcie kroku nie oznacza jego ukończenia.

2. Sprawdzenie gotowości strony

Odczytaj wyniki kontroli WordPressa, PHP, rozszerzeń oraz możliwości zapisu plików. Deweloper GOV 2.1.0 wymaga co najmniej WordPressa 6.4 i PHP 8.2.

Na localhost można sprawdzać konfigurację i pliki, ale taki adres nie jest dostępny dla dane.gov.pl. Produkcyjne udostępnianie wymaga publicznego HTTPS.

3. Aktywacja licencji

Wprowadź dane licencji otrzymane przy zakupie i uruchom aktywację dla właściwej domeny. Sprawdź pokazany plan i termin ważności. Nie wysyłaj klucza w zgłoszeniu ani na zrzucie ekranu.

Przejście do dalszej konfiguracji danych wymaga aktywnej licencji. Jeżeli aktywacja nie działa, sprawdź domenę, poprawność klucza i połączenie serwera z systemem licencji. Nie twórz drugiej instalacji jako obejścia.

4. Dane firmy

Wpisz rzeczywistą nazwę i formę prawną firmy, identyfikatory rejestrowe, telefon, e-mail oraz adres strony. Korzystaj z dokumentów firmy, a nie danych przykładowych widocznych w galerii.

Zweryfikuj zera na początku identyfikatorów i poprawność pól wymaganych dla wybranej formy prawnej. Wskazany błąd popraw przed przejściem dalej.

5. Adres siedziby

Wybierz województwo i uzupełnij powiat, gminę, miejscowość, ulicę, numer budynku, ewentualny numer lokalu oraz kod pocztowy.

Siedziba firmy, biuro sprzedaży i lokalizacja inwestycji to różne adresy. Nie wpisuj jednego w miejsce drugiego tylko po to, żeby zniknął komunikat.

6. Domyślne biuro sprzedaży

Uzupełnij adres biura, jego telefon, e-mail oraz sposób kontaktu. Podaj odpowiedni prospekt lub adres dokumentu zgodnie z przygotowaną ofertą.

Dokument ma być rzeczywiście dostępny. Niesprawdzony albo niedostępny prospekt nie jest pokazywany klientowi jako działający przycisk. Po zmianie pliku ponów kontrolę.

7. Publikacja oferty

Podaj nazwę przedsięwzięcia, daty oraz tytuł i opis zbioru. W polu Strona z cenami i dostępnością wskaż rzeczywistą stronę oferty, którą odwiedzi klient.

Adres pliku dla dane.gov.pl przygotowuje wtyczka. Nie wymyślaj adresu XML i nie podawaj adresu lokalnego jako produkcyjnego. Publiczny identyfikator zbioru uzupełnisz po utworzeniu zbioru w portalu.

8. Źródło danych

W Standard wybierz ręczne zarządzanie ofertą w WordPressie. W PRO dostępne są również importy oraz integracja EstiCRM. Wybierz jednoznacznie, gdzie zespół będzie aktualizował ceny.

Przy łączeniu źródeł ostatni zapis wygrywa. Późniejszy import lub synchronizacja może zastąpić ręczną zmianę; źródło zmiany trafia do audytu. Sam wybór EstiCRM nie uruchamia poprawnego połączenia.

9. Pierwsza nieruchomość

Dodaj inwestycję i przypisz do niej ofertę. Wybierz rodzaj, oznaczenie, status, lokalizację, powierzchnię oraz ceny brutto i daty ich obowiązywania. Status wpisu WordPress określa widoczność na stronie, a aktywność GOV udział inwestycji w raporcie.

Dla mieszkania lub domu cena raportowa wynika z powierzchni użytkowej i ceny za m². Sprawdź oba pola, jeśli różni się od wcześniej wpisanej kwoty. Nie dopasowuj danych fikcyjnie; aktualizacja wtyczki nie uzgadnia za Ciebie błędnych cen.

Dla dodatków określ relację do ceny, obowiązkowość i właściwą formę prawną. Cena konfiguracji jest osobną, jawną kwotą zatwierdzaną przez administratora — dodatki nie są automatycznie sumowane.

10. Kontrola przed publikacją

Uruchom rzeczywistą kontrolę danych i plików. Otwieraj wskazane linki naprawcze, poprawiaj pola i ponawiaj kontrolę, aż znikną błędy. Nie wystarczy obejrzeć ekranu ani zaznaczyć potwierdzenia.

Błąd jednego publikowanego rekordu blokuje cały nowy raport. Poprzedni poprawny zestaw pozostaje dostępny. Wynik lokalnego testu struktury nie jest dowodem pobrania plików przez portal.

11. Automatyzacja i powiadomienia

Ustaw godzinę publikacji i sprawdź strefę czasową WordPressa. Wybierz WP-Cron lub zewnętrzny harmonogram zgodnie z możliwościami hostingu. Uzupełnij właściwy adres powiadomień.

W Diagnostyce uruchom Przetestuj harmonogram i sprawdź rzeczywiste wykonanie. Sama obecność zadania nie potwierdza jego działania. Automatyczny watchdog, alerty i ponowienia należą do PRO.

12. Formalności dane.gov.pl

Otwórz Pomoc i dane.gov.pl. Klikaj kolejne pozycje checklisty: konto dostawcy, rola Edytora, kontrola plików, wniosek o importer i potwierdzenie widoczności zbioru. Rozwijane instrukcje opisują warunek ukończenia każdego punktu.

Dopiero dla poprawnej publikacji pod publicznym HTTPS przekaż właściwe adresy administratorowi portalu. Zapisz publiczny URL lub ID swojego zbioru i użyj Sprawdź dane.gov.pl. Nie zgłaszaj plików demonstracyjnych z tej strony.

13. Podsumowanie i pierwsza publikacja

Sprawdź podsumowanie, stronę widoczną dla klienta, historię cen i dokumenty. Pierwszą publikację uruchom świadomie na przygotowanej domenie produkcyjnej, po usunięciu błędów.

Rozróżniaj poprawność plików, dostępność przez HTTPS i potwierdzenie zasobu w dane.gov.pl. To trzy osobne etapy. Po uruchomieniu sprawdź także następne wykonanie harmonogramu.

Dostęp i uwierzytelnienie

W WordPressie utwórz osobnego użytkownika z rolą „Deweloper GOV — odczyt API” (dg_catalog_reader), a następnie wygeneruj mu Application Password. Hasło jest pokazywane tylko raz; zapisz je w menedżerze sekretów backendu.

Wywołuj katalog wyłącznie z backendu przez HTTPS i HTTP Basic Auth: nazwa użytkownika + Application Password. Wtyczka nie otwiera CORS i nie wolno osadzać tokenu w kodzie JavaScript dostarczanym do przeglądarki.

Anonimowy request otrzymuje 401, użytkownik bez dg_read_catalog — 403, a Standard, licencja wygasła lub nieważna — 403. Limit katalogu wynosi 120 żądań na minutę dla pary użytkownik–IP.

Endpointy katalogu

Adres bazowy: https://twoja-domena.pl/wp-json/deweloper-gov/v2. Odkrywanie: GET /catalog. Inwestycje: GET /catalog/investments oraz /catalog/investments/{id}.

Oferty: GET /catalog/properties oraz /catalog/properties/{id}. Historia: GET /catalog/properties/{id}/price-history. Podobne oferty: GET /catalog/properties/{id}/related.

API zwraca wyłącznie opublikowane wpisy. Szczegół oferty obejmuje inwestycję, lokalizację, status, parametry, ceny w groszach i formacie prezentacyjnym, części i prawa, pełną historię z korektami, galerię, dokumenty, zweryfikowany prospekt, kontakt, widoczność oraz bezpieczne custom_meta.

Filtrowanie, paginacja i cache

Oferty filtrujesz przez investment, status, offer_kind, type, rooms, floor, area_min/area_max, price_min/price_max, search i modified_after. Sortowanie: modified, title, price albo area oraz ASC/DESC.

Kolekcje obsługują page i per_page do 100 oraz _fields. Liczbę wyników odczytasz z X-WP-Total i X-WP-TotalPages.

Używaj ETag z If-None-Match albo Last-Modified z If-Modified-Since. Niezmieniony zasób zwraca 304 bez ponownego przesyłania JSON.

Pola dodatkowe i hooki

Własne pola dodawaj przez carbon_fields_register_fields. W custom_meta mogą znaleźć się pola Carbon Fields, ACF jawnie udostępnione do REST, register_post_meta(show_in_rest=true) i klucze dopuszczone filtrem dg_rest_business_meta_keys.

Wspólny DTO frontendu i API rozszerzają filtry dg_frontend_property_data oraz dg_frontend_investment_data. Zapytania można kontrolowanie rozszerzyć przez dg_rest_catalog_property_query_args i dg_rest_catalog_investment_query_args.

Szablony udostępniają akcje dg_before_* i dg_after_* dla listingu, inwestycji, pojedynczej oferty, szczegółów, historii, dokumentów i kontaktu. Sekrety, tokeny, licencje, EstiCRM i techniczne meta są bezwarunkowo usuwane z odpowiedzi.

Operacje administracyjne

Status, importy, preflight i publikacja pozostają oddzielnymi endpointami administracyjnymi. Wymagają konta z manage_options oraz osobnego Application Password albo sesji WordPress z nonce REST. Rola dg_catalog_reader nie może ich uruchamiać.

Import oferty jest dwuetapowy i atomowy; import raportu nie zmienia frontendu. Przed POST /publications wykonaj POST /publications/preflight. Żaden endpoint nie omija walidacji cen, historii, kontraktu ani licencji.

Webhook HMAC-SHA256

Endpoint: POST /webhooks/properties. Webhook używa osobnego sekretu, a nie Application Password. Wymagane nagłówki: X-DG-Timestamp, X-DG-Nonce, Idempotency-Key i X-DG-Signature oraz Content-Type: application/json.

Podpis to małe hex HMAC-SHA256 z łańcucha timestamp.nonce.idempotency_key.RAW_BODY. Podpisuj dokładne bajty JSON i nie serializuj body ponownie przed wysłaniem. Timestamp ma tolerancję ±300 sekund, a nonce jest jednorazowe przez 10 minut.

Ten sam klucz i body zwraca poprzedni wynik bez ponownego zapisu; ten sam klucz z innym body daje 409. Trwające wykonanie daje 409 z Retry-After. Retry zachowuje body i Idempotency-Key, ale używa nowego timestampu, nonce i podpisu.

Zakres webhooka

Webhook aktualizuje pojedyncze mieszkanie lub dom w trybie patch. Wymaga source_investment_id i source_property_id; obsługuje oznaczenie, typ, status, powierzchnię, pokoje, piętro, ceny i daty oraz lokalizację inwestycji. Kwoty przesyłaj jako string dziesiętny.

Webhook nie przesyła samodzielnych parkingów, garaży, komórek, repeaterów części, praw, świadczeń, galerii ani plików. Te dane dodaj w edytorze lub przez kontrolowane rozszerzenie. Zagnieżdżone struktury są odrzucane w całości, a nie pomijane po cichu.

Kody odpowiedzi i bezpieczne retry

200/202 oznacza sukces, 304 brak zmiany, 400 błędny format, 401 uwierzytelnienie lub replay nonce, 403 brak uprawnienia/PRO/HTTPS, 409 konflikt albo operacja w toku, 422 walidacja, 429 limit i 503 niedostępny trwały stan.

Nie loguj Authorization, Application Password, sekretu webhooka, X-DG-Signature ani pełnych nagłówków. Po podejrzeniu ujawnienia unieważnij Application Password albo przeprowadź kontrolowaną rotację sekretu webhooka.