Chcesz stworzyć raport dopasowany do potrzeb swojego działu? Z pomocą agenta AI możesz przygotować własny dashboard HTML z danych voxCRM: wykresy, tabele i filtry, które otworzysz w przeglądarce.
Nie musisz samodzielnie pisać kodu. Opisujesz, co chcesz analizować, a agent korzysta z dokumentacji API, przygotowuje pobranie danych i buduje raport. Następnie możesz rozwijać go przez rozmowę — zmieniać układ, dodawać zestawienia i pytać o wyniki.
Każda firma potrzebuje trochę innego raportu
Dyrektor sprzedaży chce porównać inwestycje i zobaczyć, jak zmienia się liczba podpisywanych umów. Marketingowiec chce przyjrzeć się źródłom klientów. Zarząd potrzebuje krótkiego przeglądu portfela i płatności. Nawet rozbudowany zestaw raportów nie odpowie na każde pytanie w układzie, który akurat jest potrzebny.
Agent AI pozwala przygotować taki widok na własne potrzeby. Opisujesz po polsku, co chcesz zobaczyć, a agent pisze kod raportu, wykonuje obliczenia i tworzy plik HTML. Potem możesz poprosić o inne zestawienie, większy wykres, filtr albo wyjaśnienie konkretnej liczby. Nie musisz samodzielnie programować interfejsu.
Zacznij od danych i pytania, następnie przygotuj z agentem pierwszą wersję, sprawdź wynik i wprowadź potrzebne poprawki. Dobry dashboard powstaje w rozmowie o tym, czego naprawdę potrzebujesz.
API powstało dla Power BI. Może z niego korzystać również agent AI
API to sposób, w jaki jeden program pobiera dane z drugiego. voxCRM udostępnia w ten sposób raporty w formacie JSON — uporządkowanym zapisie danych, który program może odczytać. Interfejs powstał z myślą o Power BI, stąd nazwa i ścieżka power-bi w adresach.
Do wykorzystania tych danych nie jest jednak potrzebny Power BI. Agent AI potrafiący tworzyć i uruchamiać skrypty może przygotować pobranie z tego samego API, obliczyć potrzebne wskaźniki i zbudować własny dashboard HTML. Potrzebuje dokumentacji, dostępu oraz informacji, co chcesz analizować.
Jeżeli wolisz pracować w Power BI, to samo API opisuje artykuł Integracja z Power BI. Obie drogi korzystają z tych samych źródeł danych i tych samych zasad zapisu filtrów.
| W pracy z plikiem Excel | W pracy z API voxCRM |
| Agent odczytuje dane z przygotowanego Excela. | Agent przygotowuje pobranie raportów z CRM przez API. |
| Opisujesz, jaki kokpit ma powstać. | Opisujesz pytania, inwestycje, okres i oczekiwany wygląd. |
| Otwierasz wynikowy HTML w przeglądarce. | Otwierasz własny HTML z danymi pobranymi z CRM. |
| Po zmianie Excela prosisz o przeliczenie raportu. | Prosisz o nowe pobranie danych i przygotowanie kolejnej wersji. |
Zmienia się źródło danych. W obu przypadkach pracujesz podobnie: folder, rozmowa z agentem i raport, który można dalej rozwijać.
Co oznacza „dashboard w HTML”?
To plik otwierany w przeglądarce, podobnie jak strona internetowa. Może zawierać wykresy, karty z najważniejszymi liczbami, tabele, filtry i szczegóły dostępne po kliknięciu. Możesz poprosić o jeden samodzielny plik, który działa po otwarciu z dysku — bez zakładania strony i uruchamiania serwera.
Plik pokazuje dane zapisane podczas jego przygotowania. Żeby mieć aktualne liczby, agent musi ponownie pobrać dane i przeliczyć raport. Samo odświeżenie zakładki w przeglądarce tego nie robi. Automatyczne odświeżanie można zaprojektować później.
Warto poprosić, żeby obok pliku HTML powstało krótkie streszczenie tekstowe policzone z tych samych danych: te same liczby, definicje i zakres, zapisane zwykłym tekstem. Wklejasz je do maila, porównujesz z CRM albo podajesz innemu narzędziu bez otwierania przeglądarki. Jeżeli streszczenie i wykres pokazują różne liczby, to sygnał, że coś liczone jest dwa razy w dwóch miejscach.
Jak zacząć we własnej firmie?
1. Wybierz pierwsze pytanie
Nie musisz od razu projektować wszystkich ekranów. Zacznij od potrzeby, którą potrafisz opisać, np.:
Możesz też przekazać agentowi obecny raport lub przykładowy układ i napisać: „Chcę podobny widok, ale z naszymi danymi”. Przykład jest inspiracją dla wyglądu; nie dowodzi, że wszystkie pokazane w nim wskaźniki da się policzyć z dostępnych źródeł.
2. Uzyskaj dostęp do danych
Klucz API tworzy się w panelu CRM, na ekranie Usługi Web - aplikacje. Jest to ekran administracyjny — jeżeli nie masz do niego uprawnień albo nie wiesz, jaki zakres danych wybrać, zgłoś się do działu supportu voxCRM. Napisz, że chcesz stworzyć własny dashboard z pomocą agenta AI, i wskaż interesujące Cię dane oraz inwestycje.
Potrzebna będzie też nazwa panelu. To część adresu Twojego CRM przed .voxdeveloper.com — jeśli logujesz się na mojafirma.voxdeveloper.com, nazwą panelu jest mojafirma. Agent poprosi Cię o nią przy pierwszym pobraniu danych.
Przy kluczu trzeba ustawić trzy rzeczy naraz:
- zaznaczyć usługę PowerBi wśród usług dostępnych dla klucza,
- wskazać inwestycje, do których klucz ma mieć dostęp,
- zaznaczyć konkretne endpointy, czyli raporty, z których klucz może korzystać.
investment-status, agreements-registry, agreements-and-reservations, schedule-payment-list. Siedem kolejnych dokłada sekcje, jeśli klucz ma do nich dostęp: returns, available-for-sale, payments, investments-sales-targets, clients-report, meeting, activities-list. Wklej tę listę do zgłoszenia. Bez siedmiu ostatnich kokpit powstanie, tylko będzie uboższy — między innymi bez lejka sprzedaży.Brak któregokolwiek z tych trzech ustawień kończy się odmową dostępu. To najczęstsza przyczyna komunikatu „HTTP 403” przy pierwszym pobraniu — i nie znaczy on, że danych nie ma.
3. Otwórz folder pracy z agentem
Utwórz folder, np. „Dashboard sprzedaży”, i otwórz go jako projekt w narzędziu agenta AI. Potrzebujesz narzędzia, które potrafi tworzyć pliki i uruchamiać skrypty, a nie tylko odpowiadać w rozmowie. Potrzebny będzie też Python w wersji 3.9 lub nowszej — sprawdzisz go poleceniem python3 --version. Jeśli na firmowym komputerze trzeba coś zainstalować lub uzyskać uprawnienia, skorzystaj z pomocy działu IT.
4. Pobierz paczkę startową
Na dole artykułu jest link do paczki startowej ZIP, pobierz ją i rozpakuj. Powstanie folder voxcrm-agent-starter i to jego otwórz w agencie jako projekt — wszystkie pliki z tabeli niżej leżą w środku. Nie musisz nic konfigurować ani instalować niczego poza Pythonem.
W środku jest wszystko, czego agent potrzebuje, żeby nie zgadywać:
| Plik | Do czego służy |
START.md |
przewodnik dla Ciebie — pięć kroków od klucza do gotowego raportu |
AGENTS.md |
instrukcja dla agenta: procedura pracy, zasady rzetelności i pułapki danych |
KATALOG_RAPORTOW.md |
wszystkie raporty API: co dają, jak są zbudowane, czego w nich nie ma |
POLECENIA.md |
gotowe polecenia do skopiowania — pierwszy raport, zmiany, odświeżanie, analiza |
narzedzia/vox_fetch.py |
pobiera dowolne raporty, do których ma dostęp Twój klucz |
przyklad/ |
gotowy kokpit zarządu wraz z kodem — wzór do przerobienia albo do porównania |
dokumentacja/ |
szczegółowe karty czterech raportów rdzenia i skrót do wczytania agentowi |
wyniki/ |
tu trafiają kolejne wersje raportu: plik HTML i streszczenie tekstowe |
Zanim zaczniesz pracę na własnych danych, otwórz przyklad/dashboard-przyklad.html. To działający raport zbudowany dokładnie tą metodą, na danych panelu demonstracyjnego — zobaczysz, czego można się spodziewać. Twój raport może wyglądać zupełnie inaczej; to Ty decydujesz, co ma pokazywać.
5. Zleć pierwszą wersję
Agent nie powinien zgadywać, jak działa API. Jeśli pracujesz z paczką startową, wystarczy poprosić go o przeczytanie plików AGENTS.md i KATALOG_RAPORTOW.md — są w nich opisane wszystkie dostępne raporty, ich pułapki i sposób pobierania danych. Jeśli budujesz od zera, podaj mu artykuł Endpointy Power BI — lista dostępnych źródeł danych. Gdy agent nie może otworzyć strony, przekaż mu jej treść.
Poniższe polecenie możesz skopiować i uzupełnić. Nie wymaga znajomości kodu:
Przeczytaj AGENTS.md i KATALOG_RAPORTOW.md w tym folderze — to instrukcja i katalog dostępnych danych.
Chcę samodzielnie stworzyć dashboard HTML na podstawie API voxCRM. Pracuję jako [rola]. Potrzebuję odpowiedzi na pytania: [Twoje pytania]. Interesują mnie [inwestycje] i [okres]. Panel to [nazwa panelu — pierwszy człon adresu, pod którym loguję się do CRM]; klucz podam lokalnie, nie w rozmowie, ustawię go w terminalu.
Najpierw sprawdź, jakie raporty widzi mój klucz i co rzeczywiście da się z nich policzyć. Jeżeli jakiegoś wskaźnika policzyć się nie da, powiedz to wprost zamiast szacować. Jeżeli brakuje informacji o znaczeniu danych, zapytaj mnie zamiast zgadywać. Zaproponuj układ raportu.
Po mojej akceptacji przygotuj pobranie przez API i jeden samodzielny plik HTML z wykresami, tabelami oraz filtrami odpowiednimi do danych. Obok niego zapisz streszczenie tekstowe policzone z tych samych danych. Nie zmieniaj niczego w CRM.
Każdy filtr zweryfikuj: porównaj liczbę wierszy z filtrem i bez niego. API nie zgłasza błędu przy złej nazwie parametru — po prostu go pomija, więc identyczny wynik oznacza, że filtr nie zadziałał. Nie zakładaj, że brak daty początkowej daje pełną historię; sprawdź to w katalogu raportów.
Sprawdź sumy, duplikaty i okresy. Przy błędzie pobrania lub braku wymaganych danych zatrzymaj tę część analizy i wyjaśnij problem. Nie uzupełniaj braków fikcyjnymi liczbami i nigdy nie raportuj zera, którego nie potwierdziłeś.
Przy wykresach opisz, co liczą, jaki mają zakres i skąd pochodzą liczby. Nie myl liczby umów z liczbą sprzedanych lokali ani terminu transzy z datą wpływu pieniędzy. Do obliczeń i raportu wybierz tylko potrzebne pola; surowych danych osobowych nie wypisuj w rozmowie.
Zapisz wynik jako nowy plik w folderze „wyniki”, bez nadpisywania poprzedniej wersji. Otwórz go, jeśli potrafisz. Pokaż krótkie podsumowanie i wskaż liczby, które mam porównać z CRM. Zapisz w folderze instrukcję odświeżania i uzgodnione definicje wskaźników.
Dwie drogi: sprawdzony kokpit albo raport od zera
Pierwszy raport warto zbudować najprostszą dostępną drogą, a dopiero potem go rozwijać.
| Droga | Na czym polega | Kiedy wybrać |
| Gotowy kokpit z paczki | Agent uruchamia przykład na Twoim kluczu: cztery raporty rdzenia plus siedem dodatkowych, jeżeli klucz ma do nich dostęp. Układ i obliczenia są już opisane i sprawdzone. | Na pierwszy raz, żeby zobaczyć własne liczby i potwierdzić, że dostęp działa. |
| Raport od zera | Agent projektuje układ pod Twoje pytania i sam dobiera źródła z katalogu raportów. | Gdy wiesz już, czego chcesz, i gotowy kokpit tego nie pokazuje. |
Obie drogi korzystają z tej samej dokumentacji i tych samych narzędzi. Różnica polega na tym, że w pierwszej agent odtwarza sprawdzony układ, a w drugiej projektuje nowy — i wtedy więcej decyzji wymaga Twojego potwierdzenia.
Jakie analizy warto przygotować na początek?
W dokumentacji rozwinęliśmy cztery źródła, które mogą posłużyć do pierwszego kokpitu:
| Obszar | Przykładowy widok | Źródło dla agenta |
| Portfel inwestycji | Stan lokali, udział sprzedanych i porównanie inwestycji. | investment-status |
| Umowy | Liczba podpisanych umów w miesiącach i ich rodzaje. | agreements-registry |
| Źródła klientów | Źródła unikalnych kontaktów występujących w raporcie oraz braki przypisania. | agreements-and-reservations |
| Płatności | Saldo transz, zaległości i czas oczekiwania w pobranym zakresie terminów. | schedule-payment-list |
To cztery źródła opisane najdokładniej, bo wystarczają na pierwszy kokpit. Nie są jednak ograniczeniem: Twój klucz może mieć dostęp do kilkudziesięciu raportów — od listy lokali i harmonogramów wpłat po cele sprzedażowe i konwersje z kampanii reklamowych. Pełne zestawienie znajdziesz w pliku KATALOG_RAPORTOW.md w paczce startowej oraz w artykule Endpointy Power BI. Listę dostępną akurat dla Twojego klucza pokaże polecenie python3 narzedzia/vox_fetch.py --panel NAZWA_PANELU --lista.
Lejek sprzedaży od klienta do aktu notarialnego jest już w przykładowym kokpicie. Analiza rabatów czy skuteczności doradców wymaga dodatkowych danych i potwierdzenia sposobu liczenia. Jeżeli chcesz zestawić wynik z planem, możesz dołożyć arkusz z celami. Agent powinien najpierw uzgodnić, czy cel i wynik dotyczą tej samej miary, inwestycji oraz okresu.
Siedem pułapek, o których warto wiedzieć
Dane w API są rzetelne, ale kilka ich właściwości łatwo źle odczytać — i agent AI sam z siebie tego nie zauważy. Te siedem punktów warto znać, żeby wiedzieć, o co dopytać.
| Pułapka | Na czym polega i co z tym zrobić |
| Odrzucony filtr wygląda jak poprawny wynik | Literówka w nazwie parametru nie zgłasza błędu — parametr jest po prostu pomijany, a odpowiedź ma status „w porządku”. Jedynym objawem jest większa niż oczekiwana liczba wierszy. Poproś agenta, żeby każdy filtr sprawdził, porównując wynik z filtrem i bez niego. |
| Brak daty początkowej to nie „cała historia” | Część raportów ma własne domyślne zawężenie. Harmonogram płatności bez podanej daty początkowej cofa się tylko o rok — na panelu demonstracyjnym pokazywał w ten sposób 438 zaległych transz zamiast 789. Zakres dat zawsze podawaj jawnie. |
| Pusta lista to nie dowód, że danych nie ma | Może oznaczać zły filtr, brak uprawnień do inwestycji albo domyślne zawężenie raportu. Zanim agent napisze „zero”, powinien potwierdzić to inną drogą. |
| Liczba wierszy to nie liczba obiektów | Umowa, lokal, kontakt i transza to różne jednostki. Jedna umowa może dotyczyć kilku lokali, jeden lokal mieć wiele transz. Zawsze ustalcie, co dokładnie liczy dany wskaźnik. |
| Identyfikatory nie są wspólne dla wszystkich raportów | Ten sam obiekt bywa w różnych raportach oznaczony inaczej, a część raportów nie zwraca identyfikatorów wcale. Nie łącz tabel po samym podobieństwie nazw ani po wartościach ID bez potwierdzenia — błędne połączenie potrafi zdublować kwoty. |
| „Inne” to domyślna wartość słownika, nie kanał | W zestawieniu źródeł klientów „Inne” zwykle znaczy „nie wskazano”, a nie „pozyskany innym kanałem”. Policz tę pozycję osobno i nie umieszczaj jej w rankingu skuteczności. |
| Termin transzy to nie data wpływu pieniędzy | Harmonogram opisuje, kiedy transza miała być zapłacona, a nie kiedy pieniądze wpłynęły. Wskaźnik „zaległości” zbudowany na złym polu pokaże coś zupełnie innego, niż się wydaje. |
Wszystkie te zasady są zapisane w paczce startowej — część w pliku AGENTS.md, część w KATALOG_RAPORTOW.md — więc agent, który przeczyta oba, stosuje je sam. Warto jednak wiedzieć, o co zapytać, gdy liczba wygląda podejrzanie.
Pierwszy dashboard to początek rozmowy
Po otwarciu raportu możesz od razu powiedzieć, co chcesz zmienić. Nie trzeba znać nazw bibliotek, typów wykresów ani języka HTML. Wystarczą konkretne polecenia:
- „Porównaj dwa ostatnie pełne miesiące. Bieżący pokaż osobno, bo jeszcze się nie skończył”.
- „Na górze pokaż przegląd inwestycji, a szczegóły płatności przenieś niżej”.
- „Dodaj tabelę z dokładnymi liczbami pod tym wykresem”.
- „Pokaż, ilu klientom w tym raporcie nie wskazano kanału pozyskania. Pamiętaj, że «Inne» to domyślna wartość słownika, a nie kanał — policz ją osobno i nie umieszczaj w rankingu źródeł”.
- „Przygotuj wersję czytelną na spotkaniu zarządu: większe napisy i krótsze podpisy”.
Możesz również poprosić o wariant „co by było, gdyby”, np. na podstawie celów zapisanych w dodatkowym arkuszu. Taka symulacja powinna wyraźnie oddzielać założenia od rzeczywistych wyników.
Pytaj także o znaczenie liczb
Warto pytać: „Co się zmieniło?”, „Co działa?” i „Co wymaga sprawdzenia?”. Agent może pomóc zarówno przygotować wykres, jak i przyjrzeć się jego wynikom.
Gdy coś budzi wątpliwości, dopytaj: „Z jakich danych i według jakiego wzoru pochodzi ta liczba?”. Przykładowo obecne źródło klienta nie musi oznaczać kanału, któremu należy przypisać sprzedaż. Takie rozróżnienie ma znaczenie, zanim wyciągniesz wnioski o skuteczności marketingu.
Sprawdź raport, zanim na nim oprzesz decyzję
Ładny wykres nie jest jeszcze potwierdzeniem poprawności obliczeń. Pierwszą wersję raportu potraktuj jak propozycję do zweryfikowania:
- Wybierz trzy do pięciu liczb i porównaj je z CRM dla dokładnie tych samych filtrów, inwestycji, okresu i uprawnień.
- Zapytaj o zakres każdej liczby — z którego raportu pochodzi, jaki okres obejmuje i czy filtr faktycznie zadziałał.
- Sprawdź daty brzegowe. Bieżący miesiąc jest niepełny i nie powinien być porównywany z pełnymi miesiącami bez zaznaczenia tego na wykresie.
- Poproś o rozróżnienie między liczbami policzonymi wprost z danych a wyliczonymi na podstawie założeń.
Jeżeli znajdziecie błąd, poproś agenta o zapisanie poprawionej reguły w instrukcji projektu, aby wykorzystał ją przy kolejnym odświeżeniu. Ten plik z czasem staje się najcenniejszą częścią folderu — to w nim zapisują się definicje wskaźników uzgodnione w Twojej firmie.
Jak korzystać z raportu za tydzień?
Wróć do tego samego folderu i poproś agenta o nowe pobranie danych. Nie musisz za każdym razem projektować kokpitu od początku:
Z czasem w folderze powstaje Twój warsztat analityczny: instrukcja, sposób pobierania danych, uzgodnione obliczenia i kolejne wersje raportu. Możesz rozwijać go zgodnie z potrzebami firmy, a rozmowę zaczynać od pytania biznesowego, zamiast od ręcznego układania kolejnej tabeli.
O czym pamiętać przy udostępnianiu danych?
Praca agenta w folderze na komputerze nie oznacza automatycznie, że model przetwarza wszystko lokalnie. Korzystaj z narzędzi i zakresu danych zatwierdzonych w firmie.
Nie wszystkie endpointy API zwracają wyłącznie dane anonimowe. Przy uzyskiwaniu dostępu ustal z supportem zakres odpowiedni do analiz z AI. Do raportu i rozmowy wybieraj potrzebne agregaty; same usunięte nazwiska nie gwarantują anonimowości całego zestawu.
Gotowy HTML zawiera zapisane wyniki. Odbiorca pliku może je odczytać bez logowania do CRM, dlatego udostępniaj go osobom uprawnionym do tych informacji. Klucz API nie trafia do pliku — ale liczby tak.
Jeżeli agent zgłosi błąd dostępu (HTTP 403) już przy pierwszym pobraniu, najczęściej znaczy to jedno z trzech: klucz nie ma włączonej usługi PowerBi, nie ma przypisanej żadnej inwestycji albo nie ma dostępu do tego konkretnego raportu. Warto od razu poprosić agenta o wypisanie listy raportów, które klucz widzi — to jedno polecenie i od razu wiadomo, o co dopytać.
Jeżeli potrzebujesz klucza lub pomocy z dostępem do raportów, zgłoś się do działu supportu voxCRM. Opisz, co chcesz analizować. Dokumentację techniczną przekaż agentowi, a sam skup się na pytaniach, sprawdzaniu odpowiedzi i decyzjach.
pliki dołączone::
