Fiskalizacja sprzedaży online i stacjonarnej przez Fakturownia.pl / Paragony.pl - architektura i integracja
Poniżej znajdziesz odpowiedzi na pytania dotyczące architektury fiskalizacji, scenariuszy awaryjnych, niezawodności usługi oraz integracji z drukarkami fiskalnymi.
Połączenie z drukarką fiskalną
Aplikacja Paragony.pl musi działać na komputerze, który ma jednocześnie połączenie z drukarką fiskalną oraz z Fakturownią. Aktualnie nie ma wersji działającej jako samodzielny serwer sieciowy (bez pośredniczącego komputera) - planowane jest udostępnienie takiej opcji w przyszłości, ale nie jest jeszcze znany termin.
W aplikacji możesz włączyć:
- autostart przy uruchamianiu systemu,
- automatyczne łączenie z drukarką po starcie,
- automatyczne ponawianie połączenia po rozłączeniu drukarki.
Zobacz artykuł: Autostart i automatyczne łączenie Paragony.pl z drukarką fiskalną
Aplikacja może działać w tle (zminimalizowana w trayu), ale musi być uruchomiona, aby odbierać zlecenia fiskalizacji z Fakturowni.
Jeśli sprzedaż działa całą dobę, komputer powinien być włączony przez całą dobę. Wyłączenie komputera w nocy jest do omówienia z księgowością - ważne jest, żeby raport dobowy był generowany na koniec każdego dnia sprzedaży, a raport za ostatni dzień miesiąca musiał zostać wygenerowany w tym samym miesiącu (najlepiej o 23:59 ostatniego dnia). Generowanie raportów dobowych można zautomatyzować.
Scenariusze awaryjne
Kolejka fiskalizacji i brak połączenia
Paragony z automatyczną fiskalizacją trafiają do kolejki, która nie ma limitu. Aplikacja Paragony.pl odpytuje kolejkę co 10 sekund i pobiera do 20 paragonów jednocześnie. Jeśli aplikacja przez jakiś czas nie działa, paragony czekają w kolejce - po ponownym uruchomieniu aplikacja zaczyna je pobierać i fiskalizować.
Kiedy potrzebna jest ręczna interwencja
Ręczna interwencja jest wymagana tylko przy błędach fiskalizacji. Najczęstsze przyczyny:
- brak adresu e-mail nabywcy (wymagany do e-paragonu),
- tzw. schodek podatkowy - blokada produktu przez drukarkę (zmiana nazwy produktu rozwiązuje problem; warto włączyć opcję wstawiania oznaczenia literowego stawki VAT w nazwie produktu),
- rozłączenie drukarki,
- pozycja zerowa lub ujemna na paragonie,
- waluta paragonu inna niż PLN.
Paragony z błędem nie są automatycznie ponawiane, bo mogą wymagać korekty danych.
Czas oczekiwania paragonu na fiskalizację
Nie ma ograniczeń technicznych co do czasu oczekiwania. Ważna jest kwestia formalna: sprzedaż z danego miesiąca musi być zafiskalizowana i ujęta w raporcie dobowym najpóźniej w ostatnim dniu tego miesiąca. Jeśli raport dobowy za ostatni dzień miesiąca nie zostanie wygenerowany w tym dniu, sprzedaż trafi do raportu kolejnego miesiąca.
Utrata połączenia z CRK (drukarka online)
Drukarki fiskalne online posiadają mechanizmy buforowania danych i dostarczają je do CRK po odzyskaniu połączenia. W przypadku e-paragonów drukarka najpierw próbuje wysłać plik JWS na serwer - jeśli to się nie powiedzie, drukuje paragon papierowo i ponawia wysyłkę (szczegóły zależą od modelu drukarki). Szczegółowych informacji o buforowaniu danych dla CRK może udzielić serwisant drukarki.
Monitoring i alerty
Fakturownia.pl ani Paragony.pl nie posiadają wbudowanego mechanizmu alertowania o błędach fiskalizacji ani o zatrzymaniu aplikacji. Możliwe jest jednak samodzielne monitorowanie:
- paragony w Fakturowni otrzymują czytelne statusy fiskalizacji - można je odpytywać po ID lub cyklicznie sprawdzać (np. co godzinę) czy nie pojawiły się paragony z błędem lub czekające w kolejce,
- można skonfigurować webhook invoice:update, który m.in. zwraca URL e-paragonu - brak tego URL po określonym czasie może sygnalizować problem,
- po otrzymaniu webhooka status fiskalizacji można sprawdzić pobierając paragon po ID i sprawdzając pole fiscal_status; wartość “error” oznacza błąd fiskalizacji.
Statusy fiskalizacji paragonu:
- to_print, to_print_f, to_print_q - paragon oczekuje w kolejce,
- printing - paragon pobrany z kolejki, przesyłany do drukarki,
- error - błąd fiskalizacji,
- printed - fiskalizacja udana, paragon papierowy,
- er_printed - fiskalizacja udana, wystawiono e-paragon,
- er_fail - fiskalizacja udana, drukarka ponawia wysyłkę e-paragonu na serwer; przy pierwszej nieudanej próbie drukowany jest paragon papierowy,
- er_fatal - fiskalizacja udana, ale e-paragon nie zostanie wystawiony (drukarka przekroczyła liczbę prób wysyłki - domyślnie co godzinę przez tydzień); paragon był drukowany papierowo przy pierwszej nieudanej próbie.
Niezawodność usługi
Fakturownia działa na wielu serwerach w różnych lokalizacjach. Baza danych ma gorącą kopię z automatycznym przełączaniem w razie awarii, a backupy tworzone są co 5 minut i przechowywane w różnych lokalizacjach i regionach. Przerwy w działaniu serwisu zdarzają się sporadycznie.
Wsparcie techniczne dostępne jest od poniedziałku do piątku w godzinach 8:00-17:00. Nie publikujemy formalnych poziomów SLA.
Jeśli przesłanie żądania API do Fakturowni nie powiedzie się z powodu awarii, żądanie należy ponowić - dokument nie zostanie wtedy utworzony. Paragony już umieszczone w kolejce, które nie zostały zafiskalizowane z powodu chwilowej niedostępności (np. brak internetu na komputerze), zostaną pobrane przez aplikację przy kolejnych odpytaniach. Paragony z błędem fiskalizacji (np. rozłączenie drukarki) nie są ponawiane automatycznie - wymagają ręcznego zlecenia ponownej fiskalizacji z poziomu interfejsu lub przez API.
API Fakturowni obsługuje do 1000 zapytań na minutę z jednego adresu IP. Fiskalizacja jednego e-paragonu trwa zazwyczaj od 1,5 do 4 sekund, maksymalnie do około 9 sekund, zależnie od liczby pozycji i jakości połączenia internetowego.
Jedna drukarka dla dwóch kanałów sprzedaży
Jedna drukarka fiskalna może obsługiwać zarówno sprzedaż online, jak i stacjonarną. Trzeba jednak wziąć pod uwagę jeden praktyczny aspekt: jeśli w kolejce czekają paragony ze sprzedaży online, zlecenie paragonu papierowego ze sprzedaży stacjonarnej trafi na koniec tej kolejki. Klient przy kasie musiałby poczekać, aż poprzednie zlecenia zostaną obsłużone.
Przy sprzedaży stacjonarnej wyłącznie w formie e-paragonów problem kolejkowania praktycznie nie istnieje - wszystkie zlecenia obsługiwane są jednakowo.
Aplikacja odpytuje kolejkę co 10 sekund, więc maksymalne opóźnienie nowego zlecenia wynosi około 10 sekund.
Wspierane drukarki fiskalne
Pełna lista wspieranych modeli dostępna jest w dokumentacji: E-Paragony w Fakturowni - czego potrzebujesz?.
Zarówno Novitus POINT, jak i Posnet Thermal HD są obsługiwane i używane przez klientów. Kilka praktycznych różnic między markami:
- Na urządzeniu Posnet Thermal XL2 Online zarejestrowano do 45 e-paragonów na minutę - cała seria Thermal jest wydajna i sprawdza się przy dużych wolumenach. Dla bardzo dużych obciążeń serwisanci drukarek rekomendują model Thermal HX.
- Novitus POINT to również dobry wybór do tego scenariusza.
- Różnica w obsłudze niepowodzenia wysyłki e-paragonu: Posnet ponawia próbę przez 30 sekund, potem co godzinę; Novitus ponawia częściej. Na Posnecie przy niepowodzeniu drukarka zawsze drukuje paragon papierowy i nie można tego wyłączyć. Na Novitusie można ustawić tryb “nie drukuj i wyślij później”. Nie jest to podwójna fiskalizacja - to dwa różne sposoby obsługi awaryjnej.
Z Fakturowni korzystają firmy wystawiające od kilkuset do kilkudziesięciu tysięcy e-paragonów miesięcznie na jednej drukarce.
Fiskalizacja przez API
Nie trzeba wysyłać osobnych żądań do fiskalizacji. W ustawieniach konta w Fakturowni można włączyć:
- automatyczną fiskalizację paragonów tworzonych przez API,
- automatyczną wysyłkę e-paragonu e-mailem.
W ustawieniach drukarki fiskalnej należy ustawić domyślny sposób wydruku na e-paragon.
Jeśli wolisz sterować fiskalizacją ręcznie z własnego systemu, jest taka możliwość przez API.
Dokumentacja techniczna dostępna jest na GitHub: