Do serwisu można wysyłać dowolne polecenia sterujące, jednak dla wygody użytkowania najczęściej używane funkcje (jak np. wydruk paragonów) mają dedykowane restpointy.
Pojedynczy Paragon
Aby wydrukować paragon, wystarczy wysłać poniższy request z konsoli (lub z dowolnego programu do wysyłania requestów HTTP, np Fiddler lub Postman).
|
1 2 3 4 5 6 7 8 9 |
curl -XPOST "http://localhost:3050/paragon" -H 'Content-Type: application/json' -d'{ "lines" : [ { "na": "Towar 1", "il": 1.0, "vt": 0,"pr": 2350}, { "na": "Towar 2", "il": 1.0, "vt": 0,"pr": 1150} ], "summary" : { "to": 3500 } }' |
Polecenie wydrukuje poniższy paragon na drukarce:
A w odpowiedzi zwróci przykładowy response:
|
1 |
{"ok":true,"code":-1,"bn":"10","hn":"120","took":2957,"message":"","ts":1685975291660,"tsend":1685975294617} |
Opis poszczególnych pól znajduje się w sekcji “STATUS WYDRUKU PARAGONU” poniżej, a poniżej krótki materiał prezentujący jak wysłać request za pomocą panelu swagger:
Paczka dystrybucyjna zawiera katalog docs/ a w nim pliki HTML z przykładowymi requestami do serwisu.
W poprzednim przykładzie fiskalizacja nastąpiła z użyciem stawki 23%, czyli zazwyczaj stawki oznaczonej literą “A“, będącej pierwszą stawką zdefiniowaną w drukarce (parametr “vt” ma wartość 0). W praktyce nie zawsze wiadomo który indeks stawki odpowiada jakiej stawce VAT. Aby nie odpytywać za każdym razem drukarki o stawki VAT lub tym bardziej nie trzymać listy stawek w kodzie tworzonej przez nas aplikacji, PosnetServer pozwala wygodnie przekazać stawkę VAT w formacie “23,00”, “8,00” lub “A”, “B” itd. W strukturze “lines” możemy używać jednego z trzech parametrów: “vt“, “vtp” lub “vtn” do określenia stawki VAT, w zależności od naszej wygody. Należy bezwzględnie unikać przekazywania wszystkich trzech parametrów lub dwóch z nich, gdyż w przyszłości (w nowych wersjach PosnetServer) może to spowodować, że towary będą fiskalizowane pod inną stawką VAT niż oczekiwana.
Alternatywne requesty, które spowodują dokładnie taki sam wydruk jak w poprzednim przykładzie:
|
1 2 3 4 5 6 7 8 9 |
curl -XPOST "http://localhost:3050/paragon" -H 'Content-Type: application/json' -d'{ "lines" : [ { "na": "Towar 1", "il": 1.0, "vtp": "23,00","pr": 2350}, { "na": "Towar 2", "il": 1.0, "vtp": "23,00","pr": 1150} ], "summary" : { "to": 3500 } }' |
|
1 2 3 4 5 6 7 8 9 |
curl -XPOST "http://localhost:3050/paragon" -H 'Content-Type: application/json' -d'{ "lines" : [ { "na": "Towar 1", "il": 1.0, "vtn": "A","pr": 2350}, { "na": "Towar 2", "il": 1.0, "vtn": "A","pr": 1150} ], "summary" : { "to": 3500 } }' |
STATUS WYDRUKU PARAGONU
O sukcesie wydruku paragonu mówi nam pole “ok” w response, ale w odpowiedzi z serwisu znajduje się więcej pól: To jest standardowa odpowiedź serwisu., Wszystkie Pola poza “ok” są opcjonalne.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "ok": true, "message": "", "code": 0, "bn": "14", "hn": "2612", "eparagon": { "id": 0 }, "took": 902, "ts": 1627376834869, "tsend": 1627376834969, "transaction": "bb3b77bf-e33b-4fbb-ad62-ede768ed5652", "userdata": {} } |
- ok – Pole informujące o sukcesie lub błędzie wydruku. Jeśli ok=true , to proces fiskalizacji przebiegł pomyślnie, paragon się wydrukował i jego numer można odczytać z pola “hn“. Jeśli ok=”false” to pola “code” i “message” informują o tym co poszło nie tak.
- bn – numer porządkowy wydruku
- eparagon – identyfikator eParagonu, jeśli fiskalizujemy paragon jako eParagon,
- took – czas fiskalizacji w ms
- ts – znacznik czasu rozpoczęcia fiskalizacji
- tsend – znacznik czasu zakończenia fiskalizacji. Pole “took” to różnica pomiędzy tsend i ts,
- transaction – identyfikator requestu. Uzupełniany jedynie w przypadku wydruku asynchronicznego (flaga async=true w request, domyślnie async=false)
- userdata – dowolne dane użytkownika. Jest to wykorzystywane w przypadku requestów asynchronicznych lub requestów z callbackiem
Wiele paragonów
Często chcemy wydrukować wiele paragonów na raz. W takiej sytuacji możemy skorzystać z requestu /paragony.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
curl -XPOST "http://localhost:3050/paragony" -H 'Content-Type: application/json' -d'[{ lines : [ { na: "Towar 1", il: 1.0, vt: 0,pr: 12356}, { na: "Towar 2", il: 1.0, vt: 0,pr: 34567} ], summary : { to: 46923 } }, { lines : [ { na: "Towar 3", il: 1.0, vt: 0,pr: 12356}, { na: "Towar 4", il: 1.0, vt: 0,pr: 34567} ], summary : { to: 46923 } }]' |
Powyższy request wydrukuje 2 paragony na drukarce.
Drukowanie asynchroniczne (opcja 1)
Drukarki fiskalne nie należą do najszybszych, stąd pojedynczy request do serwisu może trwać od kilku do nawet kilkunastu sekund, blokując tym samym proces requestujący. Aby otrzymać szybko zwrot i nie czekać na zakończenie drukowania, należy dodać w URL “?async=true“. Dzięki temu PostnetServer przyjmie request i doda go do kolejki, zwracając niezwłocznie 200OK do procesu requetsującego. Drukowanie paragonu rozpocznie się jak tylko drukarka będzie gotowa. Status requestu asynchronicznego można sprawdzić odpytując restpoint /paragon podając identyfikator transakcji asynchronicznej.
|
1 2 3 4 5 6 7 8 9 |
curl -XPOST "http://localhost:3050/paragon?async=true" -H 'Content-Type: application/json' -d'{ "lines" : [ { "na": "Towar 1", "il": 1.0, "vt": 0,"pr": 2350}, { "na": "Towar 2", "il": 1.0, "vt": 0,"pr": 1150} ], "summary" : { "to": 3500 } }' |
Sprawdzenie statusu (gdzie 5f1c29d0-3284-4bb7-878c-4cf6f992591b to identyfikator transakcji asynchronicznej zwrócony w odpowiedzi na poprzedni request):
|
1 |
curl -XGET "http://localhost:3050/paragon/5f1c29d0-3284-4bb7-878c-4cf6f992591b" -H 'Content-Type: application/json' |
W przypadku wydruku asynchronicznego możliwe jest przekazanie URL jaki ma zostać wykonany po zakończeniu wydruku, dzięki czemu nie musimy sprawdzać co pewien czas czy nasz paragon już się wydrukował
|
1 2 3 4 5 6 7 8 9 |
curl -XPOST "http://localhost:3050/paragon?async=true&url=http://myserver/api/result&urlmethod=POST" -H 'Content-Type: application/json' -d'{ "lines" : [ { "na": "Towar 1", "il": 1.0, "vt": 0,"pr": 2350}, { "na": "Towar 2", "il": 1.0, "vt": 0,"pr": 1150} ], "summary" : { "to": 3500 } }' |
DRUKOWANIE ASYNCHRONICZNE (OPCJA 2)
Node.js działa w jednym wątku, co oznacza że kolejne wołanie asynchroniczne (z parametrem ?async=true) będzie i tak oczekiwało na zakończenie aktualnego wydruku. Najlepszym rozwiązaniem aby zapewnić pełną asynchroniczność jest użycie kolejki requestów w formie “proxy” przed PostnetServer’em. Jest wiele sposobów na stworzenie takiej architektury, niemniej jednak w naszym publicznym repozytorium github, zamieszczamy kod przykładowego rozwiązania
https://github.com/bigdotsoftware/posnetserver-async-proxy
dodatkowe linie
Aby wstawić dodatkowe linie pod paragonem, wyślij następujący request:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
curl -XPOST "http://localhost:3050/paragon?async=true" -H 'Content-Type: application/json' -d'{ "lines" : [ { "na": "Towar 1", "il": 1.0, "vt": 0,"pr": 2350}, { "na": "Towar 2", "il": 1.0, "vt": 0,"pr": 1150} ], "summary" : { "to": 3500 }, extralines: [ {id:2, na: "987"}, {id:15, na: "Jan Kowalski"}, {id:39, na: "FV 12345/2018"}, {id:33, na: "dodatkowe informacje #1"}, {id:33, na: "dodatkowe informacje #2", sw: true, sh: true}, {id:38, na: "text info"} ] }' |
Gdzie ID linii może być jedną z poniższych wartości:
| ID | Opis | Typ |
|---|---|---|
| 0 | Nr transakcji | alfanumeryczny |
| 1 | Punkty | alfanumeryczny |
| 2 | Suma punktów | alfanumeryczny |
| 3 | Nr rejestracyjny | alfanumeryczny |
| 4 | Nazwisko | alfanumeryczny |
| 5 | Karta | alfanumeryczny |
| 6 | Numer karty | alfanumeryczny |
| 7 | Ważna do | alfanumeryczny |
| 8 | Kasjer | alfanumeryczny |
| 9 | Nazw. kasjera | alfanumeryczny |
| 10 | Zaliczka | alfanumeryczny |
| 11 | Waluta | alfanumeryczny |
| 12 | Przelicznik | alfanumeryczny |
| 13 | Nr zamówienia | alfanumeryczny |
| 14 | Nr Pracownika | alfanumeryczny |
| 15 | Nazw. Pracownika | alfanumeryczny |
| 16 | Konto przed tr. | alfanumeryczny |
| 17 | Przyznano | alfanumeryczny |
| 18 | Wykorzystano | alfanumeryczny |
| 19 | Konto po trans. | alfanumeryczny |
| 20 | Klienta stały | alfanumeryczny |
| 21 | Voucher | alfanumeryczny |
| 22 | Wartość Voucher | alfanumeryczny |
| 23 | Zapłata Voucher | alfanumeryczny |
| 24 | napis predefiniowany | bez parametru |
| 25 | linia bez słowa kluczowego (15 spacji) | alfanumeryczny |
| 26 | Ilość sprzedanych towarów | alfanumeryczny |
| 27 | Numer pracownika | alfanumeryczny |
| 28 | Numer klienta | alfanumeryczny |
| 29 | Udzielono łącznie rabatów | alfanumeryczny |
| 30 | Numer | alfanumeryczny |
| 31 | Kod | alfanumeryczny |
| 32 | Nazwa | alfanumeryczny |
| 33 | Opis | alfanumeryczny |
| 34 | Liczba | alfanumeryczny |
| 35 | Klient | alfanumeryczny |
| 36 | Kwota | alfanumeryczny |
| 37 | Promocja | alfanumeryczny |
| 38 | Info | alfanumeryczny |
| 39 | Do faktury | alfanumeryczny |
| 40 | Ad. | alfanumeryczny |
| 41 | napis predefiniowany z uwzględnieniem znaków formatujących | bez parametru |
| 42 | napis predefiniowany z małą czcionką | alfanumeryczny |