1. Przygotowanie pliku z danymi JSON.

Plik wsadowy składa się z jednego głównego obiektu nadrzędnego, w którym wyróżniamy cztery kluczowe sekcje logiczne. Taki podział gwarantuje porządek w danych i ułatwia późniejsze mapowanie pól w lewym panelu edytora.

Poniższy plik JSON zawiera pełne, ustrukturyzowane dane transakcji dla fikcyjnego sklepu elektronicznego, uwzględniające rabaty, podziały stawek VAT oraz informacje o płatności.

{
"receipt_details": {
"store_info": {
"company_name": "TechNova Sp. z o.o.",
"brand_name": "TechNova - Strefa Elektroniki",
"address": "31-154 Krakow, ul. Pawia 5",
"city_address": "Galeria Nova, Poziom +1",
"bdo_number": "000099887",
"nip_number": "525-00-11-222"
},
"transaction_info": {
"print_date": "2026-05-25",
"print_time": "14:35",
"print_number": "412533/0892",
"transaction_number": "28471",
"cashier_number": "104",
"pos_id": "POS-03"
},
"totals": {
"total_amount": "234,40",
"discount_total": "15,00",
"payment_method": "KARTA PLATNICZA"
},
"vat_aggregates": {
"vat_typeA_base": "154,39",
"vat_typeA_amount": "35,51",
"vat_typeA_rate": "23,00%",
"vat_typeB_base": "41,20",
"vat_typeB_amount": "3,30",
"vat_typeB_rate": "08,00%",
"vat_total_amount": "38,81"
},
"items": [
{
"product_name": "Sluchawki BT NovaSound",
"quantity": 1,
"unit_price": "149,90",
"total_price": "149,90 A"
},
{
"product_name": "Kabel USB-C Premium 2m",
"quantity": 2,
"unit_price": "19,75",
"total_price": "39,50 B"
},
{
"product_name": "Ladowarka Sieciowa 30W",
"quantity": 1,
"unit_price": "60,00",
"total_price": "60,00 A"
}
],
"marketing": {
"loyalty_card": "9876543210",
"points_earned": "45",
"footer_promo": "Zyskaj 10% rabatu na kolejne zakupy!"
}
}
}

Dane Sprzedawcy (store_info) – Zawiera stałe dane teleadresowe sklepu lub firmy. Wszystkie pola w tej sekcji są tekstowe (String).

• company_name: Oficjalna nazwa rejestrowa spółki.
• brand_name: Nazwa handlowa widoczna na samej górze paragonu.
• address & city_address: Dane lokalizacyjne.
• nip_number & bdo_number: Numery identyfikacji podatkowej i środowiskowej.

Metryka Transakcji (transaction_info)Te dane zmieniają się przy każdym wydruku.

• print_date & print_time: Data i godzina (rekomendowany format: YYYY-MM-DD oraz HH:MM).
• print_number: Unikalny licznik wydruku z danej drukarki.
• transaction_number: Numer zamówienia lub transakcji z systemu POS.
• cashier_number: Identyfikator pracownika (może być liczbą lub tekstem).

Podsumowanie Finansowe (totals)Kluczowe pola liczbowe, przekazywane jako tekst z separatorem dziesiętnym w postaci przecinka (ułatwia to poprawne formatowanie bezpośrednio na drukarce).

• total_amount: Ostateczna kwota do zapłaty.
• payment_method: Sposób płatności (np. KARTA, GOTÓWKA, BLIK).

Agregaty Podatkowe (vat_aggregates)Słownik przechowujący podsumowanie stawek VAT. W przypadku systemów niefiskalnych OPOS, każdą stawkę (A, B, C…) opisujemy trzema polami:

• base: Podstawa opodatkowania w danej stawce.
• amount: Kwota naliczonego podatku.
• rate: Procentowa wartość stawki (np. „23,00%”).

Wykaz Pozycji – Kolekcja Dynamiczna (items)To najważniejsza część struktury – tablica (oznaczona nawiasami kwadratowymi […]), która zawiera listę zakupionych towarów. Każdy produkt na liście musi być osobnym obiektem posiadającym dokładnie te same klucze:

• product_name (String): Nazwa towaru.
• quantity (Integer/Numeric): Ilość zakupionych sztuk.
• unit_price (String): Cena za jedną sztukę.
• total_price (String): Cena łączna (ilość x cena jednostkowa) uzupełniona o literowe oznaczenie stawki VAT (np.
• „149,90 A”), co jest standardem dla czytelności paragonu.

Gotowy plik należy zapisać w formacie JSON, następnie zaimportować do Comarch sPrint Wydruki OPOS wybierając „Prześlij plik z danymi”

Można skorzystać z opcji „Przeciągnij i upuść” lub „wybierz plik”

2. Przygotowanie definicji wydruku JSON.

Po zainicjowaniu nowego projektu szablonu wydruku OPOS w aplikacji, w obszarze roboczym automatycznie generowana jest struktura startowa. Stan ten przedstawia poniższy zrzut ekranu:

Wyjaśnienie elementów startowych:

• maxlength: Globalny parametr określający maksymalną szerokość linii w znakach. Domyślna wartość 56 jest optymalna dla szerszych taśm papieru. Na potrzeby naszego case study (standardowa węższa rolka) wartość tę zmodyfikujemy do 42, aby zapewnić idealne wyrównanie kolumn na wydruku o szerokości około 58 mm.
• body: Główna tablica (kontener), wewnątrz której będziemy umieszczać kolejne sekcje, linie i komendy sterujące drukarką (takie jak bloki tekstu, pętle czy polecenie cięcia papieru).

Budując profesjonalny szablon paragonu dla sklepu TechNova, wykorzystamy pełen wachlarz narzędzi systemu sPrint. Poniżej opisujemy kluczowe moduły szablonu wraz ze wskazaniem odpowiednich tagów i funkcji.

Podstawowym elementem budulcowym każdej definicji wydruku OPOS jest linia, reprezentowana w kodzie jako obiekt o typie Line. Każda instancja tego obiektu odpowiada za wyrenderowanie dokładnie jednego fizycznego, poziomego wiersza tekstu na taśmie papieru.

Gdzie wstawić kod nowej linii? Wszystkie linie tworzące strukturę paragonu muszą znajdować się wewnątrz nawiasów kwadratowych głównej tablicy „body”: [].

W standardzie JSON nawiasy kwadratowe oznaczają listę (tablicę) elementów, które na wydruku będą układane chronologicznie – od góry do dołu.

Wstawianie pierwszej linii: Obiekt należy umieścić bezpośrednio wewnątrz pustych nawiasów

"body": [
/* Miejsce na nowe linie*/
]

Dodawanie kolejnych linii: Każdy kolejny obiekt linii musi być bezwzględnie oddzielony od poprzedniego przecinkiem np.:

}, {W przypadku korzystania z narzędziownika  i użycia ikony „Wstaw linię”, program automatycznie weryfikuje pozycję kursora. Jeżeli kursor znajduje się wewnątrz sekcji body, edytor samoczynnie dba o poprawność struktury i automatycznie wstawia wymagane przecinki separujące.

W momencie wywołania funkcji „Wstaw linię”, aplikacja generuje w obszarze roboczym pełny szablon obiektu zawierający wszystkie domyślne parametry formatowania. Eliminuje to konieczność pamiętania nazw właściwości sterujących sterownikiem OPOS.

Każdy z wygenerowanych automatycznie parametrów odpowiada za określone zachowanie wiersza na fizycznym wydruku:

• Type („Line”): Identyfikator typu obiektu. Informuje silnik renderujący o utworzeniu nowego fizycznego wiersza.
• Items: Tablica (kontener) na elementy składowe wiersza. Domyślnie system umieszcza w niej jeden pusty obiekt tekstowy („Type”: „Text”, „Value”: „”), w którym docelowo wpisuje się statyczny tekst lub zamienia go na obiekt dynamiczny („Type„: „Data„).
• Bold / Italic / Underline (false): Flagowe sterowniki stylów czcionki (kolejno: pogrubienie, kursywa, podkreślenie). Zmiana wartości na true aktywuje dany styl dla całego tekstu znajdującego się w tej linii.
• DoubleWide / DoubleHeight (false): Parametry odpowiedzialne za sprzętowe powiększenie czcionki przez drukarkę. DoubleWide rozciąga znaki w poziomie, a DoubleHeight w pionie. Aktywacja obu parametrów jednocześnie (true) pozwala na uzyskanie efektu dużej, czytelnej czcionki tytułowej lub sumarycznej.
• Align („Left”): Globalne wyrównanie zawartości linii na papierze. Domyślnie tekst dosuwany jest do lewej krawędzi. Dostępne wartości to również „Center” (wyśrodkowanie – stosowane w nagłówkach) oraz „Right” (wyrównanie do prawej).
• MaxLines (1): Kluczowy parametr bezpieczeństwa układu graficznego. Wartość 1 gwarantuje, że jeśli dane wstrzyknięte do linii będą dłuższe niż pozwala na to szerokość papieru (zdefiniowana w maxlength), tekst zostanie bezpiecznie przycięty w jednej linii, co zapobiega niekontrolowanemu zawinięciu i rozbiciu struktury kolejnych wierszy poniżej.

Połączenie tekstu statycznego z danymi dynamicznymi

Przed przystąpieniem do budowy zaawansowanych pętli dynamicznych, zaleca się oswojenie z mechanizmem interpretacji danych przez silnik sPrint. W tym celu w strukturze body należy umieścić dwa podstawowe wiersze: jeden reprezentujący treść niezmienną, a drugi mapujący informację bezpośrednio z pliku źródłowego JSON.

Poniższy kod ilustruje poprawnie zainicjowany początek sekcji nagłówkowej w obszarze roboczym:

{
"maxlength": 42,
"body": [
{
"Type": "Line",
"Items": [
{
"Type": "Text",
"Value": "TechNova - Strefa Elektroniki"
}
],
"Bold": true,
"Align": "Center",
"MaxLines": 1
},
{
"Type": "Line",
"Items": [
{
"Type": "Text",
"Value": "NIP: "
},
{
"Type": "Data",
"Path": "receipt_details.store_info.nip_number"
}
],
"Align": "Center",
"MaxLines": 1
}
]
} 

Struktura tablicy body: Widoczne są dwa obiekty typu Line ułożone jeden po drugim, oddzielone obowiązkowym przecinkiem. Na fizycznym wydruku przełoży się to na dwa osobne, wycentrowane wiersze.

Użycie obiektu Text (Linia 1): W pierwszej linii parametr Value przechowuje sztywny ciąg znaków „TechNova – Strefa Elektroniki”. Tekst ten będzie identyczny dla każdego generowanego dokumentu. Dodatkowo włączono pogrubienie („Bold”: true).

Użycie obiektu Data (Linia 2): Druga linia demonstruje łączenie etykiety statycznej z parametrem dynamicznym wewnątrz jednej tablicy Items.

• Pierwszy element to stały napis „NIP: „.
• Drugi element to obiekt typu „Type”: „Data”. Nie posiada on parametru Value, lecz parametr Path (ścieżkę). Wskazuje ona bezpośrednio na pole receipt_details.store_info.nip_number w pliku wsadowym klienta. Podczas generowania wydruku system automatycznie podstawi tam wartość „525-00-11-222”.

Taki schemat działania stanowi bazę dla wszystkich kolejnych operacji na szablonie.

Pobieranie ścieżek z panelu bocznego (Parametr Path)
W lewym panelu bocznym aplikacja wizualizuje strukturę danych w postaci interaktywnego drzewa. Obok każdej zmiennej dostępna jest ikona plusa + („Dodaj do definicji”). Kliknięcie ikony lub przeciągnięcie elementu wprost do obszaru roboczego powoduje automatyczne wygenerowanie i wklejenie poprawnej ścieżki kropkowej w miejscu kursora (np. „receipt_details.store_info.nip_number”).

Autouzupełnianie składni (Skrót klawiszowy Ctrl + Space)
Ręczne wpisywanie znaczników strukturalnych nie jest wymagane, co zapobiega powstawaniu błędw w strukturze pliku JSON.

• Wywołanie kontekstowe: Po ustawieniu kursora wewnątrz cudzysłowu dla parametru „Type”: „” i naciśnięciu kombinacji klawiszy Ctrl + Space, system automatycznie wyświetli rozwijaną listę z poprawnymi, predefiniowanymi typami składników wydruku (np. Barcode, Line, NewLine, PaperCut).
• Podpowiedzi dla właściwości: Skrót działa również wewnątrz obiektów. Po wpisaniu znaku cudzysłowu na początku pustej linii, naciśnięcie Ctrl + Space wywołuje listę parametrów i stylów dostępnych dla danego elementu (np. Align, Bold, Italic, Length, Underline).

Zamiast ręcznego wpisywania komend, wybiera się żądany element bezpośrednio za pomocą myszy lub strzałek klawiatury. Zapobiega to powstawaniu błędów składniowych, takich jak literówki czy niepoprawnie domknięte cudzysłowy w pliku JSON.

Dynamiczne generowanie pozycji towarowych za pomocą pętli (Type: Repeat)

Dynamiczne generowanie pozycji towarowych za pomocą pętli (Type: Repeat) W celu sprawnego generowania list produktów na wydruku, których liczba zmienia się w zależności od transakcji, stosuje się obiekt typu Repeat. Działa on jak pętla programistyczna, która iteruje po wskazanej kolekcji danych i powiela zdefiniowany wewnątrz niej układ graficzny.

Inicjalizacja pętli w edytorze

Obiekt Repeat umieszcza się jako kolejny element nadrzędny w tablicy „body”: []. Można go wywołać bezpośrednio z narzędziownika, klikając ikonę z dwiema strzałkami i etykietą „Powtarzaj elementy”.

Po wywołaniu tej funkcji, w obszarze roboczym generowany jest następujący, czysty kod startowy:

{
"Type": "Repeat",
"DataMember": "",
"Items": []
}

Type („Repeat„): Identyfikator informujący silnik sPrint, że ten blok kodu odpowiada za operację cyklicznego powtarzania elementów.
DataMember: Puste pole tekstowe, w którym należy wskazać ścieżkę do tablicy (kolekcji obiektów) z pliku źródłowego JSON.
Items: Pusta tablica przeznaczona na umieszczenie szablonu wiersza (obiektu Line), który ma być powielany dla każdego elementu z pliku danych.

Konfiguracja i mapowanie kolekcji krok po kroku

Po wstawieniu bloku startowego, proces konfiguracji przebiega dwuetapowo: wskazanie źródła danych oraz zdefiniowanie wyglądu wiersza.

1. Określenie źródła danych

W polu DataMember należy podać ścieżkę do kolekcji produktów. Najwygodniejszym sposobem jest skorzystanie z lewego panelu bocznego, odnalezienie sekcji zawierającej listę (w omawianym przypadku jest to sekcja items) i kliknięcie znajdującej się przy niej ikony plusa +. Ścieżka zostanie automatycznie wstrzyknięta do kodu:

"DataMember": "receipt_details.items"

2. Wstawienie wzorca wiersza do tablicy Items

Pętla Repeat wymaga zdefiniowania układu graficznego dla pojedynczego towaru. W tym celu należy ustawić kursor wewnątrz pustej tablicy „Items„: [] i kliknąć znaną z poprzedniego kroku ikonę „Wstaw linię„. Edytor automatycznie wygeneruje pełny obiekt typu Line wewnątrz pętli:

{
"Type": "Repeat",
"DataMember": "receipt_details.items",
"Items": [
{
"Type": "Line",
"Items": [
{
"Type": "Data",
"Path": "receipt_details.items.product_name",
"Length": 22
},
{
"Type": "Data",
"Path": "receipt_details.items.quantity",
"Length": 3,
"Align": "Right"
},
{
"Type": "Text",
"Value": " x "
},
{
"Type": "Data",
"Path": "receipt_details.items.unit_price",
"Length": 7,
"Align": "Right"
},
{
"Type": "Text",
"Value": " = "
},
{
"Type": "Data",
"Path": "receipt_details.items.total_price",
"Length": 8,
"Align": "Right"
}
],
"Align": "Left",
"MaxLines": 1
}
]
}

Podczas renderowania pozycji asortymentowych sPrint przetwarza zagnieżdżone elementy w następujący sposób:

• Pętla sprzętowa: System sprawdza wielkość tablicy w pliku wsadowym i automatycznie powiela obiekt Line dokładnie tyle razy, ile pozycji zakupił klient.
• Wielopoziomowy parametr Path: Podelementy typu „Type„: „Data” wewnątrz pętli odnoszą się bezpośrednio do pól pojedynczego obiektu z listy (np. product_name, quantity). Ścieżki te zachowują notację kropkową rozpoczynającą się od nazwy kolekcji.
• Wyrównanie kolumnowe (Formatowanie tabelaryczne): Poprzez nadanie sztywnych szerokości za pomocą parametru Length (22 dla nazwy, 3 dla ilości, 7 dla ceny jednostkowej, 8 dla sumy) oraz znaków oddzielających Text (dwukrotnie po 3 znaki ze spacjami), uzyskuje się łączną szerokość linii równą dokładnie 42 znakom (23 + 3 + 3 + 7 + 3 + 8 = 42). Sprawia to, że dane na wydruku układają się w równe sekcje pionowe, a zastosowanie „Align„: „Right” dla wartości liczbowych gwarantuje ich czytelne dosunięcie do prawej krawędzi kolumn.

Implementacja instrukcji warunkowej (Type: Conditional)

W celu wprowadzenia logiki biznesowej do wydruku (np. wyświetlania sekcji marketingu lub danych karty lojalnościowej tylko wtedy, gdy klient ją posiada) stosuje się strukturę warunkową.

Inicjalizacja instrukcji warunkowej

Instrukcję wprowadza się do tablicy body poprzez kliknięcie ikony „if” na pasku narzędziowym lub za pomocą skrótu Ctrl + Space i wybrania opcji Conditional z listy autouzupełniania.

Po wywołaniu funkcji, w obszarze roboczym generowany jest następujący czysty kod startowy: