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 przypadku wydruku paragonów nie zawsze wiadomo który indeks stawki odpowiada jakiej stawce VAT. Aby nie odpytywać za każdym razem drukarki lub tym bardziej nie trzymać konfiguracji w kodzie, PosnetServer pozwala wygodnie przekazać stawkę VAT w formacie “23,00”, “8,00” lub “A”, “B” itd. Przykład:
|
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 odpowedzi z serwisu znajduje się więcej pól: To jest standardowa odpowiedź serwisu., Wszystkie Pola poza “ok” sa 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, jesli 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 |