API — wystawianie paragonów z własnego systemu

Jak Twój własny system (sklep, skrypt, integracja) może automatycznie wystawiać paragony na drukarce i pobierać gotowe pliki PDF.

1. Po co to jest

   Aplikacja udostępnia interfejs dla programistów (tzw. API), dzięki któremu Twój własny system (sklep internetowy, skrypt, integracja firmowa) może automatycznie wystawiać paragony na drukarce fiskalnej i pobierać gotowe pliki PDF z paragonem.

   To dodatkowy kanał — niezależny od standardowych integracji ze sklepami (Sellasist, Baselinker) i programami magazynowymi (Subiekt, Nexo, Optima). Paragony wystawione tym kanałem NIE są wgrywane z powrotem do żadnego sklepu — pliki PDF pobierasz bezpośrednio z aplikacji.

2. Działa tylko w wersji w tle (usługa)

   Aplikację można zainstalować w dwóch trybach:

   • Wersja w tle (usługa) — aplikacja działa w tle, a ustawienia otwierasz w przeglądarce pod adresem http://localhost:5050. W tym trybie API jest dostępne.
   • Wersja okienkowa — po uruchomieniu otwiera się okno aplikacji na ekranie. W tym trybie API nie działa.

   Jeśli używasz wersji okienkowej i chcesz korzystać z API — przeinstaluj aplikację, wybierając w instalatorze wersję w tle.

3. Dostępne tylko lokalnie

   Aplikacja jest zainstalowana lokalnie na Twoim komputerze. Adresy API zaczynają się od http://localhost:5050/api/receipts — są dostępne tylko z tego samego komputera. Aplikacja nie jest dostępna z internetu.

   Jeśli chcesz wystawiać paragony z innego komputera w sieci lokalnej (np. ze stanowiska kasowego), odblokuj port aplikacji (domyślnie 5050) w zaporze Windows i używaj adresu IP komputera z drukarką, np. http://192.168.1.50:5050/api/receipts.

   Jeśli zmieniłeś port aplikacji, użyj swojego. Aplikacja nie powinna być wystawiona do internetu bez świadomej konfiguracji zabezpieczeń.

4. Włączenie — domyślnie wyłączone

   API jest domyślnie wyłączone. Żeby je włączyć, w ustawieniach przejdź do sekcji 🧩 API (karta „API — wystawianie paragonów z własnego systemu”) i włącz przełącznik Włącz API. Dopóki jest wyłączone, zapytania z zewnętrznych systemów będą odrzucane.

   Domyślnie wyłączamy, żeby nikt z sieci lokalnej (np. inny pracownik, ktoś z tej samej sieci Wi-Fi) nie mógł przypadkowo wystawiać paragonów na Twojej drukarce. Włącz tylko, jeśli świadomie integrujesz API z własnym systemem.

   

   Sekcja API — przełącznik Włącz API.

5. Interaktywna dokumentacja API

   W menu po lewej jest pozycja API. Po włączeniu API (w wersji w tle) klikasz Otwórz dokumentację API — w przeglądarce otworzy się interaktywna dokumentacja: lista wszystkich operacji z opisami pól, przykładami i możliwością wysłania zapytania wprost ze strony, bez żadnych dodatkowych narzędzi.

   Dokumentacja zawsze pokazuje aktualną wersję API dla zainstalowanej u Ciebie wersji aplikacji. W wersji okienkowej przycisk jest nieaktywny.

   

   Strona API — Otwórz dokumentację API.

6. Co API potrafi

   Najważniejsze operacje (pod adresem /api/receipts):

   • Wystaw nowy paragon — wysyłasz dane (pozycje, ceny, opcjonalnie inną drukarkę), aplikacja drukuje paragon natychmiast.
   • Lista ostatnich paragonów — pobierz historię wystawionych paragonów.
   • Szczegóły paragonu — sprawdź status konkretnego paragonu po jego numerze.
   • Pobierz graficzny PDF paragonu (/paragon.pdf) — wizualizacja, którą można przesłać klientowi.
   • Pobierz cyfrowy dowód fiskalny (/jws.pdf lub surowy /jws) — techniczny plik potwierdzający fiskalizację.
   • Pobierz surową odpowiedź drukarki (/printer-response) — przydatne do diagnostyki.

   Po wysłaniu polecenia drukarka drukuje paragon natychmiast, ale wygenerowanie cyfrowego eParagonu (PDF) trwa około 1–2 sekund. Pobierając szczegóły paragonu możesz sprawdzić, czy eParagon jest już gotowy (zanim będzie, pobranie PDF zwróci „brak”).

7. Możliwość wskazania innej drukarki

   W zapytaniu o wystawienie paragonu możesz opcjonalnie wskazać inną drukarkę niż ta ustawiona w aplikacji (podając jej model, adres IP i port). Paragon zostanie wystawiony na wskazanej drukarce, bez zmiany konfiguracji aplikacji.

   Przydatne, gdy:

   • testujesz nową drukarkę bez zmiany ustawień produkcyjnych,
   • obsługujesz kilka punktów sprzedaży z różnymi drukarkami z jednego systemu,
   • masz drukarkę awaryjną i chcesz na nią przerzucić wystawienie.

   Jeśli nie wskażesz drukarki, paragon idzie na drukarkę ustawioną w aplikacji.

8. Paragony z API nie trafiają do sklepu

   Paragony wystawione przez API są zapisywane lokalnie w aplikacji (z oznaczeniem „API”), ale nie są wgrywane z powrotem do żadnego sklepu (Sellasist, Baselinker). Dzieje się tak, bo numer zamówienia podany w API może być dowolny (np. tekst z literami) i może nie istnieć w żadnym sklepie.

   Plik PDF z paragonem oraz cyfrowy dowód fiskalny pobierasz wyłącznie przez API — z poziomu Twojego systemu.