Endpointy Power BI — lista dostępnych źródeł danych

API Power BI systemu voxDeveloper CRM udostępnia dane w formacie JSON. Można je wykorzystać w programie Power BI, własnych skryptach, dashboardach oraz narzędziach przygotowywanych z pomocą agentów AI.

Artykuł zawiera katalog źródeł oraz rozszerzoną dokumentację czterech raportów: stanu inwestycji, rejestru umów, kontaktów i etapów obsługi lokalu oraz harmonogramu płatności. To zakres pozwalający rozpocząć budowę dashboardu. Dostępne źródła i inwestycje zależą od uprawnień klucza API.

Jak rozpocząć

1. Ustal nazwę panelu i zakres dostępu klucza.
2. Pobierz listę źródeł udostępnionych temu kluczowi przez endpoints.
3. Wybierz raport, przeczytaj definicję rekordu i ustaw właściwy zakres dat.
4. Pobierz dane, sprawdź odpowiedź oraz wymagane pola i dopiero wtedy oblicz wskaźniki.

Pierwsze żądanie HTTP:

GET https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/endpoints
Api-key: TWOJ_KLUCZ_API
Accept: application/json

NAZWA_PANELU i TWOJ_KLUCZ_API są miejscami do zastąpienia własnymi wartościami. Endpoint endpoints zwraca listę z polami endpoint i description. Lista w artykule jest katalogiem źródeł; odpowiedź API określa dostęp konkretnego klucza.

Wspólne zasady pobierania

• Adres raportu ma postać /webservice/power-bi/source/NAZWA_ENDPOINTU. Autoryzacja odbywa się przez nagłówek Api-key.
• Wartości parametrów koduj dla URL, np. spację jako %20. Nazwę inwestycji należy przepisać zgodnie z systemem. Nieznanego parametru nie traktuj jako skutecznego filtra tylko dlatego, że odpowiedź ma status HTTP 200.
• Brak filtrów nie oznacza pełnej historii. Endpoint może mieć domyślny zakres dat, statusów i rodzajów obiektów. Dostępne inwestycje zawsze zależą od klucza.
• Zapisuj datę pobrania, zastosowane filtry i liczbę rekordów osobno dla każdego raportu. Kilka kolejnych pobrań nie stanowi jednej transakcji bazy danych.

Jak przekazywać parametry

Zasady z tego rozdziału obowiązują we wszystkich źródłach danych, nie tylko w czterech opisanych dalej szczegółowo. Filtry można podać na dwa sposoby i oba działają identycznie — zwracają odpowiedź co do bajta taką samą:

• pary segmentów w ścieżce URL — https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/clients-report/contact-created-date-from/2026-01-01/contact-created-date-to/2026-03-31
• klasyczny query string — https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/clients-report?contact-created-date-from=2026-01-01&contact-created-date-to=2026-03-31

W dokumentacji źródeł obowiązuje zapis w ścieżce — trzymaj się go, żeby przykłady były porównywalne. Wartości koduj dla URL, np. spację jako %20, a polskie znaki w nazwach inwestycji jako sekwencje UTF-8 (Jaworowe%20Wzg%C3%B3rze).

Nazwy parametrów przepisuj dokładnie. date-from i date_from to dwie różne nazwy i nie są zamienne, a API nie ma jednej konwencji — o tym, czy w danym raporcie obowiązuje myślnik, czy podkreślnik, decyduje wyłącznie opis tego raportu. Przykładowo clients-report i leads-report wymagają myślników (contact-created-date-from, lead-created-date-from), a agreements, sales-forecast i activities-list — podkreślników (date_from, activity_date_from). Ten sam raport potrafi mieszać obie konwencje: w agreements-registry obowiązują jednocześnie agreement_date_from z podkreślnikami i first-agreement-date-from z myślnikami.

Nazwa endpointu w ścieżce również jest zapisywana z myślnikami. Wariant z podkreślnikiem nie istnieje — lead_comparision zwraca HTTP 404 z pustą treścią. Poprawną listę nazw dostępnych dla Twojego klucza daje źródło endpoints.

Kody odpowiedzi HTTP

API zwraca JSON wyłącznie dla odpowiedzi udanych oraz dla błędów 400 i 500. Odmowa dostępu i nieznana nazwa endpointu zwracają treść w formacie HTML albo pustą treść — parser JSON zgłosi wtedy błąd składni, a nie pustą tabelę. Zanim odczytasz treść, sprawdź kod HTTP i nagłówek Content-Type.

Kodów 401 i 429 nie generuje samo API — kontroler zwraca wyłącznie 200, 400, 403, 404 i 500. Kody 429 i 503 mogą przyjść z zapory stojącej przed panelem, gdy zapytania są wysyłane zbyt często. W takiej sytuacji zmniejsz częstotliwość odpytywania i nie ponawiaj wielu zapytań równolegle; nagłówka Retry-After nie gwarantuje żadna warstwa aplikacji.

Błąd HTTP, niepoprawny JSON i pusta tablica to trzy różne sytuacje i nie wolno ich obsługiwać jedną gałęzią kodu.

Kształty odpowiedzi

Nie zakładaj jednego formatu. Na typowej instancji występuje sześć kształtów odpowiedzi. Loader powinien rozpoznawać je wszystkie, zanim zacznie czytać wiersze.

Uwagi praktyczne:

• Pole success występuje wyłącznie w kształcie 4 — jego brak nie oznacza błędu i nie warunkuj od niego wczytania danych w pozostałych raportach.
• Pusta odpowiedź może mieć postać [] (kształt 1) albo {"users": []} (kształt 5). Obie oznaczają brak danych dla podanych filtrów, a nie błąd.
• Kształty 5 i 6 nie mają pola data w ogóle — kod, który szuka go bezwarunkowo, wywróci się na tych raportach.
• Kształt potwierdź przy pierwszym pobraniu każdego raportu i sprawdzaj ponownie po aktualizacji systemu.

Domyślna populacja raportu to zwykle wycinek

Brak filtra nie oznacza pełnych danych. Raporty umów i płatności domyślnie pomijają część rekordów — bez odpowiedniego parametru wynik jest zaniżony, a system nie zgłasza żadnego ostrzeżenia. Liczby zmierzone na panelu demonstracyjnym (wrzesień 2026) pokazują skalę zjawiska:

Wartości filtrów statusowych: raz po angielsku, raz w języku panelu

Nazwy statusów podawane w filtrach nie mają jednej konwencji, a wartość nierozpoznana jest pomijana bez komunikatu — w odpowiedzi dostajesz wtedy pełny zbiór domyślny albo pustą tablicę, nigdy informację o błędzie.

• agreements-list — wyłącznie po angielsku: inprogress, signed, canceled. Zapytanie status/signed zwraca 157 rekordów, a status/Podpisane — 629, czyli wszystko.
• reservations-list — wyłącznie po angielsku: active, canceled, expired. Polskie nazwy zwracają pustą tablicę.
• sold-and-not-sold — odwrotnie: wartości są tłumaczone na język panelu, więc na instalacji polskiej wpisujesz Podpisana. Liczy się wielkość liter poza pierwszą, a statusu „Anulowana" tym filtrem nie wybierzesz.

Przy każdym filtrze statusowym sprawdź w opisie konkretnego raportu, której konwencji oczekuje, i porównaj liczbę rekordów z wynikiem bez filtra.

Filtr investment — literówka daje 403, a nie pustą listę

Wartość filtra investment jest dopasowywana do nazw inwestycji przypisanych do klucza API. Jeżeli żadna z podanych nazw się nie dopasuje, system odmawia dostępu tak samo jak przy nieważnym kluczu: HTTP 403 z pustą treścią odpowiedzi. Nie dostajesz pustej listy ani komunikatu o błędnej nazwie.

Zanim zaczniesz szukać problemu w kluczu API, sprawdź, czy nazwa inwestycji jest przepisana dokładnie tak, jak występuje w systemie — łącznie z wielkością liter, spacjami i znakami diakrytycznymi. Listę nazw, do których klucz ma dostęp, daje endpoint realestate-list: nazwy inwestycji są tam kluczami najwyższego poziomu odpowiedzi.

Przy kilku inwestycjach nazwy oddziela się przecinkiem, ale wystarczy jedna poprawna nazwa, żeby całe żądanie przeszło — pozostałe, zapisane błędnie, są po cichu pomijane i nie ma o nich żadnej informacji. Po ustawieniu filtra na kilka inwestycji zawsze porównaj liczbę inwestycji obecnych w odpowiedzi z oczekiwaną.

Przykład: https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/available-for-sale/investment/Jaworowe%20Wzg%C3%B3rze,Magiczny%20Zak%C4%85tek

Filtr investment nie usuwa z wyniku rekordów, które nie mają przypisanej inwestycji — w części raportów (m.in. clients-report, leads-report, mobile-call-list) są one zwracane zawsze, z pustą nazwą inwestycji. Dlatego sumy liczone osobno dla każdej inwestycji nie zsumują się do wyniku bez filtra: te same rekordy „bez inwestycji" powtórzą się w każdym wywołaniu.

Brak paginacji i wielkość odpowiedzi

API nie udostępnia parametrów limit, offset ani page. Każde żądanie zwraca komplet wierszy pasujących do filtrów — jedynym sposobem ograniczenia odpowiedzi jest zawężenie zakresu dat, inwestycji lub statusów. Odpowiedź jest budowana w całości w pamięci serwera przed wysłaniem, więc szeroki zakres na dużej instancji oznacza długie oczekiwanie i ryzyko przekroczenia czasu połączenia.

Dla orientacji — rzędy wielkości zmierzone na niewielkim panelu demonstracyjnym (ok. 610 umów w rejestrze, ok. 1600 lokali w kartotece, z czego 733 dostępne w sprzedaży):

Przy portfelu kilkunastu tysięcy lokali te same raporty osiągają dziesiątki megabajtów. Duże zakresy dziel na okresy (miesiąc, kwartał) albo na inwestycje i łącz wyniki po stronie Power BI. Przy pierwszym pobraniu zacznij od wąskiego, jawnie podanego zakresu — dopiero po sprawdzeniu odpowiedzi rozszerzaj go. Pamiętaj przy tym, że część raportów sama narzuca maksymalną szerokość okna dat (np. 3 lub 6 miesięcy) i przekroczenie jej kończy się kodem 400 z komunikatem, a nie skróconą listą.

Format liczb i kwot

Te same wielkości bywają zwracane w dwóch postaciach, zależnie od raportu:

• liczba JSON, z kropką dziesiętną — np. "Wartość BRUTTO": 243332.64, "amount": 63994.02, "realestate_value": 12196251;
• tekst w formacie polskim, z przecinkiem dziesiętnym i spacją jako separatorem tysięcy — np. "current_gross_price": "231 166,01", "Łączna sprzedaż (wartość netto) PLN": "182 116 524,86".

Separator tysięcy w drugiej postaci to zwykła spacja (U+0020), a nie spacja nierozdzielająca — przy czyszczeniu wartości wystarczy usunąć spacje i zamienić przecinek na kropkę. W Power Query ustaw typ Liczba dziesiętna z ustawieniami regionalnymi „Polski (Polska)". Nie stosuj tej konwersji hurtowo do wszystkich kolumn tekstowych.

Procenty również bywają tekstem z przecinkiem ("Łączna ilość (%)": "78,52") i nie są ułamkiem — to wartość wyrażona w procentach.

null, pusty tekst, brak pola i zero nie są zamienne. Kwoty obliczaj z precyzją dziesiętną.

Nazwy kluczy JSON — polskie i angielskie

API nie ma jednej konwencji nazewniczej i nie da się jej przewidzieć z nazwy endpointu.

• Raporty wywodzące się z eksportów CRM zwracają klucze po polsku, z polskimi znakami, spacjami i znakami interpunkcyjnymi: Typ umowy, Wartość BRUTTO, Końcowa NETTO, Źródło pochodzenia, Łączna ilość (%), L.P., Powierzchnia lokalu (total).
• Endpointy nowsze i integracyjne zwracają klucze angielskie w formacie technicznym: investment_name, sales_progress, realestate_count, transaction_id, client_crm_id, payment_date.

Ta sama informacja może więc nazywać się inaczej w dwóch raportach. Nie łącz tabel po podobieństwie nazw kolumn — przed połączeniem potwierdź, że chodzi o ten sam obiekt i tę samą przestrzeń identyfikatorów. Polskie nazwy kluczy pochodzą z tłumaczeń interfejsu, więc mogą się zmienić po aktualizacji systemu.

Parametr wspólny: format-numbers/1

Do adresu każdego raportu można dodać segment /format-numbers/1. Nazwy kolumn zostają wtedy przepisane na ASCII: polskie znaki tracą znaki diakrytyczne, kropka i nawias zamykający są usuwane, a nawias otwierający zamieniany na spację. Wartości pól pozostają bez zmian — parametr modyfikuje wyłącznie nazwy kluczy.

Przykład: https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/transaction-list-anonymized/format-numbers/1

Jak sprawdzić, czy filtr zadziałał

Status HTTP 200 nie potwierdza, że filtr został zastosowany. Nierozpoznany parametr, nierozpoznana wartość ze słownika i parametr zapisany w złej konwencji (myślnik zamiast podkreślnika) są pomijane po cichu. Dlatego każdy nowy filtr sprawdź jednym prostym testem.

• Wykonaj to samo zapytanie dwa razy: raz bez filtra, raz z filtrem, przy niezmienionych pozostałych parametrach.
• Porównaj liczbę rekordów: w kształcie 1 — długość tablicy, w kształtach 2–4 — długość tablicy data lub pole total_count / total_records, w kształtach 5 i 6 — liczbę elementów właściwej kolekcji.
• Identyczna liczba rekordów oznacza, że parametr albo jego wartość nie zostały rozpoznane, a nie że wszystkie rekordy spełniają warunek. Tak samo interpretuj identyczny rozmiar odpowiedzi w bajtach.
• Jeżeli filtr rzeczywiście zadziałał, sprawdź jeszcze zakres wartości w odpowiedzi — przy filtrze dat najstarszą i najnowszą datę w wyniku. Data starsza niż podana granica oznacza, że raport filtruje po innym polu, niż zakładasz.

Przykład filtra, który działa: .../clients-report zwraca 110 rekordów, a .../clients-report/contact-created-date-from/2026-01-01/contact-created-date-to/2026-03-31 zwraca 46 — zmienia się zarówno total_count, jak i długość tablicy data.

Przykład parametru zignorowanego: .../lead-comparision zwraca 24 wiersze i .../lead-comparision/nieistniejacy-parametr/abc zwraca te same 24 wiersze, odpowiedź jest identyczna co do bajta.

Gdy filtrów jest kilka, literówka w jednej nazwie wyłącza tylko ten jeden filtr — pozostałe nadal działają, więc wynik będzie zawężony, ale szerszy niż zamówiony. Porównanie z wywołaniem bez filtrów tego nie wykryje; sprawdzaj każdy filtr osobno.

Co oznaczają rekordy i identyfikatory

Zasada łączenia danych: zgodność wartości ID nie dowodzi wspólnego znaczenia. Przed połączeniem potwierdź obiekt, przestrzeń identyfikatora i relację jeden-do-jednego lub jeden-do-wielu. Brakującego klucza nie zastępuj automatycznie nazwą, e-mailem ani numerem telefonu. Pamiętaj też, że pokrycie wartości ID — czyli to, jaka część identyfikatorów z jednego raportu ma odpowiednik w drugim — jest diagnostyką jakości danych, a nie dowodem, że obie kolumny opisują ten sam obiekt; wysokie pokrycie równie dobrze potwierdza wspólną relację, co przypadkową zbieżność numeracji.

Katalog źródeł danych

Poniżej znajduje się katalog 41 źródeł danych. Szczegółowo rozwinięto pozycje 11, 16, 19 i 27. Pozostałe opisy służą orientacji w dostępnych raportach; nie są pełną specyfikacją odpowiedzi.

Ta lista jest katalogiem źródeł istniejących w systemie — nie listą uprawnień Twojego klucza. O rzeczywistym dostępie rozstrzyga odpowiedź endpointu endpoints (poz. 37), a nie ta tabela: klucz może widzieć węższy zestaw. Na panelu demonstracyjnym klucz widzi wszystkie 41 źródeł.

Leady i klienci

1. Raport leadów — porównanie (lead-comparision)

Zestawienie liczby leadów i klientów w podziale na miesiące. Domyślnie obejmuje 24 ostatnie miesiące: bieżący i 23 poprzednie.

Odpowiedź: tablica wierszy, jeden wiersz na miesiąc. Kolumny: Data, Data new, Leady, Usuniętych leadów, Powiązanych leadów, Klientów z leadów, Klientów, Klienci bezpośredni, Pierwszych spotkań, Umów rezerwacyjnych.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — ograniczenie do wybranych inwestycji spośród przypisanych do klucza
• date-from/MM-RRRR — pierwszy miesiąc zakresu, format miesiąc-rok, np. 01-2025
• date-to/MM-RRRR — ostatni miesiąc zakresu, np. 12-2025

⚠ Ważne: odpowiedź nie zawiera kolumny inwestycji. Filtr investment zawęża wyłącznie zbiór wejściowy — rozbicie wyniku na poszczególne inwestycje wymaga osobnego wywołania dla każdej nazwy. Dodatkowo podanie tego filtra usuwa z zestawienia klientów bez przypisanej inwestycji, więc wywołanie z filtrem i bez filtra liczą inne populacje.

⚠ Ważne: kolumny są liczone na różnych kohortach — leady po dacie utworzenia leada, klienci po dacie utworzenia klienta, pierwsze spotkania po dacie spotkania, umowy rezerwacyjne po dacie utworzenia umowy. To nie jest lejek: kolumn nie należy od siebie odejmować ani sumować. W szczególności Klientów z leadów i Klienci bezpośredni nie sumują się do Klientów — konwersja jest liczona w miesiącu, w którym nastąpiła, a nie w miesiącu pozyskania leada. W odpowiedzi panelu demonstracyjnego za styczeń 2025 jest Klientów 16, Klientów z leadów 0 i Klienci bezpośredni 8. Nie licz z tych kolumn udziałów procentowych.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/lead-comparision/investment/Osiedle%20Zielony%20Staw/date-from/01-2024/date-to/12-2024

2. Lista leadów (leads-list)

Szczegółowe informacje o leadach. Domyślnie pobiera dane z ostatnich 100 dni — zakres domyślny obowiązuje tylko wtedy, gdy nie podano ani date-from, ani date-to. Podanie samej daty początkowej wyłącza domyślne ograniczenie od góry, a samej końcowej — od dołu.

Odpowiedź: tablica wierszy. Zestaw bazowy kolumn, obecny zawsze: Id Lead, Osoba, Telefon, E-mail, Źródło pochodzenia, Opis, Status, Inwestycja, Utworzono, Przyp., Skonwertowany, Ostatnia zmiana. Kolumna Status to status leada (wartości spotykane w panelu demonstracyjnym: „Nowy”, „Skonwertowany”, „Powiązany”, „Usunięto”), a nie status klienta.

Cztery kolumny są warunkowe — pojawiają się dopiero po włączeniu odpowiedniego ustawienia panelu i domyślnie ich nie ma:

Dostępne filtry:

• date-from/DATA_OD — data utworzenia leada od (RRRR-MM-DD)
• date-to/DATA_DO — data utworzenia leada do (RRRR-MM-DD)
• lead-classifications/NAZWY_PO_PRZECINKU — klasyfikacje leada; wartość Puste wybiera leady bez klasyfikacji
• contact-classifications/NAZWY_PO_PRZECINKU — klasyfikacje powiązanego klienta; wartość Puste wybiera klientów bez klasyfikacji
• contact-classification-created-from/DATA_OD oraz contact-classification-created-to/DATA_DO — data nadania klasyfikacji klientowi (RRRR-MM-DD)
• contact-status/NAZWY_PO_PRZECINKU — status klienta; działa tylko w panelach z włączoną kolumną „Status klienta”
• date-modification-contact-status-from/DATA_OD oraz date-modification-contact-status-to/DATA_DO — data zmiany statusu klienta; działa tylko w panelach z włączoną kolumną „Data zmiany statusu klienta”

⚠ Ważne: trzy ostatnie pozycje są odczytywane wyłącznie wtedy, gdy w panelu włączona jest odpowiadająca im kolumna. Przy wyłączonym ustawieniu parametr nie zwraca błędu — jest po cichu ignorowany, a odpowiedź obejmuje pełny zakres. Reguła praktyczna: jeżeli w odpowiedzi nie ma kolumny „Status klienta”, filtr contact-status też nie działa.

⚠ Ważne: to źródło nie ma filtra investment zawężającego wynik. Nazwy klasyfikacji i statusów podawaj w języku panelu, dokładnie tak jak w słowniku — porównanie jest dosłowne, z automatycznym podniesieniem pierwszej litery. Nazwa, której nie ma w słowniku, nie zwraca błędu, tylko pustą listę.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/leads-list/date-from/2024-01-01/date-to/2024-12-31

3. Lista klientów (clients-list)

Szczegółowe informacje o klientach: dane osobowe, status, klasyfikacja, sposób finansowania, źródło pochodzenia, doradca, preferencje, zgody marketingowe, powiązane leady oraz dane UTM. Domyślnie wyświetla klientów z ostatnich 3 miesięcy.

Dostępne filtry:

• date_from/DATA_OD — data utworzenia klienta od (RRRR-MM-DD)
• date_to/DATA_DO — data utworzenia klienta do (RRRR-MM-DD)
• contact_id/ID_KLIENTA — ograniczenie wyniku do jednego klienta

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/clients-list/date_from/2024-01-01/date_to/2024-03-31

⚠ Ważne: przekroczenie 3 miesięcy albo podanie daty początkowej późniejszej niż końcowa zwraca HTTP 400 i komunikat w polu error: {"error":"The period between date_from and date_to cannot exceed 3 months"}.

4. Raport po klientach (clients-report)

Szczegółowe informacje o klientach wraz z datami ostatnich aktywności sprzedażowych (spotkanie, e-mail, telefon), liczbą dni bez aktywności, źródłem pierwszego i ostatniego kontaktu oraz zgodami RODO.

Odpowiedź: obiekt {success, timestamp, total_count, data}, w którym data jest tablicą wierszy o polach: contact_id, contact_name, contact_phone, contact_email, contact_status, investment_name, user_id, user_name, contact_created_date, contact_last_meeting_date, contact_last_email_date, contact_last_call_date, days_without_activities, contact_first_source, contact_last_source, contact_rodo_email_consent, contact_rodo_phone_consent, contact_last_call_comment.

⚠ Ważne: preferencji inwestycyjnych klienta ten raport nie zwraca — są dostępne w źródle clients-list, w kolumnie „Preferencje”. Raport podaje wyłącznie daty ostatnich aktywności; pełna lista aktywności jest w źródle activities-list.

⚠ Ważne: pole investment_name może zawierać kilka nazw inwestycji rozdzielonych przecinkami albo być puste — jeden wiersz to jeden klient, nie para klient–inwestycja. Kontakty w statusie anonimizacji są domyślnie pomijane; wchodzą do wyniku dopiero po użyciu filtra include-anonymized i mają wtedy null w polach imienia i nazwiska, e-maila, telefonu, komentarza oraz obu zgód.

Dostępne filtry (nazwy zawsze z myślnikami):

• contact-created-date-from/DATA_OD — data utworzenia klienta od (RRRR-MM-DD)
• contact-created-date-to/DATA_DO — data utworzenia klienta do (RRRR-MM-DD)
• user-id/ID_LUB_ID_PO_PRZECINKU — ID doradcy przypisanego do klienta; można podać kilka ID po przecinku, np. user-id/332,388
• contact-status/NAZWY_PO_PRZECINKU — nazwy statusów klienta w języku panelu, nie ID, np. contact-status/Przeterminowany; nazwę przepisz dokładnie ze słownika statusów swojego panelu
• investment/NAZWY_PO_PRZECINKU — ograniczenie do wybranych inwestycji spośród przypisanych do klucza
• include-anonymized/1 — dołącza kontakty w statusie anonimizacji, z wyzerowanymi danymi osobowymi i dodatkowym polem is_anonymized; działa tylko w panelach z włączonym ustawieniem power_bi_clients_report_include_anonymized

Filtry można przekazać zarówno jako pary segmentów w ścieżce URL, jak i jako parametry query string — wynik jest identyczny.

Przykład:

https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/clients-report/contact-created-date-from/2026-03-01/contact-created-date-to/2026-08-31/user-id/332

https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/clients-report?contact-created-date-from=2026-03-01&contact-created-date-to=2026-08-31

⚠ Ważne: podanie nazwy inwestycji, której klucz nie ma przypisanej, albo nazwy nieistniejącej, kończy się kodem HTTP 403 z pustą treścią — jeszcze przed wykonaniem raportu. Filtr investment nie usuwa natomiast z wyniku klientów bez przypisanej inwestycji: są zwracani zawsze, z pustym investment_name. Dlatego sumy liczone osobno dla każdej inwestycji nie zsumują się do wyniku bez filtra — te same rekordy „bez inwestycji” powtórzą się w każdym wywołaniu.

5. Raport po leadach (leads-report)

Informacje o leadach wraz z historią zmian statusu powiązanego klienta i datami ostatnich aktywności sprzedażowych.

Odpowiedź: obiekt {success, timestamp, total_count, data}, w którym data jest tablicą wierszy o polach: lead_id, lead_status, lead_removal_reason, contact_id, contact_name, contact_status, contact_status_history, lead_phone, lead_email, investment_name, user_id, user_name, contact_created_date, lead_created_date, lead_conversion_date, contact_last_meeting_date, contact_last_email_date, contact_last_call_date, lead_source, utm_data, lead_rodo_email_consent, lead_rodo_phone_consent, contact_last_call_comment.

Pole contact_status_history jest zagnieżdżoną tablicą obiektów {contact_status_date, contact_status}, uporządkowaną rosnąco po dacie — pozwala odtworzyć ścieżkę statusów klienta. W Power BI wymaga rozwinięcia kolumny (Expand), inaczej pokaże się jako List; dla leada bez powiązanego klienta jest pustą tablicą. Pole utm_data jest tekstem w formacie query string (utm_campaign=…&utm_source=…), a nie obiektem, i ma wartość null, gdy żaden znacznik UTM nie został zapisany.

⚠ Ważne: raport zwraca wyłącznie daty ostatniego spotkania, e-maila i telefonu. Pełna lista aktywności jest w źródle activities-list.

Dostępne filtry (nazwy zawsze z myślnikami):

• lead-created-date-from/DATA_OD — data utworzenia leada od (RRRR-MM-DD)
• lead-created-date-to/DATA_DO — data utworzenia leada do (RRRR-MM-DD)
• user-id/ID_LUB_ID_PO_PRZECINKU — ID doradcy przypisanego do leada, nie do klienta; można podać kilka ID po przecinku
• investment/NAZWY_PO_PRZECINKU — ograniczenie do wybranych inwestycji spośród przypisanych do klucza

Filtry można przekazać zarówno jako pary segmentów w ścieżce URL, jak i jako parametry query string — wynik jest identyczny.

Przykład:

https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/leads-report/lead-created-date-from/2026-03-01/lead-created-date-to/2026-08-31

⚠ Ważne: podanie nazwy inwestycji, której klucz nie ma przypisanej, albo nazwy nieistniejącej, kończy się kodem HTTP 403 z pustą treścią. Filtr investment nie usuwa z wyniku leadów bez przypisanej inwestycji — są zwracane zawsze, z pustym investment_name, więc wyniki dla poszczególnych inwestycji nie zsumują się do wyniku bez filtra.

6. Leady powiązane z umowami (lead-list-agreements)

Lista leadów powiązanych z umowami. Łączy dane leadów z informacjami o zawartych umowach.

7. Konwersje Google Ads (gclid-conversions)

Lista leadów z danymi konwersji Google Ads (GCLID). Służy do integracji konwersji offline z Google Ads. Zwraca leady skonwertowane, czyli powiązane z klientem, które mają niepuste pole GCLID.

Odpowiedź: tablica wierszy o pięciu polach: gclid, conversion_name (stała wartość „Konwersja offline”), conversion_time (data i godzina konwersji), email_address, investment (może być null).

⚠ Ważne: klasyfikacja leada nie jest warunkiem domyślnym tego źródła — odpowiedź w ogóle nie zawiera pola klasyfikacji. Jeżeli potrzebujesz wyłącznie leadów o wybranej klasyfikacji, np. „Ciepły Lead”, dodaj filtr lead-classifications/Ciep%C5%82y%20Lead.

Dostępne filtry:

• conversion-date-from/DATA_OD — data konwersji leada na klienta od (RRRR-MM-DD)
• conversion-date-to/DATA_DO — data konwersji do (RRRR-MM-DD)
• from/DATA_I_GODZINA — konwersje od podanego momentu, format RRRR-MM-DD GG:MM:SS (spację koduj jako %20); służy do pobrań przyrostowych
• investments/NAZWY_PO_PRZECINKU — nazwy inwestycji; parametr w liczbie mnogiej
• lead-classifications/NAZWY_PO_PRZECINKU — klasyfikacje leada, np. lead-classifications/Ciep%C5%82y%20Lead

Przykład:

https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/gclid-conversions/conversion-date-from/2026-01-01/conversion-date-to/2026-08-31

⚠ Ważne: błędny format parametru from zwraca HTTP 400 z komunikatem {"error":"Invalid date format for parameter from. Required format: YYYY-MM-DD HH:MM:SS"}.

8. Konwersje do Google Ads (google-ads-conversions)

Eksport leadów w formacie przygotowanym pod import konwersji offline oraz „enhanced conversions for leads” w Google Ads. Jeden rekord = jeden lead w powiązaniu z jedną inwestycją. Zamiast jawnych danych kontaktowych zwraca skróty SHA-256 (hashed_email, hashed_phone_number), zgody marketingowe, typ konwersji oraz GCLID, jeżeli lead go ma.

Odpowiedź: tablica wierszy o polach: investment, conversion_type (wartości: form-kontakt, klik-tel, call-page-koniec-rozmowy), conversion_name, conversion_time, hashed_email, hashed_phone_number, ad_user_data, ad_personalization, lead_quality, gclid, crm_id, extra_info.

Dostępne filtry:

• date-from/DATA_OD — data utworzenia leada od (RRRR-MM-DD)
• date-to/DATA_DO — data utworzenia leada do (RRRR-MM-DD)
• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (nazwy dokładnie jak w CRM)

Bez dat raport zwraca całą historię leadów. Data w innym formacie niż RRRR-MM-DD kończy się kodem HTTP 400 i treścią {"error":"Invalid date format, expected Y-m-d"}.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/google-ads-conversions/date-from/2026-08-01/date-to/2026-08-31

Ograniczenia:

• conversion_time to data utworzenia leada, a nie data kontaktu ani sprzedaży. Nie zawiera strefy czasowej — import do Google Ads wymaga jej dopisania.
• Lead przypisany do kilku inwestycji występuje w kilku wierszach z tym samym crm_id — liczbę leadów licz jako COUNT DISTINCT po crm_id.
• gclid bywa pusty; rekordy bez GCLID i bez skrótów są nieprzydatne do importu — odfiltruj je po swojej stronie.
• ad_user_data i ad_personalization pochodzą z jednej zgody marketingowej i zawsze mają tę samą wartość.
• Pola investment i lead_quality są zapisane małymi literami, ale filtr investment wymaga oryginalnej pisowni z CRM; nieznana nazwa kończy się kodem HTTP 403.
• Numer telefonu bez prefiksu kraju jest normalizowany do +48 przed zahaszowaniem — numery zagraniczne zapisz w CRM z prefiksem.

9. Historia leadów z portalu RynekPierwotny.pl (leads-activities-history-rp)

Raport zwrotny dla portalu RynekPierwotny.pl. Dla każdego leada z wypełnionym identyfikatorem RP zwraca dane kontaktowe, status klienta w CRM, status w słowniku RP oraz daty kluczowych zdarzeń: utworzenia i konwersji leada, ostatniego telefonu, ostatniego spotkania, zmiany statusu, rezerwacji ustnej, umowy rezerwacyjnej, przedwstępnej, deweloperskiej i końcowej.

Odpowiedź: tablica wierszy o polach: rynekpierwotnyid, lead_id, contact_name, contact_phone, contact_email, contact_status, rp_status, lead_created_date, lead_conversion_date, contact_last_call_date, contact_last_meeting_date, last_status_change, oral_reservation_date, reservation_agreement_date, preliminary_agreement_date, developer_agreement_date, final_agreement_date.

Dostępne filtry:

• date-from/DATA_OD — data utworzenia leada od (RRRR-MM-DD), nazwa z myślnikiem
• date-to/DATA_DO — data utworzenia leada do (RRRR-MM-DD), nazwa z myślnikiem
• contact_status/ID_STATUSÓW_PO_PRZECINKU — status klienta, nazwa z podkreślnikiem; wartość -1 oznacza brak statusu klienta
• rp_status/KODY_PO_PRZECINKU — status w słowniku RynekPierwotny, nazwa z podkreślnikiem

Zakres domyślny to ostatnie 12 miesięcy — daty są opcjonalne. Zakres dłuższy niż 12 miesięcy lub odwrócony kończy się kodem HTTP 400 i treścią {"error":"Invalid date-from or date-to parameter, or range exceeds 12 months"}.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/leads-activities-history-rp/date-from/2026-01-01/date-to/2026-08-31

Ograniczenia:

• Raport obejmuje WYŁĄCZNIE leady z identyfikatorem RynekPierwotny.pl. Na panelu bez tej integracji odpowiedzią jest pusta tablica [] — to nie jest błąd klucza ani awaria raportu.
• Nie ma filtra po inwestycji: zwracane są leady RP z całego panelu.
• Ten sam identyfikator RP może wystąpić przy kilku leadach — nie traktuj go jako klucza unikalnego.
• Numer telefonu złożony z samych cyfr wraca jako liczba; wczytaj tę kolumnę jako tekst, żeby nie zgubić wiodących zer.
• Odpowiedź zawiera imię i nazwisko, telefon oraz e-mail — nie publikuj jej w materiałach jawnych.

10. Kartoteka firm (company)

Pełna lista firm zapisanych w CRM: dane rejestrowe (NIP, REGON, KRS), kontakt, adresy, typ i branża, przypisany opiekun oraz pole opisowe opis_firma. Obejmuje zarówno klientów firmowych, jak i kontrahentów lub wykonawców — rozróżnia je pole kontrahent_firma (wartość logiczna true/false).

Odpowiedź: tablica wierszy. Klucze są w większości polskie (zapis snake_case z sufiksem _firma), identyfikatorem jest account_id. Na panelu demonstracyjnym raport zwraca 23 firmy po 30 pól.

Wybrane pola: account_id, uuid_firma, nazwa_firma, nazwa_skrocona_firma, nip_firma, regon_firma, krs_firma, email_firma, nr_telefonu_firma, tel_kom_firma, url_strony_firma, adres_siedziba_firma, adres_korespondencyjny_firma, typ_wlasnosci_firma, typ_firma, branza_firma, obszar_aktywnosci_firma, wielkosc_firma, tagi_firma, kontrahent_firma, instytucja_finansowa_firma, kategorie_zgloszen_kontrahent_firma, przypisana_do_firma, opis_firma.

Dostępne filtry: brak. Raport zawsze zwraca całą kartotekę firm, bez paginacji, bez zakresu dat i bez podziału na inwestycje. Segmenty /date-from/, /date-to/ i /investment/ są ignorowane — ale nieznana lub nieprzypisana kluczowi nazwa inwestycji nadal kończy się kodem HTTP 403.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/company

Ograniczenia:

• Brak powiązania firma–osoba: endpoint nie zwraca contact_id, a clients-list i clients-report nie zwracają account_id. W API nie ma więc sposobu na połączenie kartoteki firm z kontaktami.
• Adresy są sklejone w jeden tekst (ulica z numerem, kod pocztowy, miasto, województwo, kraj). Miasto i kod trzeba wyodrębnić samodzielnie.
• Pola wielowartościowe (branża, obszar aktywności, telefony, faksy, kategorie zgłoszeń) to jeden tekst rozdzielony przecinkami, a same nazwy słownikowe też mogą zawierać przecinki — nie rozdzielaj ich automatycznie.
• Pusty tekst oraz wartość „0” są zwracane jako null; url_strony_firma bywa placeholderem „http://” — traktuj go jak brak wartości.
• Tylko kontrahent_firma i instytucja_finansowa_firma są wartościami logicznymi; pozostałe pola to tekst albo null.
• Brak daty utworzenia i modyfikacji — źródło nie nadaje się do synchronizacji przyrostowej.
• Kolejność wierszy nie jest gwarantowana; sortuj po swojej stronie.

Umowy i rezerwacje

11. Rejestr umów i ich wartości (agreements-registry)

Rejestr opisuje umowy i ich wartości. Jeden wiersz jest wierszem raportu umów; przed liczeniem należy sprawdzić unikalność UUID umowy. Ten sam lokal może wystąpić na kilku etapach, np. w umowie rezerwacyjnej i deweloperskiej.

Odpowiedź: Tablica wierszy. Nazwy wielu kluczy pochodzą z tłumaczeń raportu.

Daty i status: pole Data jest datą umowy. Kolumna Podpisana, jeżeli występuje, jest datą, a nie wartością logiczną. O podpisaniu nie wnioskuj na podstawie samej obecności daty — sprawdź Status.

Parametry w ścieżce URL — wybrany zakres:

⚠ Nazwy parametrów tego raportu mieszają konwencje: agreement_date_from, agreement_date_to, include_canceled, status_id_filter i last_modified mają podkreślniki, a first-agreement-date-from, first-agreement-date-to i remote-sync — myślniki. Wariant zapisany w drugiej konwencji jest ignorowany bez błędu, a odpowiedź nadal ma status HTTP 200.

Kolumny Status (W toku / Podpisana / Anulowana) nie da się zawęzić żadnym parametrem tego endpointu — filtruj ją po pobraniu danych.

Przykład adresu:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/agreements-registry/agreement_date_from/2026-08-01/agreement_date_to/2026-08-31

Wybrane pola: tabela nie jest pełnym schematem odpowiedzi. Typy opisują oczekiwaną interpretację; typ JSON i możliwość pustej wartości potwierdź na próbce. Brak wymaganego pola zatrzymuje obliczenia.

Ilustracyjny JSON — fikcyjne wartości, wybrane pola:

[
  {
    "UUID": "11111111-1111-4111-8111-111111111111",
    "Typ umowy": "Umowa deweloperska",
    "Status": "Podpisana",
    "Data": "2026-08-12"
  },
  {
    "UUID": "22222222-2222-4222-8222-222222222222",
    "Typ umowy": "Umowa rezerwacyjna",
    "Status": "Podpisana",
    "Data": "2026-08-19"
  }
]

Jak interpretować przykład: Dla tych dwóch rekordów liczba unikalnych podpisanych umów wynosi 2. Nie wynika z tego, że sprzedano dwa różne lokale. Do serii miesięcznej ustal zestaw typów umów, wybierz status Podpisana i grupuj według Data. Nieznany typ lub status powinien być widoczny w kontroli jakości.

12. Eksport listy umów (transaction-list)

Eksport listy umów w takim kształcie, w jakim widzi ją użytkownik w module Umowy. Zawiera dodatkowe kolumny: „Budynek” oraz „Cena całkowita netto”.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (wartości koduj URL)
• all-agreements/1 — dołącza umowy anulowane; bez tego parametru raport ich nie zwraca
• first-agreement-date-from/DATA_OD — data pierwszej umowy na lokalu, od (myślniki, YYYY-MM-DD)
• first-agreement-date-to/DATA_DO — data pierwszej umowy na lokalu, do (myślniki, YYYY-MM-DD)

Endpoint nie ma filtra po dacie samej umowy — segmenty date-from i date-to są tu ignorowane bez błędu. Filtr first-agreement-date-* działa po dacie pierwszej umowy zawartej na danym lokalu, więc do okna wpadnie także umowa deweloperska z późniejszą datą, jeżeli rezerwacja tego lokalu mieści się w zakresie. Zawężanie po kolumnie „Data podpisania umowy” wykonuj po swojej stronie.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/transaction-list/all-agreements/1/investment/Osiedle%20Zielony%20Staw

Przykład z zakresem daty pierwszej umowy:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/transaction-list/first-agreement-date-from/2026-01-01/first-agreement-date-to/2026-08-31

13. Lista umów (agreements-list)

Szczegółowe informacje o umowach wraz z zagnieżdżonymi danymi klientów i lokali. Spośród raportów o umowach ten zwraca najpełniejszy zestaw identyfikatorów technicznych: transaction_id, client_crm_id, account_crm_id i agreement_local_crm_id. Odpowiedź to obiekt z tablicą transactions.

Domyślnie raport pomija umowy anulowane. Na panelu demonstracyjnym wywołanie bez filtra zwraca 629 rekordów, a ze status/inprogress,signed,canceled — 1505, w tym 876 ze statusem „Anulowana”.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (wartości koduj URL)
• status/STATUSY_PO_PRZECINKU — status umowy; wartości podaje się wyłącznie po angielsku: inprogress (W toku), signed (Podpisane), canceled (Anulowane). Wielkość liter bez znaczenia, wiele wartości po przecinku.
• agreement_created_date_from/DATA_OD — data utworzenia umowy w CRM, od (podkreślniki, YYYY-MM-DD)
• agreement_created_date_to/DATA_DO — data utworzenia umowy w CRM, do (podkreślniki, YYYY-MM-DD)

Filtry dat działają po dacie założenia rekordu w CRM (agreement_created_date), a nie po dacie umowy (agreement_date). Niepoprawny format daty kończy się odpowiedzią HTTP 400 z komunikatem „Invalid date format. Required format: YYYY-MM-DD”.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/agreements-list/status/inprogress,signed,canceled/agreement_created_date_from/2026-01-01/agreement_created_date_to/2026-08-31

14. Lokale z bieżącym etapem umowy (agreements)

Raport zwraca jeden wiersz na lokal — z etapem umowy, na którym lokal znajduje się obecnie (pole agreement_type). Nie jest to lista umów: wcześniejsze etapy tego samego lokalu, np. umowa rezerwacyjna poprzedzająca deweloperską, nie mają osobnych wierszy. Tym właśnie różni się od pozostałych raportów tej sekcji: agreements-registry, transaction-list i agreements-list liczą umowy, a agreements liczy lokale.

Odpowiedź: obiekt z tablicą data. Rekord zawiera wyłącznie pola opisowe: investment, rooms, first_agreement_date, agreement_type, agreement_status, realestate_type, realestate_area, realestate_m2_price, assigned_to oraz zagnieżdżoną tablicę contiguities (przynależności z cenami).

Umowy anulowane są pomijane — w odpowiedzi nie występuje agreement_status = „Anulowana”. Zestaw etapów wchodzących do raportu jest zaszyty w kodzie i różni się między wersjami wdrożenia, więc zanim cokolwiek policzysz, sprawdź na próbce swojego panelu, jakie wartości agreement_type faktycznie wracają. Na panelu demonstracyjnym wraca 458 wierszy: Umowa rezerwacyjna 265, Umowa deweloperska 155, Umowa końcowa 21, Umowa przedwstępna 17; w polu agreement_status tylko „W toku” (372) i „Podpisana” (86).

first_agreement_date jest datą najwcześniejszej umowy na tym lokalu, a agreement_type i agreement_status opisują umowę bieżącą — obie wartości mogą pochodzić z różnych umów.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (wartości koduj URL)
• date_from/DATA_OD — data umowy bieżącej od (podkreślniki, YYYY-MM-DD)
• date_to/DATA_DO — data umowy bieżącej do (podkreślniki, YYYY-MM-DD)
• sources/NAZWY_ŹRÓDEŁ_PO_PRZECINKU — źródło pochodzenia umowy (słownik źródeł umów, a nie źródło kontaktu używane w raporcie agreements-and-reservations)

W tym raporcie obowiązują nazwy date_from i date_to z podkreślnikiem. Wariant date-from / date-to jest ignorowany bez błędu — odpowiedź obejmuje wtedy całą historię, mimo statusu HTTP 200. Filtr dat działa po dacie umowy bieżącej, więc w wyniku mogą znaleźć się wiersze, w których first_agreement_date jest wcześniejsze niż podana data początkowa. Nazwa źródła spoza słownika nie wyłącza filtra — odpowiedź jest wtedy pusta.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/agreements/investment/Osiedle%20Przykladowe/date_from/2026-01-01/date_to/2026-08-31

15. Lokale z rezerwacjami (reservations-list)

Lista lokali z rezerwacjami. Odpowiedź to tablica wierszy z polskimi nazwami kluczy: Id, Lokal, Metraż m2, Inwestycja, Etap, Status, Typ rezerwacji, Wstępna cena rezerwacyjna, Doradca, Data utworzenia, Od, Wygasa. Bez parametru status raport zwraca wyłącznie rezerwacje aktywne.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (wartości koduj URL)
• status/STATUSY_PO_PRZECINKU — status rezerwacji; wartości podaje się wyłącznie po angielsku: active, canceled, expired (wielkość liter bez znaczenia, wiele wartości po przecinku)
• date-from/DATA_OD — data utworzenia rezerwacji od (myślniki, YYYY-MM-DD, warunek włączny)
• date-to/DATA_DO — data utworzenia rezerwacji do (myślniki, YYYY-MM-DD, warunek włączny)

W odpowiedzi pole Status jest tłumaczone na język panelu (Aktywne / Wygasłe / Anulowane), więc wartość wejściowa i wyjściowa mają różną postać. Nie przepisuj wartości z odpowiedzi z powrotem do adresu.

Endpoint nie obsługuje parametru all-agreements. Nierozpoznane segmenty ścieżki są ignorowane bez błędu — status HTTP 200 nie potwierdza, że filtr zadziałał. Filtry dat działają po dacie utworzenia rezerwacji w CRM, a nie po dacie jej rozpoczęcia (pole Od) ani wygaśnięcia (pole Wygasa); wariant z podkreślnikami (date_from / date_to) jest tu ignorowany.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/reservations-list/status/active,expired,canceled

Przykład z zakresem dat utworzenia rezerwacji:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/reservations-list/status/active,expired,canceled/date-from/2026-01-01/date-to/2026-08-31

16. Klienci i zarejestrowane etapy obsługi lokalu (agreements-and-reservations)

Raport zestawia kontakty oraz zarejestrowane etapy obsługi przedmiotu, np. lokalu. Model grupuje dane według kontaktu i przedmiotu. Jeden kontakt może wystąpić w wielu wierszach; nie jest to pełna lista wszystkich klientów CRM ani lista samych umów.

Odpowiedź: Obiekt z success i tablicą data. Przed odczytem wierszy sprawdź success.

Ważne rozróżnienie dat: date_from i date_to dotyczą daty utworzenia rekordu przedmiotu w modelu raportu (subject_to_order.date_created). Nie filtrują daty pozyskania kontaktu ani dat podpisania wszystkich pokazanych umów. Pola z końcówką _created_date opisują utworzenie etapu w CRM; pola daty umowy mają inne znaczenie.

Klient kupujący — definicja kanoniczna: klientem kupującym jest unikalny, niepusty contact_id, dla którego w co najmniej jednym wierszu wypełnione jest przynajmniej jedno z pól preliminary_agreement_date, developer_agreement_date lub notarial_deed_date. Sama rezerwacja nie czyni klienta kupującym. Licz to jako COUNT DISTINCT po contact_id, nie jako liczbę wierszy. Na panelu demonstracyjnym 465 wierszy odpowiada 226 klientom, z czego 117 spełnia tę definicję.

Źródło: source jest cechą kontaktu (contact.source_of_origin_id → contact_source_of_origin.name), a nie cechą umowy czy lokalu — jeden contact_id ma więc dokładnie jedną wartość źródła, niezależnie od tego, w ilu wierszach występuje. Na panelu demonstracyjnym żaden z 226 kontaktów nie miał dwóch różnych źródeł, więc „konflikt źródeł” w praktyce nie występuje i nie trzeba budować pod niego reguły. Realnym problemem jest wartość zbiorcza „Inne”: ma ją 38 z 226 klientów, czyli drugie co do wielkości „źródło” w zestawieniu — w analizie kanałów pokazuj ją jako osobną, nieprzypisaną pozycję, a nie rozdzielaj między kanały. Puste ID wyłącz z liczby unikalnych kontaktów i pokaż jako osobną liczbę błędów jakości (na panelu demonstracyjnym pustych contact_id nie było).

Parametry w ścieżce URL — wybrany zakres:

Nazwa źródła spoza słownika nie wyłącza filtra — odpowiedź jest wtedy pusta przy statusie HTTP 200. Ten sam parametr sources w endpointach agreements i lead-list-agreements korzysta z innego słownika (źródło umowy), więc nie kopiuj wartości między raportami.

Przykład adresu:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/agreements-and-reservations/investment/Osiedle%20Przykladowe

Wybrane pola: tabela nie jest pełnym schematem odpowiedzi. Typy opisują oczekiwaną interpretację; typ JSON i możliwość pustej wartości potwierdź na próbce. Brak wymaganego pola zatrzymuje obliczenia.

Ilustracyjny JSON — fikcyjne wartości, wybrane pola:

{
  "success": true,
  "data": [
    {
      "contact_id": "101",
      "investment": "Osiedle Przykladowe",
      "property": "A/01",
      "source": "Polecenie",
      "contact_method": "Telefon",
      "developer_agreement_date": "2026-08-12"
    },
    {
      "contact_id": "101",
      "investment": "Osiedle Przykladowe",
      "property": "A/02",
      "source": "Polecenie",
      "contact_method": "Telefon",
      "developer_agreement_date": null
    },
    {
      "contact_id": "102",
      "investment": "Osiedle Przykladowe",
      "property": "A/03",
      "source": "Inne",
      "contact_method": "Formularz WWW",
      "developer_agreement_date": null
    }
  ]
}

Jak interpretować przykład: Przykład ma 3 wiersze i 2 unikalne kontakty, a klient kupujący jest jeden — kontakt 101, bo w jednym z jego wierszy jest data umowy deweloperskiej. Kontakt 102 ma źródło „Inne”, czyli pozycję nieprzypisaną do kanału; nie zastępuj jej wartością z contact_method, bo Formularz WWW opisuje sposób kontaktu, a nie kanał pozyskania. Te liczby nie określają liczby transakcji ani konwersji kanału.

17. Anulowane umowy / Zwroty (returns)

Lista zwrotów, czyli umów, które najpierw miały status „Podpisana”, a następnie zostały anulowane. Zawiera dane o lokalu, datach umowy i anulowania oraz wartości umowy (netto/brutto).

Odpowiedź: tablica wierszy z ośmioma polami: ID umowy, Data anulowania umowy, Data podpisania umowy, Typ umowy, Numer lokalu głównego na umowie, Inwestycja, Wartość umowy netto, Wartość umowy brutto. Kolejność wierszy nie jest częścią kontraktu — jeżeli jej potrzebujesz, posortuj dane po swojej stronie.

Zakres: zawsze cała historia panelu. Endpoint nie obsługuje żadnych filtrów dat, więc zwraca wszystkie zwroty od początku istnienia danych, a nie wybrany okres. Na panelu demonstracyjnym 173 rekordy obejmują daty anulowania od 2024-12-06 do 2026-09-03 i daty podpisania od 2017-09-26 do 2026-08-20. Okno czasowe wytnij po swojej stronie, po polu Data anulowania umowy, i zapisz przy wskaźniku, którą datę wybrałeś.

Nie odejmuj tego raportu od rejestru umów „na oko”. Odpowiedź nie zawiera ani UUID umowy, ani UUID lokalu, a jedyny identyfikator, ID umowy, nie ma pokrycia w domyślnej odpowiedzi agreements-registry — na panelu demonstracyjnym żadna ze 173 wartości nie występuje wśród 610 wierszy kolumny Nr, bo rejestr domyślnie pomija umowy anulowane. Żeby zestawić oba raporty, pobierz rejestr z include_canceled/1 i dopiero wtedy łącz po Nr; bez tego kroku nie ma klucza pozwalającego jednoznacznie odjąć zwroty od liczby umów.

Zbiór obejmuje wszystkie typy umów obecne we wdrożeniu, także niesprzedażowe — na panelu demonstracyjnym m.in. Umowa najmu (11) i Umowa zmian lokatorskich (2), obok Umowy deweloperskiej (68), rezerwacyjnej (52), końcowej (31) i przedwstępnej (9). Do wskaźników sprzedaży zawęź listę typów po pobraniu danych.

Uwaga na dwie pułapki tego raportu. Po pierwsze, Data anulowania umowy bywa wcześniejsza niż Data podpisania umowy — na panelu demonstracyjnym dotyczy to 7 ze 173 rekordów. Nie licz z różnicy tych dat czasu życia umowy bez kontroli wartości ujemnych. Po drugie, Numer lokalu głównego na umowie może zostać zwrócony jako liczba (np. „5.20” jako 5,2), więc przy łączeniu z innymi raportami rzutuj go na tekst i licz się z utratą zer końcowych.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (wartości koduj URL). Endpoint nie obsługuje żadnych filtrów dat.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/returns/investment/Osiedle%20Zielony%20Staw

18. Cele sprzedażowe — plan i realizacja (investments-sales-targets)

Jedyne źródło celów sprzedażowych w API. Dla każdej inwestycji i każdego miesiąca, dla którego w CRM wpisano cel, zwraca plan liczby umów, umowy faktycznie podpisane, umowy w toku oraz wartość podpisanych umów — miesięcznie i narastająco. Osobno dla umów sprzedaży lokali (primary_transactions) i dla umów zmian lokatorskich (tenant_change_transactions).

Odpowiedź: pojedynczy obiekt z tablicą investments, nie tablica wierszy. Struktura jest zagnieżdżona: inwestycja → years → months → dwa bloki liczb. W Power BI rozwiń kolejno investments, years, months, a następnie rekordy primary_transactions i tenant_change_transactions.

Ilustracyjny JSON — fikcyjna nazwa inwestycji, liczby z panelu demonstracyjnego:

{
  "investments": [
    {
      "city": "Łódź",
      "investment_id": 12,
      "investment_name": "Osiedle Przykładowe",
      "years": [
        {
          "year": 2025,
          "months": [
            {
              "month": 1,
              "primary_transactions": {
                "goal_monthly": 5,
                "signed_monthly": 1,
                "planned_monthly": 1,
                "goal_cumulative": 15,
                "signed_cumulative": 18,
                "value_monthly_pln": 287841.46,
                "value_cumulative_pln": 4630702.33
              },
              "tenant_change_transactions": {
                "goal_monthly": 1,
                "signed_monthly": 0,
                "planned_monthly": 0,
                "goal_cumulative": 4,
                "signed_cumulative": 2,
                "value_monthly_pln": 0,
                "value_cumulative_pln": 2650
              }
            }
          ]
        }
      ]
    }
  ]
}

Znaczenie pól (identyczne w obu blokach):

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji; filtr zawęża wynik. Inwestycja bez wpisanych celów zwróci {"investments":[]}.

Raport nie ma filtrów dat — zwraca całą historię celów; zakres zawężaj po polach year i month po swojej stronie.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/investments-sales-targets

Płatności i finanse

19. Harmonogram i saldo transz (schedule-payment-list)

Raport przedstawia harmonogram płatności: kwotę transzy, jej termin oraz rozliczone i pozostałe kwoty. To stan rozliczenia transz w pobranym zakresie. Przed sumowaniem sprawdź unikalność identyfikatora transzy.

Odpowiedź: płaska tablica wierszy, 28 kolumn. Część nazw kluczy jest przetłumaczona na język panelu (Termin, Kwota, Zapłacono), część zostaje po angielsku (Schedule UUID, Client / Company full data).

Zakres domyślny: filtry date-from i date-to działają na terminie transzy — na polu Termin (w bazie due_date), czyli na planowanej dacie płatności, a nie na dacie wpływu środków. Brak date-from nie daje kompletu danych: serwer podstawia wtedy datę sprzed roku, więc starsze zaległości znikają z odpowiedzi bez żadnego ostrzeżenia. Brak date-to nie ustawia górnej granicy, więc odpowiedź zawiera także cały przyszły plan płatności.

⚠ Ważne: oba końce zakresu obcinają co innego i oba trzeba ustawić świadomie. date-from odcina zaległości starsze niż rok, date-to odcina przyszłe transze planu. Pomiar na panelu demonstracyjnym z 10.09.2026:

Domyślny rok terminów ukrył na panelu demonstracyjnym 351 zaległych transz na 17 928 349,10 PLN, czyli 37% całej zaległości. Jeżeli liczysz zaległości, podaj jawnie wczesną datę początkową — cofnij date-from do początku historii inwestycji. Ustawienie date-to na dzień pobrania nie zmienia zaległości, ale usuwa z odpowiedzi cały przyszły plan (tu 207 transz) — nie rób tego, jeżeli prognozujesz wpływy.

hide-lower jest domyślnie włączony — filtr działa przy każdej wartości poza dosłownym 0, w tym gdy parametru w ogóle nie ma. Przy włączonym filtrze dla każdego lokalu zwracane są wyłącznie transze z umowy o najwyższym etapie; transze umów niższego etapu, zastąpionych późniejszą umową (na przykład opłata rezerwacyjna po zawarciu umowy deweloperskiej), są ukryte. Na panelu demonstracyjnym hide-lower/0 zwraca 800 wierszy zamiast 703. Ustaw hide-lower/0, jeżeli rozliczasz także opłaty z umów wcześniejszych etapów.

only-not-paid/1 zawęża odpowiedź do transz nierozliczonych (na panelu demonstracyjnym 636 z 703 wierszy). Ten filtr ogranicza populację, więc nie licz na jego podstawie udziału zapłaconych kwot w całym harmonogramie — mianownik trzeba pobrać osobno, bez tego filtra.

Porównując dwa pobrania, zawsze używaj tego samego zakresu dat oraz tych samych ustawień hide-lower i only-not-paid. Przy każdym wskaźniku zapisz faktyczny zakres pobranych terminów.

Identyfikator transzy: kluczem wiersza jest kolumna Schedule UUID — zawiera UUID pojedynczej transzy (transaction_schedule_payment.uuid), a nie UUID całego harmonogramu. Etykieta w odpowiedzi jest nietłumaczona i brzmi dokładnie „Schedule UUID”, także na panelu polskim.

Na panelu demonstracyjnym 703 wiersze miały 703 różne wartości Schedule UUID przy 255 różnych umowach. Nie zastępuj tego pola ani kolumną ID umowy, ani Transaction UUID — jedna umowa ma wiele transz i obie te kolumny powtarzają się w wielu wierszach.

Parametry w ścieżce URL — wybrany zakres:

Populacja domyślna: raport zwraca transze umów o statusie W toku i Podpisana (na panelu demonstracyjnym 541 i 162 z 703 wierszy). Umowy anulowane wchodzą dopiero z cancelled-agreement/1. Licząc zaległości bez tego parametru, pomijasz umowy anulowane — zwykle o to chodzi, ale trzeba to zapisać w definicji wskaźnika.

⚠ Ważne: parametr remote-sync/1 nie zmienia odpowiedzi. W kodzie przypisuje on tę samą etykietę kolumny, którą raport ustawia i tak — nie usuwa żadnego pola. Kolumna Client / Company full data z pełnymi danymi kontaktów (imię, nazwisko, telefon, e-mail, contact_id, UUID) jest zwracana zawsze, także przy remote-sync/1 (na panelu demonstracyjnym pole wypełnione w 670 z 703 wierszy zarówno z tym parametrem, jak i bez niego; w 33 wierszach kolumna jest pusta razem z „Klient / Firma" i „ID klienta"). Nie istnieje parametr, który by ją wyłączył.

Jeżeli budujesz eksport bez danych osobowych, usuń tę kolumnę po swojej stronie bezpośrednio po pobraniu — nie licz na filtr po stronie API.

Przykład adresu:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/schedule-payment-list/date-from/2015-01-01/date-to/2026-08-31

Wybrane pola: tabela nie jest pełnym schematem odpowiedzi (wiersz ma 28 kolumn). Postacie potwierdzone na panelu demonstracyjnym 10.09.2026.

Ilustracyjny JSON — fikcyjne wartości, wybrane pola:

[
  {
    "Termin": "2026-08-15",
    "Kwota": 100000,
    "Zapłacono": 75000,
    "Pozostało": 25000
  }
]

Jak interpretować przykład: Dla tej ilustracyjnej transzy saldo wynosi 100 000 − 75 000 = 25 000 PLN. Na dzień 2026-09-10 saldo jest zaległe. Nie oznacza to, że 75 000 PLN wpłynęło w sierpniu — raport grupowany po Termin nie podaje daty wpływu. Przykład pomija identyfikator: nie służy do testowania deduplikacji.

20. Lista wpłat (payments)

Lista faktycznych wpłat zarejestrowanych na umowach, z datą księgowania — czyli tego, co wpłynęło, w odróżnieniu od raportu schedule-payment-list, który pokazuje planowany harmonogram transz. Umożliwia integrację z systemami ERP.

Odpowiedź: obiekt z tablicą data w postaci {"data": [ … ]}, nie płaska tablica. Pola wiersza: payment_id, invoice_id, document_number, amount, payment_date, investment_id, transaction_id. Nazwa inwestycji nie jest zwracana — jest tylko investment_id.

Dostępne filtry:

• date_from — data początkowa wpłaty (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem, nie z łącznikiem
• date_to — data końcowa wpłaty (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem
• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji
• include_cancelled_transactions/1 — dołącza wpłaty z umów anulowanych

Zakres domyślny: brak. Bez dat endpoint zwraca całą historię wpłat, bez stronicowania — na dużym panelu zawsze podawaj date_from i date_to. Domyślnie pomijane są wpłaty z umów anulowanych; do rozliczeń zwrotów dodaj include_cancelled_transactions/1.

Kontrola jakości: pole payment_date może zawierać wartość 0000-00-00 (wpłata bez uzupełnionej daty; na panelu demonstracyjnym jeden taki rekord). Jest on zwracany przy pobraniu bez filtra dat, ale znika przy każdym date_from — suma z całego zbioru i suma z pobrań miesięcznych mogą się z tego powodu różnić, bez żadnego komunikatu. Przy szeregach czasowych odrzuć takie rekordy i policz je osobno jako błąd jakości: nie zamieniaj ich na zero i nie pomijaj milcząco. Kwoty ujemne w polu amount to zwroty i korekty (na panelu demonstracyjnym 28 z 299 rekordów) — licz je oddzielnie od wpływów.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/payments/date_from/2026-01-01/date_to/2026-01-31

21. Lista faktur (invoices)

Lista faktur wystawionych w systemie voxCRM. Umożliwia integrację z systemami ERP.

Odpowiedź: obiekt z tablicą data w postaci {"data": [ … ]}, nie płaska tablica. Wiersz zawiera invoice_id, document_number, invoice_type, parent_invoice_id, correct_invoice_id, agreement_id, agreement_number, issue_date, sale_date, description, net_value, gross_value, vat_value oraz zagnieżdżone tablice contractors (dane kontrahenta) i items (pozycje faktury). Kluczem wiersza jest invoice_id; document_number nie jest unikalny (na panelu demonstracyjnym 412 różnych numerów na 440 faktur).

Dostępne filtry:

• date_from — data początkowa wystawienia faktury (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem, nie z łącznikiem
• date_to — data końcowa wystawienia faktury (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem
• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji

Zakres domyślny: brak. Bez dat zwracana jest cała historia faktur, bez stronicowania. Filtr dat działa na dacie wystawienia (issue_date).

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/invoices/date_from/2026-01-01/date_to/2026-01-31

22. Prognoza sprzedaży (sales-forecast)

Rejestr aktywnych umów w podziale na lokale: dane lokalu, ceny, rabaty, harmonogram wpłat i przyległości. Jeden wiersz to jeden lokal główny z bieżącą, nieanulowaną umową — także umową rezerwacyjną i umową w toku. To nie jest lista lokali sprzedanych. Na panelu demonstracyjnym 468 wierszy odpowiada 468 różnym lokalom głównym.

Odpowiedź: płaska tablica wierszy, 54 klucze po polsku. Pola „Każda płatność rozpisana” i „Anulowane umowy - szczegóły” są zagnieżdżonymi tablicami obiektów. Odpowiedź bywa bardzo duża — rzędu megabajtów: na panelu demonstracyjnym ok. 1,5 MB na 468 wierszy — i nie ma stronicowania, więc zawsze zawężaj zakresem dat albo inwestycją.

Dostępne filtry:

• date_from/DATA_OD — data zawarcia bieżącej umowy od (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem, nie z łącznikiem
• date_to/DATA_DO — data zawarcia bieżącej umowy do (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem
• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji

⚠ Ważne: warianty date-from i date-to z łącznikiem są ignorowane bez komunikatu — żądanie kończy się statusem HTTP 200 i pełnym zbiorem. Sama data użyta do filtrowania nie jest zwracana w odpowiedzi jako osobna kolumna.

Cztery kolumny cen zarządczych („Cena zarządcza brutto”, „Cena zarządcza netto”, „Cena m2 zarządcza brutto”, „Cena m2 zarządcza netto”) są wypełnione tylko dla lokali, którym uzupełniono cenę zarządczą w kartotece — na panelu demonstracyjnym wszystkie cztery są puste we wszystkich 468 wierszach. Brak wartości nie jest błędem; sprawdź pokrycie, zanim zbudujesz na nich wskaźnik.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/sales-forecast/date_from/2024-01-01/date_to/2025-01-01

Lokale i nieruchomości

23. Lista lokali (realestate-list)

Endpoint zwraca słownik lokali — mapowanie „UUID lokalu → nazwa lokalu”, pogrupowane według inwestycji. Jego zadaniem jest identyfikacja lokali, a nie raportowanie.

Odpowiedź: zagnieżdżony obiekt kluczowany nazwami inwestycji — {nazwa inwestycji: {UUID lokalu: {"name": "…"}}}. To nie jest tablica ani obiekt z polem data, więc w Power BI trzeba go spłaszczyć do wierszy (inwestycja, UUID, nazwa). Liczba elementów pierwszego poziomu to liczba inwestycji, a nie liczba lokali: na panelu demonstracyjnym 3 inwestycje i 1596 lokali.

{
  "Osiedle Zielony Staw": {
    "0f5c1c2e-…": { "name": "1.1" },
    "3a77b9d4-…": { "name": "1.2" }
  },
  "Osiedle Przykladowe": {
    "b214e0af-…": { "name": "A/12" }
  }
}

Zakres: wszystkie nieusunięte lokale w nieusuniętych inwestycjach przypisanych do klucza API — wszystkie rodzaje (mieszkania, miejsca postojowe, garaże, komórki, boksy, lokale komercyjne) i wszystkie statusy, także sprzedane i wycofane. Zapytanie nie ma sortowania, więc kolejność nie jest gwarantowana.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji. Filtr zawęża odpowiedź: podanie jednej nazwy zwraca jedną inwestycję, dwóch nazw — dwie. Kilka nazw rozdziel przecinkiem, wartości koduj URL.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/realestate-list/investment/Osiedle%20Zielony%20Staw

24. Lokale dostępne w sprzedaży (available-for-sale)

Lista lokali dostępnych w sprzedaży. Raport bierze pod uwagę cztery statusy kartoteki lokalu, a nie dwa: Dostępne, Rezerwacja ustna, Wstrzymane oraz czwarty status oznaczony w kodzie jako Reserved (jego etykieta zależy od tłumaczenia panelu). Na panelu demonstracyjnym 733 zwrócone rekordy to 728 Dostępne, 4 Wstrzymane i 1 Rezerwacja ustna.

Odpowiedź: płaska tablica wierszy. Pola: ID lokalu, Nazwa lokalu, Inwestycja, Etap, Typ, Status, Powierzchnia, Liczba pokoi, Piętro, Cena brutto, Cena netto oraz cztery kolumny cen zarządczych.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji

Endpoint nie ma filtra dat, sortowania ani stronicowania — zawsze zwraca pełną migawkę na moment pobrania.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/available-for-sale/investment/Osiedle%20Zielony%20Staw

25. Raport sprzedane i niesprzedane (sold-and-not-sold)

Zestawienie sprzedanych i niesprzedanych nieruchomości w podziale na rodzaje lokali, z ilościami, powierzchniami, wartościami i cenami za m2.

Odpowiedź: zagnieżdżony obiekt — nie płaska tablica i nie obiekt z polem data. Pierwszy poziom to trzy grupy: Sprzedane, Niesprzedane, Podsumowanie. Drugi poziom to nazwa typu lokalu (Mieszkanie, Garaż, Komórka lokatorska…) oraz pseudo-typ Suma. Trzeci poziom to jednoelementowa tablica z metrykami. W Power BI rozwiń kolejno: rekord grupy, rekord typu, listę.

{
  "Sprzedane": {
    "Mieszkanie": [ { "Ilość": 457, "Łączna ilość (%)": "78,52", … } ],
    "Garaż":     [ { … } ],
    "Suma":      [ { "Łączna sprzedaż (wartość netto) PLN": "…", "Łączna sprzedaż (wartość brutto) PLN": "…" } ]
  },
  "Niesprzedane": { "Mieszkanie": [ { "Ilość": 125, … } ], … },
  "Podsumowanie": { "Mieszkanie": [ { "Ilość": 582, … } ], … }
}

Definicje grup: zależą od konfiguracji panelu. Domyślnie Sprzedane obejmuje każdy lokal, którego bieżąca nieanulowana umowa jest co najmniej umową rezerwacyjną — a więc także umowy w toku i same rezerwacje. Niesprzedane to lokale o statusie kartoteki Dostępne lub Rezerwacja ustna, pomniejszone o lokale sprzedane; zmienne panelu decydują m.in. o tym, czy do niesprzedanych trafiają lokale wstrzymane. Ten sam raport na dwóch panelach może więc mieć różne definicje.

Dlaczego ten raport pokazuje inny procent sprzedaży niż status inwestycji. To najczęstsze źródło rozbieżności w raportowaniu portfela. Domyślnie raport uznaje lokal za sprzedany, jeżeli ma jakąkolwiek umowę — także rezerwację, która nigdy nie doszła do skutku. Oba raporty liczą „sprzedane”, ale według innych definicji, i na tych samych danych dają wyniki różniące się blisko siedmiokrotnie. Pomiar na panelu demonstracyjnym:

Jak uzgodnić obie liczby. Aby otrzymać wynik zgodny ze stanem portfela, dodaj filtr statusu umowy:

https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/sold-and-not-sold/agreement-status/Podpisana

Na panelu demonstracyjnym zapytanie zwraca wtedy 100 sprzedanych mieszkań zamiast 457 — co uzgadnia się ze stanem portfela z raportu investment-status (68 sprzedanych i 39 zarezerwowanych) oraz ze 105 unikalnymi lokalami z podpisanymi umowami w rejestrze.

Którego raportu użyć:

• „Ile lokali jest już zakontraktowanych, na jakim etapie jest sprzedaż projektu” — sold-and-not-sold. Uwzględnia umowy w toku, więc pokazuje realny stan komercjalizacji.
• „Ile umów jest domkniętych, ile możemy rozpoznać jako sprzedaż” — investment-status albo sold-and-not-sold z filtrem agreement-status/Podpisana.
• „Ile mieszkań można dziś kupić” — żaden z tych dwóch. Użyj available-for-sale z filtrem po polach Typ i Status.

Nie zestawiaj tych liczb w jednym wykresie i nie licz z nich wspólnych wskaźników. Populacje też nie są identyczne: sold-and-not-sold raportuje po nazwie typu („Mieszkanie”), a investment-status po grupie mieszkalnej z wyłączeniem lokali komercyjnych, komórek i boksów rowerowych.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji
• investment-stage/NAZWY_ETAPOW — etap (działa przy wyborze jednej inwestycji)
• investment-buildings/NAZWY_BUDYNKOW — budynek (działa przy wyborze jednej inwestycji)
• agreement-type/TYPY_UMOW_PO_PRZECINKU — typ umowy (Akt notarialny, Umowa deweloperska, Umowa przedwstępna, Umowa rezerwacyjna)
• agreement-status/STATUSY_PO_PRZECINKU — status umowy (Podpisana, W toku)
• date-from/DATA_OD — data podpisania umowy od (⚠ łączniki, nie podkreślniki)
• date-to/DATA_DO — data podpisania umowy do (⚠ łączniki)

Na panelu demonstracyjnym pobranie z zakresem 2026-01-01 – 2026-08-31 dało 160 sprzedanych mieszkań zamiast 457, przy Niesprzedane 127 zamiast 125 — udział sprzedanych spadł z 78,5% do 55,8%. Do sprzedaży w okresie użyj raportu agreements-registry, a ten raport pobieraj bez dat. Filtry investment, investment-stage i investment-buildings działają na obie grupy.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/sold-and-not-sold/investment/Osiedle%20Zielony%20Staw

26. Sprzedane przyległości (sold-associated-units)

Lista przyległości (komórek, boksów, miejsc postojowych) powiązanych z nieanulowanymi umowami — a więc także z umowami w toku i rezerwacyjnymi, nie tylko z podpisanymi.

Odpowiedź: płaska tablica wierszy o sześciu polach: ID lokalu, Powierzchnia, Cena zarządcza brutto, Cena zarządcza netto, Cena m2 zarządcza brutto, Cena m2 zarządcza netto. Automatycznie wyliczane są tylko cena netto i przeliczenia na m2 — cena zarządcza brutto jest polem kartoteki lokalu i bywa pusta (na panelu demonstracyjnym wszystkie 380 rekordów ma te pola puste).

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji
• date_from/DATA_OD — data umowy lokalu głównego od (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem
• date_to/DATA_DO — data umowy lokalu głównego do (YYYY-MM-DD); ⚠ nazwa z podkreślnikiem

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/sold-associated-units/investment/Osiedle%20Zielony%20Staw

27. Bieżący stan i wartość lokali (investment-status)

Raport przedstawia bieżący stan inwestycji w podziale na kategorie sprzedaży. Jeden rekord opisuje parę inwestycja–kategoria stanu, a nie pojedynczy lokal. Wartości odnoszą się do chwili pobrania, nie do historii sprzedaży w wybranym miesiącu.

Odpowiedź: obiekt z polami data (wiersze) i meta (metadane). Wiersz ma 14 pól: nazwę inwestycji, kategorię stanu oraz metryki dla pięciu grup rodzajów lokali — count, area i value dla grupy mieszkalnej i lokali komercyjnych, a count i value dla komórek, miejsc postojowych i boksów rowerowych. Gdy filtr statusu nie dopasuje kategorii, odpowiedź jest pustą tablicą [], a nie obiektem data/meta.

Zakres rodzajów lokali: raport rozbija stan na pięć rozłącznych grup, każda z własnymi polami:

• realestate_* — grupa mieszkalna, bez lokali komercyjnych, komórek i boksów rowerowych
• commercial_units_* — lokale komercyjne
• storage_units_* — komórki lokatorskie
• parking_spaces_* — miejsca postojowe i garaże
• bike_boxes_* — boksy rowerowe

Parametry w ścieżce URL — wybrany zakres:

Przykład adresu:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/investment-status/investment_name/Osiedle%20Przykladowe

Wybrane pola: tabela nie jest pełnym schematem odpowiedzi (wiersz ma 14 pól).

Ilustracyjny JSON — fikcyjne wartości, wybrane pola:

{
  "data": [
    {
      "investment_name": "Osiedle Przykladowe",
      "sales_progress": "Sprzedane",
      "realestate_count": 40,
      "realestate_value": 28000000
    },
    {
      "investment_name": "Osiedle Przykladowe",
      "sales_progress": "Zarezerwowane",
      "realestate_count": 10,
      "realestate_value": 7200000
    },
    {
      "investment_name": "Osiedle Przykladowe",
      "sales_progress": "Pozostałe",
      "realestate_count": 50,
      "realestate_value": 37500000
    }
  ],
  "meta": {
    "total_investments": 1,
    "generated_at": "2026-09-10 13:38:34",
    "status_note": "STAN AKTUALNY NA DATĘ WYGENEROWANIA RAPORTU"
  }
}

Jak interpretować przykład: 40 + 10 + 50 = 100 mieszkań w polu realestate_count, z czego 40% jest sprzedanych. Suma wartości 72 700 000 PLN łączy różne podstawy wyceny, dlatego nie należy nazywać jej przychodem. Przykład pomija kolumny przyległości i lokali komercyjnych — one nie wchodzą do tych 100.

Aktywności i kontakt

28. Raport spotkań (meeting)

Informacje o spotkaniach z klientami. Filtr dat działa na datę spotkania (Data spotkania), a nie na datę utworzenia. Domyślny zakres — bieżący rok kalendarzowy od 1 stycznia do 31 grudnia — włącza się wyłącznie wtedy, gdy nie podano ani date-from, ani date-to; obejmuje wtedy także spotkania zaplanowane w przyszłości. Podanie tylko jednego z parametrów dat daje zakres otwarty z drugiej strony. Endpoint nie ogranicza długości zakresu.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji
• date-from/DATA_OD — data spotkania od
• date-to/DATA_DO — data spotkania do

Przykład (spotkania za cały 2024 rok):
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/meeting/date-from/2024-01-01/date-to/2025-01-01/investment/Osiedle%20Zielony%20Staw

29. Lista aktywności klientów (activities-list)

Lista aktywności związanych z klientami (zadania, spotkania, telefony itp.).

Dostępne filtry:

• activity_date_from/DATA_OD — data początkowa (YYYY-MM-DD); domyślnie dzień dzisiejszy minus 12 miesięcy
• activity_date_to/DATA_DO — data końcowa (YYYY-MM-DD); domyślnie dzień dzisiejszy
• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji
• activity_status/NAZWA_STATUSU — status aktywności; nazwy dokładnie takie, jak w polu status odpowiedzi (np. Zaplanowane, Zakończony, Odbyło się, Wysłano); kilka wartości rozdziel przecinkiem
• activity_type/NAZWA_TYPU — typ aktywności; dopuszczalne wartości: telefon, spotkanie, email, zadanie, zaplanowany email (wielkość liter dowolna); kilka wartości rozdziel przecinkiem
• user_id/ID_UZYTKOWNIKA — ograniczenie do wskazanych doradców (identyfikatory rozdzielone przecinkiem)

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/activities-list/activity_date_from/2024-09-01/activity_date_to/2024-09-30

Kształt odpowiedzi: obiekt {"success": true, "timestamp": "YYYY-MM-DD HH:MM:SS", "total_records": N, "data": [ … ]}. Pola wiersza: id, activity_date, type, status, user_id, user, contact_id, contact, priority, notice, description, created_date, investment_name.

30. Historia transakcji klientów (contact-transactions)

Zestawienie zdarzeń handlowych klienta w podziale na inwestycje. Rekord = klient + inwestycja + rodzaj zdarzenia (pole event_type). Endpoint zwraca wyłącznie trzy rodziny zdarzeń: utworzenie klienta i konwersję leada na klienta, oferty online (kolejno numerowane: „Oferta 1", „Oferta 2", …) oraz umowy (rezerwacyjna, przedwstępna, deweloperska, końcowa) wraz z liczbą, powierzchnią i wartością lokali oraz przyległości.

Kształt odpowiedzi: obiekt {"data": [ … ], "meta": {"total_records": N, "generated_at": "YYYY-MM-DD HH:MM:SS"}}. Pola wiersza: contact_id, investment_name, event_type, date, realestate_count, realestate_area, realestate_value oraz liczniki przyległości (commercial_units_*, sold_storage_units_*, sold_parking_spaces_*, sold_bike_boxes_*).

Dostępne filtry:

• date_from/DATA_OD — data początkowa (YYYY-MM-DD); domyślnie dzień dzisiejszy minus 6 miesięcy
• date_to/DATA_DO — data końcowa (YYYY-MM-DD); domyślnie dzień dzisiejszy
• investment_name/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (kilka nazw rozdziel przecinkiem)
• contact_id/ID_KLIENTA — ograniczenie do jednego klienta

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/contact-transactions/date_from/2024-01-01/date_to/2024-06-30

31. Identyfikacja połączenia przychodzącego (incoming-call)

Endpoint pomocniczy dla integracji telefonicznej (Cludo). Dla podanego numeru telefonu zwraca powiązany kontakt, jego opiekuna oraz aktywnych użytkowników z oddziałów tego opiekuna. Nie zwraca listy ani historii połączeń — te dane znajdziesz w mobile-call-list (poz. 32).

Dostępne filtry:

• self_target/NUMER_TELEFONU — numer dzwoniącego (parametr wymagany; przed wyszukaniem usuwane są spacje, myślniki, kropki, przecinki i podkreślniki oraz prefiks +48 lub 48)

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/incoming-call/self_target/500600700

Kształt odpowiedzi: {"contact_id": …, "account_manager_id": …, "account_manager_email": …, "user_branch": [ {"name": "…", "users": [ {"id": …, "full_name": "…"} ]} ]}

Numer porównywany jest z telefonem służbowym, domowym i komórkowym kontaktu oraz z jego numerami dodatkowymi. Lista user_branch pomija użytkowników usuniętych oraz nieaktywnych (dezaktywowanych w CRM); pole account_manager_email pochodzi wprost z kartoteki kontaktu i może wskazywać także konto już nieaktywne.

32. Lista połączeń z aplikacji mobilnej (mobile-call-list)

Lista połączeń telefonicznych z aplikacji mobilnej. Każde połączenie zawiera: datę, numer telefonu, status (Wychodzące / Przychodzące / Nieodebrane), informację czy jest powiązane z klientem oraz czy klient posiada umowę.

Dostępne filtry:

• date-from/DATA_OD — data połączenia od (YYYY-MM-DD); domyślnie dzień dzisiejszy minus 3 miesiące
• date-to/DATA_DO — data połączenia do (YYYY-MM-DD); domyślnie dzień dzisiejszy
• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji
• contact-has-agreement/0|1 — 1 = tylko połączenia z klientami posiadającymi nieanulowaną umowę, 0 = tylko połączenia z pozostałymi numerami

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/mobile-call-list/date-from/2026-01-01/date-to/2026-06-30

33. Użytkownicy wskazanego oddziału (branch-users)

Lista użytkowników (doradców) przypisanych do jednego, wskazanego oddziału.

Dostępne filtry:

• name/NAZWA_ODDZIALU — pełna nazwa oddziału z CRM (parametr wymagany; nazwa musi zgadzać się w całości, fragment nazwy nic nie zwróci)

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/branch-users/name/Oddzia%C5%82%20Warszawa

Kształt odpowiedzi: {"users": [ {"id": 123, "full_name": "Nowak Jan"} ]} — pole full_name ma postać „nazwisko imię", a odpowiedź nie zawiera nazwy oddziału, więc przypisz ją po stronie integracji.

Endpoint pomija użytkowników usuniętych oraz nieaktywnych (dezaktywowanych w CRM), a także oddziały oznaczone jako usunięte.

Zmiany lokatorskie

34. Lista zmian lokatorskich (realestate-changes-list)

Lista zmian lokatorskich dotyczących nieruchomości. Wykorzystywany m.in. przy kopiowaniu umów z innych paneli.

Dostępne filtry:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji (nazwy dokładnie jak w CRM)
• last_modified/DATA — zwraca zmiany utworzone lub zmodyfikowane od podanej daty włącznie (format YYYY-MM-DD albo YYYY-MM-DD HH:MM:SS); służy do pobrań przyrostowych

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/realestate-changes-list/last_modified/2026-01-01

Techniczne i hurtownia danych

35. Lista dostępnych endpointów (endpoints)

Endpoint meta-informacyjny zwracający listę wszystkich źródeł Power BI nadanych danemu kluczowi API. Umożliwia programowe sprawdzenie, które źródła danych są dostępne.

Odpowiedź: tablica obiektów z polami endpoint i description.

[
  { "endpoint": "/webservice/power-bi/source/lead-comparision", "description": "Dane z raportu leadów - porównanie" },
  { "endpoint": "/webservice/power-bi/source/investment-status", "description": "Current sales status of the investment" }
]

Pole endpoint zawiera PEŁNĄ ścieżkę, a nie samą nazwę źródła. Nazwę, którą wstawiasz po /source/, weź z ostatniego segmentu tej ścieżki — nie doklejaj całej wartości do adresu bazowego.

Lista jest zawsze pełnym wykazem uprawnień klucza; nie ma tu filtrów. Dodanie segmentu /investment/NAZWA nie zawęża wyniku, a nieznana nazwa inwestycji kończy się kodem HTTP 403. Jeżeli w odpowiedzi widzisz źródło, którego nie ma w katalogu poniżej — jest dostępne, ale nieudokumentowane; przed użyciem uzgodnij jego zakres z działem wsparcia technicznego.

36. Rejestr umów — zanonimizowany (transaction-list-anonymized)

Okrojona wersja eksportu listy umów (transaction-list, poz. 12) — te same wiersze, ale węższy zestaw kolumn: bez danych klienta (nazwa klienta i firmy, ich identyfikatory, e-mail, telefon) oraz bez kolumn „ID umowy", „Numer lokalu", „ID lokalu głównego", „Budynek", „Przyległość", „Data anulowania umowy", „Kwota zniżki z umowy", „Procentowa wartość zniżki" i „Klasyfikacja umowy". Stworzony na potrzeby hurtowni danych.

Odpowiedź nie zawiera UUID umowy ani ID lokalu — jedynym identyfikatorem jest tekstowy „Numer umowy", który nie jest gwarantowanie unikalny. Do łączenia z innymi raportami użyj agreements-registry (poz. 11) lub transaction-list (poz. 12).

37. Zestawienie umów wg źródła pozyskania (warehouse-contracts-by-source)

Zanonimizowane zestawienie leadów, klientów, aktywności i umów w podziale na inwestycję i źródło pozyskania. Stworzony na potrzeby hurtowni danych. Jeden wiersz = inwestycja × źródło pozyskania × miesiąc (pole period zawiera pierwszy dzień miesiąca).

Parametry wymagane (bez nich raport nie zadziała):

• date-from/DATA_OD — data od (YYYY-MM-DD)
• date-to/DATA_DO — data do (YYYY-MM-DD)

Oba parametry są obowiązkowe i pisane z MYŚLNIKIEM. To jeden z nielicznych raportów bez zakresu domyślnego: wywołanie bez dat zwraca HTTP 400 i treść {"error":"Missing parameters date-from or date-to"}, a wartość, której system nie potrafi zinterpretować jako daty — HTTP 400 i {"error":"Invalid date format"}. Nie ma górnego limitu długości zakresu.

Parametr opcjonalny:

• investment/NAZWY_INWESTYCJI_PO_PRZECINKU — wybór inwestycji; podaj PRAWDZIWE nazwy z CRM, a nie aliasy I1/I2 widoczne w odpowiedzi

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/warehouse-contracts-by-source/date-from/2026-08-01/date-to/2026-08-31

Co oznacza tu anonimizacja: podmieniane są wyłącznie NAZWY — developer_name i investment_name dostają aliasy D1, D2… oraz I1, I2…. Pola investment_id, developer_id, city i voivodeship zawierają prawdziwe wartości.

Pola: developer_id, developer_name, investment_id, investment_name, city, voivodeship, source_of_origin_id, source_of_origin, period, leads_count, unique_clients_count, activities_count, reservation_agreements_count, sale_agreements_count, lead_created_date, contract_created_date.

Uwaga do liczników umów:

• reservation_agreements_count liczy UMOWY (transakcje) na etapie „Umowa rezerwacyjna",
• sale_agreements_count liczy unikalne LOKALE na etapie umowy deweloperskiej, przedwstępnej albo aktu notarialnego.

To różne jednostki — nie sumuj obu kolumn jako „umów". Brany jest bieżący etap przedmiotu, a nie historia: lokal zarezerwowany w sierpniu i sprzedany we wrześniu nie pojawi się już jako rezerwacja sierpniowa. Obiekty bez ustawionego źródła pochodzenia są pomijane we wszystkich kolumnach, dlatego sumy z tego raportu bywają niższe niż w leads-list czy agreements-and-reservations.

39. Zestawienie umów wg źródła pozyskania — wariant nieanonimizowany (warehouse-contracts-by-source-stg)

Ten sam raport co pozycja 39: ten sam zestaw 16 pól i te same filtry (date-from i date-to obowiązkowe, investment opcjonalny, ta sama obsługa błędów HTTP 400). Różnica polega na tym, że developer_name i investment_name zawierają prawdziwe nazwy zamiast aliasów D1/I1. Wszystkie pozostałe wartości, łącznie z licznikami, są identyczne — na panelu demonstracyjnym oba warianty zwróciły te same 34 wiersze, różniące się wyłącznie dwoma polami nazw. Wariant przeznaczony jest do wewnętrznej hurtowni danych.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/warehouse-contracts-by-source-stg/date-from/2026-08-01/date-to/2026-08-31

Dostęp do obu wariantów nadaje dział wsparcia technicznego; aktualną listę uprawnień swojego klucza sprawdzisz endpointem endpoints (poz. 37).

39. Dzienne statystyki użycia systemu (daily-statistics-usage)

Jeden wiersz na każdy dzień zakresu, z licznikami pracy w systemie: logowania użytkowników, utworzeni klienci i nowe leady, utworzone umowy, przeterminowane telefony i spotkania, dodane usterki, dostępne lokale i stany pozostałych etapów, wysłane oferty online oraz automatyzacje. Dane dotyczą całego panelu — nie ma podziału na inwestycje ani doradców.

Parametry wymagane (bez nich raport nie zadziała):

• date-from/DATA_OD — data od (YYYY-MM-DD)
• date-to/DATA_DO — data do (YYYY-MM-DD)

Nazwy pisze się z MYŚLNIKIEM. Podobnie jak pozycje 39 i 40, raport nie ma zakresu domyślnego: wywołanie bez dat zwraca HTTP 400 i treść {"error":"Missing parameters date-from or date-to"}, a wartość nieinterpretowalna jako data — HTTP 400 i {"error":"Invalid date format"}. Nie ma limitu długości zakresu.

Przykład:
https://NAZWA_PANELU.voxdeveloper.com/webservice/power-bi/source/daily-statistics-usage/date-from/2026-08-01/date-to/2026-08-31

Odpowiedź: tablica wierszy z polskimi nazwami kolumn, posortowana rosnąco po dacie: Data, Liczba logowań użytkowników, Utworzeni klienci, Nowe leady, Leady nieprzekonwertowane, Leady nierozpoznane, Utworzone umowy, Przeterminowane telefony, Przeterminowane spotkania, Dodane usterki, Dostępne lokale, Lokale zarezerwowane, Lokale umowa deweloperska, Lokale odebrane, Lokale umowa końcowa, Wysłane oferty online, Aktywne automatyzacje, Uruchomienia automatyzacji.

Ograniczenia:

• Wiersz za dany dzień powstaje dopiero po zadaniu nocnym uruchamianym o 23:55. Dzisiejszej daty jeszcze w odpowiedzi nie będzie.
• W jednym wierszu są trzy rodzaje liczników: dzienne przepływy (można je sumować po dniach), stany na koniec dnia (Dostępne lokale, Lokale zarezerwowane i pozostałe etapy oraz Aktywne automatyzacje) i narastające zaległości (Przeterminowane telefony, Przeterminowane spotkania). Stanów i zaległości nie sumuj po dniach.
• Kolumny dodane w kolejnych wersjach systemu mają zero za okres sprzed wdrożenia. Zero oznacza wtedy brak pomiaru, a nie brak zdarzeń.
• Segment /investment/NAZWA nie zawęża wyniku (dane są dla całego panelu), ale nieznana nazwa nadal kończy się kodem HTTP 403.

Zasady przygotowania analiz i pracy z agentem AI

• Stan portfela: licz kategorie lokali w investment-status. „Pozostałe” nie oznacza wyłącznie lokali dostępnych do sprzedaży.
• Dynamika umów: w agreements-registry ustal typy i statusy, sprawdź UUID i grupuj po dacie umowy. Porównuj pełne miesiące; bieżący miesiąc oznacz jako niepełny.
• Źródła klientów: licz unikalne niepuste contact_id w pobranym raporcie. Brak źródła, wartość „Inne” i sprzeczne źródła jednego kontaktu pokaż oddzielnie.
• Zaległości: sumuj dodatnie salda transz z terminem wcześniejszym niż dzień stanu. Transza z terminem dzisiejszym nie jest jeszcze zaległa według tej reguły. Pominięcie daty początkowej nie daje kompletu zaległości — przy braku date-from serwer sam cofa się dokładnie o rok od dnia pobrania i starsze transze w ogóle nie trafiają do odpowiedzi. Żeby policzyć pełne zaległości, podaj date-from jawnie, z datą wcześniejszą niż początek historii inwestycji, i zawsze zapisz w definicji wskaźnika zakres pobranych terminów. Na panelu demonstracyjnym pobranie domyślne pokazało 438 zaległych transz na 30 561 646,16 PLN, a pełna historia 789 transz na 48 489 995,26 PLN — poza domyślnym oknem zostało 351 transz na 17 928 349,10 PLN, czyli 37% całej zaległości.
• Sprawdzaj, czy filtr zadziałał: nierozpoznana nazwa parametru jest pomijana bez błędu — odpowiedź ma status HTTP 200 i wygląda poprawnie. Wykonaj to samo zapytanie dwa razy: z filtrem i bez niego. Jeżeli liczba rekordów jest identyczna, nazwa albo wartość parametru nie została rozpoznana i pracujesz na pełnym zbiorze. Na panelu demonstracyjnym lead-comparision bez parametrów i to samo źródło z dopisanym segmentem /nieistniejacy-parametr/abc zwróciły po 24 wiersze o identycznej treści. Wyjątkiem jest filtr investment: błędna nazwa nie daje pełnego zbioru, tylko HTTP 403 z pustą treścią.
• Procent sprzedaży: zawsze podawaj definicję przy liczbie. sold-and-not-sold i investment-status odpowiadają na różne pytania i na tych samych danych panelu demonstracyjnego dają 78,5% (lokal z jakąkolwiek umową, także rezerwacją, która nie doszła do skutku) wobec 11,4% (lokal ze sprzedażą potwierdzoną statusem w kartotece). Oba wyniki są poprawne — różnią się populacją, nie błędem. Wskaźnik bez podanego źródła i reguły zaliczania lokalu do sprzedanych jest nieporównywalny.
• Lejek i konwersja: nie dziel sum z niezależnych raportów bez wspólnej populacji, okresu i zweryfikowanych relacji. Nie dopisuj wcześniejszego etapu tylko dlatego, że istnieje późniejsza umowa.
• Publiczne materiały: wykorzystuj wybrane agregaty. Surowe odpowiedzi mogą zawierać dane osobowe. Zmiana nazw inwestycji nie usuwa informacji biznesowej zawartej w kwotach i liczebnościach.

Instrukcja dla agenta przygotowującego integrację

Aktualizowanie integracji

Po zmianie API porównaj dostępne endpointy, nazwy pól, kształt odpowiedzi i typy wartości. Sprawdź również znaczenie dat, statusów i populacji — mogą wpływać na wynik nawet wtedy, gdy nazwy kolumn pozostają takie same. Nieznaną zmianę zgłoś przed dalszym przeliczaniem raportu.

W przypadku problemów przekaż działowi wsparcia nazwę endpointu, zastosowane filtry, datę pobrania i komunikat błędu. Nie dołączaj klucza API ani danych osobowych do publicznego zgłoszenia.