# voxCRM Power BI API — llms.txt (katalog 2026-09-10-draft.2, 4 opisane raporty; live niepotwierdzone)

- Wersja robocza, sprawdzona w lokalnym kodzie; live i tłumaczone klucze wymagają potwierdzenia. Lista pól jest częściowa.
- GET https://<PANEL>.voxdeveloper.com/webservice/power-bi/source/<endpoint>/<filtr>/<wartość>; nagłówek Api-key z VOX_KEY. Zacznij od endpoints; nie zgaduj dostępu.
- Dokładne parametry wg karty; nie zamieniaj myślników na podkreślniki. Koduj wartości URL.
- Odpowiedź błędu i nieznany kształt przerywają obliczenia. Pusta lista nie dowodzi braku danych w całym CRM.
- Kwoty PLN parsuj bez zamiany braków i błędów w 0. Nie łącz ID przez float ani po samej zgodności numerów.
- Umowy ≠ unikalne lokale, transze ≠ wpłaty, stan dzienny ≠ zdarzenia. Nie uzupełniaj brakujących etapów lejka domysłem.
- Dane pobiera backend/skrypt; HTML zawiera tylko zatwierdzone agregaty, bez klucza i danych klientów.
- Pułapka 1: `Status` w agreements-registry to stan obiegu, nie fakt podpisania (demo1: 263 umowy z datą w polu `Podpisana`, tylko 52 ze statusem `Podpisana`). Licz po `Status = Podpisana` i raportuj wykluczenia; sprawdzian: unikalne lokale ≈ sprzedane+zarezerwowane z investment-status.
- Pułapka 2: „Inne" w `source` = domyślna pozycja słownika (NAME_OTHER, id 1) wstawiana, gdy nikt źródła nie wskazał — to NIE kanał (demo1: 38 z 226 klientów). Pokazuj osobno jako nieuzupełnione. `source` jest atrybutem kontaktu, więc konflikt źródeł nie występuje.
- Pułapka 3: date-from/date-to w schedule-payment-list filtruje `Termin` (planowany), nie datę wpłaty — okno ucina starsze zaległości i całą przyszłość planu. Do zaległości podawaj `date-from` jawnie i z zapasem — bez niego serwer cofa się tylko o rok (demo1: 438 transz zamiast 789).
- Cloudflare odrzuca domyślny User-Agent Pythona (`Python-urllib`) kodem 403 przed sprawdzeniem klucza — ustaw własny User-Agent w każdym wywołaniu.

## Model danych — zasady łączenia i źródła (skrót)
- ID przechowuj jako tekst z przestrzenią nazw panel:encja:id. Lead, kontakt, firma, umowa i lokal to różne encje.
- Zgodność numerów ani pokrycie zbiorów nie dowodzą wspólnej encji. Potwierdź mapowanie w kodzie, typy i krotność.
- Nie łącz po nazwach, e-mailach ani domenach automatycznie. Null ID nie jest kluczem.
- agreements-and-reservations.source to bieżące źródło kontaktu; leads-report.lead_source to źródło leada.
- Inne to wartość słownika, nie dowód braku źródła. Brak, Inne i konflikt źródeł raportuj osobno.

## Tier A (rdzeń)
- `investment-status` [data/meta, EN, PII:none] — Bieżący stan i wartość lokali Filtry: investment_name, status. Pola: investment_name, sales_progress, realestate_count, realestate_value, commercial_units_count, parking_spaces_count. ⚠ Pozostałe nie oznacza wyłącznie statusu Dostępne: oznacza brak dopasowanej umowy w logice tego raportu. | Nie nazywaj realestate_count liczbą wszystkich rodzajów lokali. Nie sumuj wartości jako przychodu.
- `agreements-registry` [array, PL / tłumaczenia, PII:names] — Rejestr umów i ich wartości Filtry: investment, agreement_date_from, agreement_date_to, include_canceled, status_id_filter. Pola: Nr, UUID, Typ umowy, Status, Data, ID lokalu, UUID lokalu, ID Klient, Wartość BRUTTO, Końcowa BRUTTO. ⚠ Etapy jednej sprzedaży mogą występować jako różne umowy. Suma ich wartości nie jest przychodem ani wartością unikalnych sprzedanych lokali. | Nie odejmuj liczby returns od liczby dowolnych umów bez uzgodnienia populacji i identyfikatorów.
- `agreements-and-reservations` [success/data, EN, PII:names] — Klienci i zarejestrowane etapy obsługi lokalu Filtry: investment, date_from, date_to, sources. Pola: contact_id, investment, property, source, contact_method, reservation_created_date, developer_agreement_created_date, developer_agreement_date, notarial_deed_date, current_gross_price. ⚠ COUNT(*) liczy powiązania, nie klientów. Do klientów COUNT DISTINCT niepustego contact_id. | Późniejszy etap nie dowodzi wcześniejszego. Nie dopisuj rezerwacji klientom z samym aktem.
- `schedule-payment-list` [array, PL / tłumaczenia, PII:full] — Harmonogram i saldo transz Filtry: investment, date-from, date-to, only-not-paid, hide-lower. Pola: Termin, Kwota, Zapłacono, Pozostało, ID umowy, Schedule UUID. ⚠ Raport może zawierać pełne dane kontaktów w zagnieżdżonym JSON; publiczny eksport wyłącznie przez listę dozwolonych agregatów. | Domyślny rok terminów może pomijać starsze zaległości.

## Tier B (uzupełniający)

## Tier C (pozostałe — tylko nazwy)


## Czego nie ma
- Plan sprzedaży poza zakresem startera (deferred): investments-sales-targets jest w routerze commita indeksowanego przez vox-rag. Nie zweryfikowano tu danych live i kontraktu metryk. Obejście: Osobna iteracja po uruchomieniu czterech raportów startowych.
