Dokumentacja Szambook

Ta część dokumentacji opisuje korzystanie z aplikacji Szambook z perspektywy użytkowników biznesowych.

Dla kogo jest ta dokumentacja

• Klienci składający zamówienia.
• Operatorzy obsługujący i realizujący zamówienia.
• Managerowie nadzorujący ofertę i proces operacyjny.
• Administratorzy zarządzający użytkownikami, rolami i danymi demonstracyjnymi.

Spis treści

• Pierwsze kroki
• Konta i logowanie
• Rejestracja użytkownika
• Oferty
• Programy lojalnościowe
• Zamówienia
• Panel administratora
• FAQ

Jak rozwijać tę dokumentację

Każda strona powinna odpowiadać na jedno praktyczne pytanie użytkownika, np. "Jak złożyć zamówienie?" albo "Jak administrator blokuje konto?". Gdy aplikacja dostanie nowy ekran lub nowy proces, dodaj osobną sekcję albo nowy plik w tym katalogu.

Cel aplikacji

Szambook wspiera proces zamawiania, obsługi i rozliczania usług wywozu szamba. Aplikacja łączy prostą ścieżkę składania zamówienia przez klienta z panelem operacyjnym dla zespołu.

Podstawowe role

Typowy przebieg pracy

1. Użytkownik wybiera ofertę lub składa szybkie zamówienie ze strony głównej.
2. Aplikacja zbiera dane kontaktowe i adresowe.
3. Zamówienie trafia do systemu.
4. Operator lub manager planuje i obsługuje realizację.
5. Po wykonaniu usługi zamówienie zostaje oznaczone jako zrealizowane.

Gdzie szukać pomocy

• Problemy z logowaniem: Konta i logowanie.
• Pytania o zamówienia: Zamówienia.
• Zadania administracyjne: Panel administratora.

Dostępne metody logowania

Szambook obsługuje lokalne logowanie przez telefon/SMS oraz lokalne logowanie przez email. Ekrany logowania mogą też pokazywać przyciski Google i Facebook. Jeśli zewnętrzny dostawca nie jest skonfigurowany, przycisk pozostaje niedostępny.

Rejestracja

Użytkownik może utworzyć konto, podając numer telefonu albo adres email, zależnie od wybranej ścieżki. Domyślna ścieżka korzysta z numeru telefonu i jednorazowego kodu SMS. Szczegółowy opis znajduje się w dokumencie Rejestracja użytkownika.

Weryfikacja OTP

Kod OTP potwierdza dostęp użytkownika do podanego kanału kontaktu. Jeżeli kod wygasł albo nie dotarł, użytkownik może poprosić o ponowne wysłanie.

Ustawienia konta

Zalogowany użytkownik może przejść do swoich ustawień i zaktualizować dane kontaktowe oraz adresowe. Administrator może zarządzać danymi użytkowników w panelu administracyjnym.

Konto zablokowane

Jeżeli konto zostało zablokowane, użytkownik zobaczy ekran blokady. Odblokowanie konta wykonuje administrator.

Problem biznesowy

Firma odbierająca nieczystości potrzebuje szybkiego sposobu zakładania kont klientów bez długiego formularza i bez ręcznej obsługi przez biuro. Klient często chce po prostu złożyć zlecenie, potwierdzić numer telefonu i wrócić do swoich spraw.

Jak Szambook rozwiązuje ten problem

Domyślna rejestracja w Szambook odbywa się przez numer telefonu i jednorazowe hasło SMS. Dzięki temu konto można utworzyć bez ustawiania hasła na starcie, a firma od razu ma potwierdzony kanał kontaktu do klienta.

Opcjonalnie użytkownik może zarejestrować się zwykłym adresem email. System pokazuje również opcje Google i Facebook, ale te metody wymagają konfiguracji dostawców zewnętrznych. Dopóki konfiguracja nie zostanie uzupełniona, logowanie i rejestracja przez Google/Facebook nie powinny być traktowane jako działające ścieżki produkcyjne.

Domyślna ścieżka: numer telefonu i kod SMS

1. Użytkownik wybiera rejestrację.
2. System domyślnie prosi o numer telefonu.
3. Użytkownik wpisuje numer telefonu i wysyła formularz.
4. System wysyła jednorazowy kod SMS.
5. Użytkownik wpisuje kod na ekranie weryfikacji.
6. System tworzy konto i loguje użytkownika.

Korzyść dla firmy

Rejestracja przez telefon zmniejsza tarcie przy pierwszym kontakcie z klientem. Numer telefonu jest naturalnym kanałem dla potwierdzeń, przypomnień i kontaktu kierowcy przed odbiorem, dlatego firma szybciej przechodzi od zgłoszenia do realizacji.

Rejestracja przez email

Rejestracja przez email jest dostępna jako alternatywa dla użytkowników, którzy wolą używać poczty elektronicznej. Przepływ pozostaje podobny: użytkownik podaje email, system wysyła kod lub link weryfikacyjny, a konto zostaje utworzone po potwierdzeniu.

Google i Facebook

Przyciski Google i Facebook mogą być widoczne na ekranie konta, ale wymagają konfiguracji po stronie aplikacji i dostawcy:

• Google wymaga ClientId i ClientSecret.
• Facebook wymaga AppId i AppSecret.
• Adresy callback muszą być zarejestrowane u dostawcy.

Jeżeli konfiguracja nie jest gotowa, użytkownik powinien korzystać z rejestracji telefonem albo emailem.

Komunikaty i sytuacje wyjątkowe

Rekomendowana komunikacja z klientem

W materiałach sprzedażowych warto podkreślać, że klient może rozpocząć współpracę z firmą bez rozmowy telefonicznej z biurem. System prowadzi go przez rejestrację, potwierdza kontakt i pozwala szybciej złożyć zamówienie.

Czym jest oferta

Oferta opisuje usługę dostępną w systemie, np. wariant wywozu szamba. Oferta może być widoczna dla klientów albo ukryta przed standardowymi użytkownikami.

Przeglądanie ofert

Użytkownik widzi aktywne oferty dostępne do zamówienia. Role administracyjne mogą widzieć szerszy zestaw ofert, w tym pozycje przygotowywane lub nieaktywne.

Na stronie głównej system może dodatkowo wyświetlać informację o aktywnych programach lojalnościowych. Jeżeli administrator albo manager włączy rabaty, klient zobaczy przy cenniku komunikat o zniżce dla klientów z umową albo o rabacie przy co N-tym wywozie.

Tworzenie i edycja ofert

Tworzenie oraz edycja ofert wymaga odpowiednich uprawnień. Zwykle wykonuje je administrator lub manager.

Dobre praktyki opisu oferty

• Nazwa powinna jasno mówić, czego dotyczy usługa.
• Cena i zakres usługi powinny być zrozumiałe dla klienta.
• Nieaktywne lub testowe oferty nie powinny być widoczne dla zwykłych użytkowników.

Składanie zamówienia

Użytkownik może złożyć zamówienie z poziomu strony głównej albo przez wybór konkretnej oferty. Formularz zbiera dane kontaktowe, adresowe i informacje potrzebne do realizacji usługi.

Jeżeli dla zalogowanego klienta działa program lojalnościowy, system uwzględnia rabat podczas checkoutu. Dotyczy to programu stałego dla klientów z podpisaną umową albo programu częstotliwościowego dla powracających klientów.

Historia zamówień

Zalogowany użytkownik widzi swoje zamówienia. Role operacyjne i zarządcze mogą widzieć zamówienia zgodnie ze swoimi uprawnieniami.

Statusy zamówień

Status zamówienia opisuje etap procesu. Dokumentacja statusów powinna być rozszerzana razem ze zmianami w OrderStatus w kodzie aplikacji.

Realizacja zamówienia

Operator lub osoba z uprawnieniem do edycji zamówień może aktualizować dane realizacji. Po wykonaniu usługi zamówienie powinno zostać oznaczone jako zrealizowane.

Płatność

Proces checkout może przekierowywać użytkownika przez płatność oraz odbierać powiadomienia płatnicze. Szczegóły integracji technicznej są opisane w integrations.

Rabaty lojalnościowe w zamówieniu

System oblicza rabat automatycznie w chwili finalizacji zamówienia. W zamówieniu zapisywana jest końcowa kwota, procent rabatu, źródło rabatu oraz cena pierwotna przed obniżką.

Jeżeli klient ma podpisaną umowę na regularny wywóz i jednocześnie kwalifikuje się do rabatu częstotliwościowego, pierwszeństwo ma rabat wynikający z umowy.

Automatyczna faktura po realizacji

Szambook wspiera automatyczną księgowość dla firm realizujących wywóz nieczystości. Po oznaczeniu zamówienia jako wykonanego system może utworzyć fakturę w popularnej platformie księgowej fakturownia.pl. Dzięki temu manager nie musi ręcznie przepisywać danych klienta, adresu realizacji, kwoty usługi ani informacji o płatności.

Ta funkcjonalność pomaga uporządkować rozliczenia po każdym wywozie. Firma może podpiąć elektroniczną kasę fiskalną do swojego procesu księgowego albo ją pominąć, jeżeli każdy klient otrzymuje fakturę. Integracja z fakturownia.pl pozwala traktować zakończenie usługi jako naturalny moment wygenerowania dokumentu sprzedaży.

W praktyce operator lub manager zatwierdza wykonanie usługi w zamówieniu. System tworzy fakturę na podstawie danych z zamówienia i zapisuje link do dokumentu przy zamówieniu. Jeżeli w danych klienta znajduje się adres e-mail, faktura może zostać wysłana do klienta przez fakturownia.pl. Dla zamówień założonych tylko na numer telefonu firma powinna uzupełnić adres e-mail klienta albo udostępnić fakturę innym kanałem operacyjnym.

Korzyść biznesowa jest prosta: mniej pracy administracyjnej po każdej realizacji, mniejsze ryzyko pomyłek w danych faktury i szybsze przekazanie dokumentu klientowi.

Zakres panelu

Panel administratora służy do utrzymania systemu i obsługi danych pomocniczych.

Najważniejsze zadania

• Zarządzanie użytkownikami.
• Konfiguracja programów lojalnościowych.
• Nadawanie i odbieranie ról.
• Zarządzanie uprawnieniami użytkowników.
• Blokowanie i odblokowywanie kont.
• Usuwanie kont użytkowników.
• Wgrywanie i usuwanie danych demonstracyjnych.
• Przeglądanie i pobieranie logów.

Programy lojalnościowe

Administrator lub manager może otworzyć ekran programów lojalnościowych i skonfigurować dwa automatyczne rabaty:

• Program częstotliwościowy, czyli zniżkę co N-ty zakończony wywóz klienta.
• Program stały, czyli rabat dla klientów z podpisaną umową na regularny wywóz.

Rabat stały ma priorytet nad programem częstotliwościowym. Jeżeli klient spełnia oba warunki, system stosuje tylko rabat wynikający z umowy.

Flaga umowy u klienta

Warunek dla programu stałego jest zapisany na koncie użytkownika jako informacja o podpisanej umowie na regularny wywóz. Administrator lub manager może ustawić tę flagę podczas edycji danych użytkownika.

Role systemowe

Dane demonstracyjne

Administrator może załadować dane demonstracyjne do testów i prezentacji. Po zakończeniu prezentacji dane demonstracyjne można usunąć z panelu.

Zasady bezpieczeństwa

• Nie udostępniaj konta administratora innym osobom.
• Po prezentacji usuń dane demonstracyjne, jeżeli środowisko ma dalej służyć do pracy.
• Realne sekrety konfiguracyjne przechowuj poza repozytorium.

Nie mogę się zalogować. Co zrobić?

Sprawdź, czy wybrana została właściwa metoda logowania: telefon/SMS albo email. Jeżeli używasz OTP, poproś o ponowne wysłanie kodu.

Nie widzę oferty, którą widzi administrator.

Standardowy użytkownik widzi tylko oferty przeznaczone do składania zamówień. Oferty robocze lub nieaktywne mogą być widoczne tylko dla ról administracyjnych.

Kto może zmienić status zamówienia?

Zmiana statusu zależy od uprawnień. Operacje na zamówieniach wykonują role operacyjne lub administracyjne.

Gdzie są dane testowe?

Dane demonstracyjne są zarządzane w panelu administratora. Ich dokładna lista jest opisana w głównym pliku README.

Jak zgłosić brak w dokumentacji?

Dodaj wpis do właściwego pliku w docs/user/pl albo utwórz nową stronę, jeśli temat jest większy.

Cel funkcji

Programy lojalnościowe pozwalają automatycznie obniżać cenę wywozu dla wybranych klientów. Funkcja działa bez ręcznej zmiany ceny w zamówieniu, dlatego firma może nagradzać stałych klientów bez dodatkowej pracy operatora.

Dla firmy asenizacyjnej oznacza to prostsze utrzymanie klientów długoterminowych. Manager ustawia reguły raz, a system sam rozpoznaje, czy klientowi przysługuje rabat przy składaniu zamówienia.

Dostępne programy

Program częstotliwościowy

Ten program przyznaje zniżkę co N-ty zakończony wywóz klienta. Wartość N oraz procent rabatu ustawia administrator albo manager. Program sprawdza historię zakończonych zamówień i pomaga zachęcać klientów do regularnych powrotów.

Klient nie musi pamiętać o kodzie rabatowym. System sam liczy, który kolejny wywóz kwalifikuje się do rabatu, i pokazuje obniżkę w checkoutcie, kiedy przychodzi odpowiedni moment.

Stały program dla klientów z umową

Stały program daje rabat klientom, którzy mają podpisaną umowę na regularny wywóz. Warunek jest zapisany na koncie użytkownika jako flaga Podpisana umowa na stały wywóz.

To rozwiązanie jest przeznaczone dla klientów długoterminowych, którzy korzystają z usług cyklicznie na podstawie stałej umowy. Klient nie musi wpisywać kodu rabatowego ani prosić obsługi o indywidualną cenę. Jeżeli spełnia warunki programu, zniżka nalicza się automatycznie na każdy wywóz.

Zasada priorytetu

Jeżeli klient spełnia warunki obu programów, system stosuje tylko program stały. Rabat z umowy jest sprawdzany przed rabatem częstotliwościowym.

Przykład: jeżeli klient z umową kwalifikuje się do stałego rabatu 10% i jednocześnie wypada mu rabat częstotliwościowy 5%, system zastosuje rabat 10% z umowy.

Konfiguracja programu częstotliwościowego

Program częstotliwościowy konfiguruje użytkownik z rolą Admin albo Manager. Na ekranie programów lojalnościowych dostępne są:

• przełącznik ON/OFF, który włącza lub wyłącza program,
• pole Co ile wywozów przysługuje zniżka, które określa częstotliwość rabatu,
• pole Wysokość zniżki procentowej, które określa procent obniżki dla wywozu objętego promocją.

Gdy program jest włączony, pola konfiguracji są aktywne, zniżki mogą być naliczane automatycznie, a informacja o promocji może być widoczna na stronie głównej. Zalogowany użytkownik może też widzieć w panelu informację o przyszłej zniżce.

Gdy program jest wyłączony, pola Co ile wywozów przysługuje zniżka oraz Wysokość zniżki procentowej są zablokowane, rabaty nie są naliczane, a informacje promocyjne nie są pokazywane klientom. Zapisane wartości pozostają w systemie i mogą zostać ponownie użyte po włączeniu programu.

Co ile wywozów przysługuje zniżka

Parametr Co ile wywozów przysługuje zniżka określa, co który wywóz klienta będzie objęty rabatem.

Wartość musi być liczbą całkowitą równą 0 lub większą. Wartość 0 oznacza, że częstotliwościowy rabat nie daje realnej zniżki, nawet jeśli program jest włączony.

Konfiguracja stałego programu

Stały program lojalnościowy konfiguruje użytkownik z rolą Admin albo Manager. Na ekranie programów lojalnościowych dostępne są:

• przełącznik ON/OFF, który włącza lub wyłącza program,
• pole Wysokość stałej zniżki procentowej, które określa rabat dla klienta z aktywną umową.

Gdy program jest włączony, pole wysokości zniżki jest aktywne, a system może naliczać rabat kwalifikującym się klientom. Gdy program jest wyłączony, pole zniżki jest zablokowane, rabaty nie są naliczane, a komunikaty o stałej zniżce nie powinny być pokazywane klientowi.

Wyłączenie programu nie usuwa informacji o podpisanej umowie z kont klientów. Dzięki temu manager może czasowo zatrzymać naliczanie rabatów i później ponownie włączyć program bez ponownego oznaczania klientów.

Wysokość stałej zniżki

Wysokość stałej zniżki procentowej określa, o ile tańszy będzie każdy wywóz klienta z podpisaną umową. Dozwolony zakres to 0-100%.

Przykład: jeżeli stała zniżka wynosi 10%, a standardowa cena wywozu to 300 zł, klient z podpisaną umową zapłaci 270 zł.

Flaga umowy przy kliencie

Admin albo manager może oznaczyć klienta jako osobę z podpisaną umową na stały wywóz. Flaga jest widoczna przy użytkowniku, na przykład na liście użytkowników, w szczegółach konta, w edycji danych klienta albo podczas obsługi zamówienia.

W praktyce oznaczenie ma dwa stany:

Dla nowego klienta domyślnym stanem powinno być NIE. Zmianę flagi może wykonać tylko admin albo manager.

Kiedy system nalicza stały rabat

Stały rabat jest naliczany automatycznie, gdy wszystkie warunki są spełnione:

• stały program lojalnościowy jest włączony,
• wysokość stałej zniżki jest większa niż 0%,
• klient ma ustawioną flagę Podpisana umowa na stały wywóz,
• zamówienie jest składane dla tego klienta.

Jeżeli którykolwiek warunek nie jest spełniony, stały rabat nie zostanie naliczony.

Gdzie klient widzi informację o rabacie

• Na stronie głównej przy cenniku może pojawić się komunikat o aktywnych promocjach.
• W checkoutcie zalogowany użytkownik widzi procent rabatu, jeżeli kwalifikuje się do zniżki.
• W zapisanym zamówieniu system przechowuje cenę przed rabatem i po rabacie.
• Zalogowany klient z podpisaną umową powinien widzieć w swoim panelu informację o stałej zniżce, np. Masz podpisaną umowę na stały wywóz. Każdy Twój wywóz jest tańszy o 10%.

Informacja o promocji na stronie głównej

Sekcja promocyjna na stronie głównej może informować wszystkich odwiedzających, także niezalogowanych, że firma nagradza regularne zamówienia. To pomaga pokazać wartość korzystania z platformy zamiast jednorazowego kontaktu telefonicznego.

Dla programu częstotliwościowego sekcja jest widoczna, gdy:

• program częstotliwościowy jest włączony,
• parametr Co ile wywozów przysługuje zniżka jest większy od 0,
• parametr Wysokość zniżki procentowej jest większy od 0.

Przykładowa treść:

Program lojalnościowy dla stałych klientów

Korzystasz regularnie z wywozu szamba? W szambook.pl automatycznie nagradzamy stałych klientów. Co 3. wywóz otrzymasz automatyczną zniżkę w wysokości 10%. Nie musisz wpisywać żadnego kodu rabatowego.

Jeżeli program jest wyłączony, wartość częstotliwości wynosi 0 albo wysokość rabatu wynosi 0%, sekcja promocyjna nie powinna być wyświetlana dla tego programu.

Informacja w panelu zalogowanego użytkownika

Zalogowany użytkownik powinien widzieć w swoim panelu informację o tym, kiedy będzie przysługiwać mu kolejna zniżka i jaka będzie jej wysokość. Komunikat zależy od historii zakończonych wywozów klienta oraz aktualnej konfiguracji programu.

Przykłady komunikatów:

• Twój 3. wywóz będzie tańszy o 10%.
• Do kolejnej zniżki pozostały Ci 2 wywozy. Twój kolejny rabat wyniesie 10%.
• Ten wywóz jest objęty programem lojalnościowym. Otrzymujesz 10% zniżki.

Komunikat o przyszłej zniżce jest widoczny, gdy użytkownik jest zalogowany, program częstotliwościowy jest włączony, częstotliwość jest większa od 0, a wysokość rabatu jest większa od 0%.

Przykłady programu częstotliwościowego

Kto zarządza ustawieniami

Programy lojalnościowe konfiguruje administrator albo manager. Ustawienia obejmują:

• włączenie lub wyłączenie programu,
• wysokość zniżki procentowej,
• wartość N dla programu częstotliwościowego,
• flagę podpisanej umowy na koncie klienta.

Ważne ograniczenia

• Rabat jest liczony automatycznie tylko dla zalogowanego użytkownika, dla którego system może sprawdzić historię zamówień albo flagę umowy.
• Program stały wymaga poprawnie ustawionej informacji o podpisanej umowie na koncie klienta.
• Program częstotliwościowy wymaga poprawnej historii zakończonych wywozów klienta.
• Zmiana wysokości rabatu wpływa na kolejne zamówienia. Zamówienia już zapisane zachowują rabat, który został naliczony w chwili ich utworzenia.