# Ritevo Printer Ritevo Printer - aplikacja do drukowania etykiet kurierskich (PDF, ZPL, EPL) i paragonów na polskich drukarkach fiskalnych: obsługiwane systemy, pobieranie, podłączenie drukarki, druk z zamówienia i z akcji. Ritevo Printer drukuje etykiety kurierskie i paragony fiskalne prosto z zamówień w Ritevo. Instalujesz ją na komputerze, do którego podłączona jest drukarka - albo kilka drukarek naraz - a wydruk zlecasz w panelu: z zamówienia, akcją automatyczną albo nawet z telefonu. > **Wymagana integracja:** Potrzebujesz komputera z Windows, macOS albo Linuksem, do którego podłączona jest drukarka (albo kilka drukarek), z zainstalowaną aplikacją Ritevo Printer. W panelu Ritevo dodaj nową integrację **Drukarka** - osobną dla każdej drukarki - i powiąż ją z aplikacją Ritevo Printer na komputerze. ## Jak to działa - **Jedna drukarka - jedna integracja.** Każda drukarka to osobna integracja **Drukarka** w panelu, z własnym tokenem. - **Wiele drukarek w jednej aplikacji.** Na jednym stanowisku dodasz np. drukarkę fiskalną do paragonów i zwykłą drukarkę do etykiet PDF - każda pracuje niezależnie. - **Wiele stanowisk.** Każdy komputer ma własną aplikację Ritevo Printer ze swoimi drukarkami - np. kasa z paragonami i pakowalnia z etykietami albo osobne stanowiska kilku pracowników. - **Zlecasz skądkolwiek.** Wydruk zlecasz w panelu - na komputerze albo w telefonie - a drukuje komputer, na którym działa aplikacja z tą drukarką. - **Działa w tle.** Zamknięcie okna chowa aplikację do paska systemowego. Zaznacz **Uruchamiaj agenta po zalogowaniu**, żeby po restarcie komputera drukowała dalej. ## Obsługiwane systemy i drukarki Etykiety PDF wydrukujesz na każdej drukarce dodanej w komputerze, także na zwykłej atramentowej albo laserowej. Etykiety ZPL i EPL wydrukuje tylko drukarka etykiet, np. Zebra. Paragony drukujemy przez oprogramowanie, które dostarcza producent drukarki fiskalnej - a nie każdy producent przygotował je na każdy system. Co działa gdzie: | | Windows | Linux | macOS | | --- | --- | --- | --- | | Etykiety PDF | ✓ | ✓ | ✓ | | Etykiety ZPL / EPL | ✓ | ✓ | ✓ | | Paragony - Novitus | ✓ | ✓ tylko drukarka w sieci | ✓ | | Paragony - Posnet | ✓ | ✓ | ✓ tylko Mac z procesorem Intel | | Paragony - Elzab | ✓ | ✓ port /dev/ttyS albo drukarka w sieci | ✗ | - Drukarka Novitus musi pracować w protokole XML - to ustawienie w menu drukarki. W starszym protokole klasycznym aplikacja ją rozpozna, ale paragonu nie wydrukuje. - Drukarkę fiskalną podłączoną przez USB system widzi jako port szeregowy (na Windowsie port COM) - na Windowsie wymaga to sterownika producenta drukarki. - Drukarkę fiskalną w sieci podajesz adresem i portem, np. `tcp:192.168.1.50:6666` - port znajdziesz w ustawieniach drukarki. - Obsługujemy drukarki fiskalne Novitus, Posnet i Elzab, a paragony drukujemy tylko w PLN. ## Pobieranie i instalacja Pobierz wersję dla swojego systemu - wszystkie wersje są też na stronie [Pobierz Ritevo Printer](/pl/ritevo-printer): - **Windows** - [ritevo-printer-setup.exe](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-setup.exe) - **macOS, Apple Silicon (M1 i nowsze)** - [ritevo-printer-arm64.dmg](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-arm64.dmg) - **macOS, Intel** - [ritevo-printer-x64.dmg](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-x64.dmg) - **Linux** - [ritevo-printer.AppImage](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer.AppImage) albo [ritevo-printer_amd64.deb](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer_amd64.deb) Aplikacja nie jest podpisana certyfikatem, więc przy pierwszym uruchomieniu system zapyta o zgodę: - **Windows** - w oknie SmartScreen kliknij **Więcej informacji**, a potem **Uruchom mimo to**. - **macOS** - przy komunikacie, że Apple nie może zweryfikować aplikacji, kliknij **Gotowe**, wejdź w **Ustawienia systemowe → Prywatność i ochrona** i kliknij **Otwórz mimo to**. Aktualizacje: na Windowsie i Linuksie (AppImage) nowa wersja pobiera się sama i instaluje, gdy nic się nie drukuje - możesz też kliknąć **Uruchom ponownie i zaktualizuj**. Na macOS aplikacja pokaże **Pobierz nową wersję** - pobierz plik i przeciągnij Ritevo Printer do folderu Aplikacje. Wersję .deb aktualizujesz ręcznie. ![Sekcja Aktualizacje w Ritevo Printer z numerem wersji i przyciskiem Sprawdź aktualizacje](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-updates.webp) ## Dodanie drukarki w panelu 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Drukarki** wybierz kafelek **Drukarka**. 3. Wpisz **Nazwa drukarki** - własną nazwę, np. stanowiska - i kliknij **Dodaj integrację**. 4. Otwórz drukarkę na liście integracji i w karcie **Token drukarki** kliknij **Pokaż token**. Skopiuj go - wkleisz go w aplikacji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Katalog integracji w Ritevo z zaznaczonym kafelkiem Drukarka w sekcji Drukarki](https://ritevo.com/docs/integrations/ritevo-printer/pl-catalogue.webp) ![Formularz dodania drukarki z polem Nazwa drukarki](https://ritevo.com/docs/integrations/ritevo-printer/pl-add.webp) ![Lista integracji z dodaną drukarką Stanowisko #1](https://ritevo.com/docs/integrations/ritevo-printer/pl-list.webp) ## Dodanie drukarki w aplikacji 1. Otwórz Ritevo Printer i kliknij **+ Dodaj drukarkę**. 2. Wklej **Token drukarki** z panelu. 3. W polu **Drukarka** wybierz drukarkę, której chcesz używać. Drukarkę fiskalną podłączoną do sieci wybierz jako **Drukarka fiskalna w sieci (adres IP)** i wpisz jej adres. 4. Aplikacja sama sprawdzi, jaka to drukarka, i pokaże **Podłączona drukarka**. 5. Kliknij **Zapisz drukarkę**. 6. Kliknij **Uruchom**. Przy drukarce pojawi się **Działa - nasłuchuję zadań**. Możesz dodać kolejne drukarki, np. jedną do etykiet, a drugą do paragonów: kliknij jeszcze raz **+ Dodaj drukarkę** i wklej token kolejnej drukarki z panelu. ![Formularz nowej drukarki w Ritevo Printer z tokenem i rozpoznaną drukarką systemową](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-add.webp) ![Okno Ritevo Printer z listą drukarek i przyciskiem Dodaj drukarkę](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-printers.webp) > **Warto wiedzieć:** Drukarki do etykiet nie ma na liście? Dodaj ją najpierw w systemie: na Windowsie w **Ustawienia → Drukarki i skanery**, na Macu w **Ustawienia systemowe → Drukarki i skanery**. Na Macu przy zwykłej drukarce atramentowej lub laserowej wybierz sterownik **AirPrint** - z ogólnym sterownikiem PostScript wydruk nie wyjdzie. ## Drukowanie Wydruk zlecasz ręcznie albo akcją automatyczną: - **Etykieta** (ręcznie) - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij **Drukuj** i wybierz drukarkę. - **Paragon** (ręcznie) - w szczegółach zamówienia rozwiń przycisk paragonu i w sekcji **Drukuj** wybierz drukarkę. To samo zrobisz z listy dokumentów. - **Wydrukuj etykietę przesyłki** (krok akcji) (API: "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`; wartość w `actionSteps[].action.type`) - drukuje etykietę najnowszej udanej przesyłki zamówienia na wybranej drukarce. - **Wydrukuj paragon** (krok akcji) (API: "Wydrukuj paragon" = `PRINT_RECEIPT`; wartość w `actionSteps[].action.type`) - drukuje najnowszy paragon zamówienia na wybranej drukarce fiskalnej. - **Zlecenie wydruku** (wyzwalacz akcji) (API: "Zlecenie wydruku" = `CREATE_PRINT_JOB`; wartość w `triggerType`) - uruchamia akcję, gdy wydruk zostanie zlecony. ![Karta Przesyłki w zamówieniu z rozwiniętym przyciskiem Drukuj i listą drukarek](https://ritevo.com/docs/integrations/ritevo-printer/pl-print-label.webp) ![Wystawione dokumenty w zamówieniu z rozwiniętym paragonem i sekcją Drukuj z listą drukarek](https://ritevo.com/docs/integrations/ritevo-printer/pl-print-receipt.webp) Zlecony wydruk czeka w karcie **Aktualna kolejka** w szczegółach drukarki, aż aplikacja go odbierze - wydruki zlecone przy wyłączonym komputerze wyjdą po jego włączeniu. Wynik widzisz w karcie **Historia wydruków**: - **Wydrukowano** (API: "Wydrukowano" = `SUCCESS`; wartość w `status`) - aplikacja odebrała wydruk i wysłała go na drukarkę. - **Błąd** (API: "Błąd" = `ERROR`; wartość w `status`) - wydruku nie dało się przygotować, np. kurier nie oddał etykiety. Plakietka pokazuje rodzaj błędu, a ikona obok - jego treść. ![Szczegóły drukarki w Ritevo: token, aktualna kolejka i historia wydruków](https://ritevo.com/docs/integrations/ritevo-printer/pl-details.webp) W samej aplikacji, w sekcji **Ostatnie zadania i błędy**, widzisz, co i na której drukarce się wydrukowało, oraz błędy drukarki, np. brak papieru. ![Sekcja Ostatnie zadania i błędy w Ritevo Printer](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-history.webp) ## Druk w akcji automatycznej Na co zwrócić uwagę, gdy akcja ma coś wydrukować: - **Wydrukuj etykietę przesyłki** (API: "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`; wartość w `uuidValue`: id integracji drukarki: `GET /integrations/printers`) - bierze najnowszą przesyłkę zamówienia, która została utworzona pomyślnie. Jeśli takiej nie ma, krok kończy się błędem. - **Wydrukuj paragon** (API: "Wydrukuj paragon" = `PRINT_RECEIPT`; wartość w `uuidValue`: id integracji drukarki: `GET /integrations/printers`) - bierze najnowszy paragon zamówienia, który nie został usunięty. Jeśli zamówienie nie ma paragonu, krok kończy się błędem. - **Utwórz przesyłkę**, potem **Wydrukuj etykietę przesyłki** (API: "Utwórz przesyłkę" = `CREATE_SHIPMENT`, "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`) - najpierw przesyłka, w następnym kroku etykieta. Krok przesyłki czeka na odpowiedź kuriera, więc etykieta jest gotowa, zanim przyjdzie czas na druk. - **Wygeneruj paragon**, potem **Wydrukuj paragon** (API: "Wygeneruj paragon" = `GENERATE_RECEIPT`, "Wydrukuj paragon" = `PRINT_RECEIPT`) - tak samo dla paragonu: najpierw dokument, w następnym kroku wydruk. - **Status przesyłki jest** (API: "Status przesyłki jest" = `SHIPMENT_STATUS_IS`; wartość w `enumValues`: `PENDING`, `SUCCESS`, `ERROR`) - żeby nie drukować etykiety po nieudanej przesyłce, dodaj w kroku druku [rozgałęzienie](https://ritevo.com/pl/docs/automations/how-it-works#branches) z tym warunkiem i wartością Utworzona pomyślnie. Krok druku nie czeka, aż kartka wyjdzie z drukarki. Akcja idzie dalej, gdy wydruk trafi do kolejki albo gdy od razu się nie uda - błąd nie zatrzymuje akcji. Nie ma warunku na wynik wydruku, więc sprawdzisz go w **Historii wydruków**. Jeśli wydruk trafi na drukarkę złego rodzaju - etykieta na fiskalną albo paragon na zwykłą - odrzuci go dopiero aplikacja na komputerze. Zobaczysz to w jej historii, akcja się o tym nie dowie. ## Paragony fiskalne - Paragon drukujemy tylko przez oficjalną bibliotekę producenta drukarki. - Zanim paragon trafi na drukarkę, sprawdzamy, czy to paragon w złotówkach i czy suma pozycji zgadza się z kwotą dokumentu. - Aplikacja zapamiętuje każdy wydrukowany paragon. Jeśli ten sam paragon zostanie zlecony na tym komputerze jeszcze raz, nie wydrukuje go drugi raz i pokaże komunikat. Zabezpieczenie działa tylko w obrębie jednego komputera, dlatego drukarkę fiskalną podłącz w aplikacji tylko na jednym stanowisku i każdy paragon zlecaj na jedną drukarkę - inne stanowisko nie wie, co już zostało wydrukowane. - Gdy połączenie z drukarką zerwie się w trakcie paragonu, aplikacja pokaże **Sprawdź drukarkę** - zanim wyślesz paragon ponownie, sprawdź na drukarce, czy wyszedł. > **Warto wiedzieć:** Nagłówek paragonu - nazwę firmy, adres i NIP - drukarka fiskalna bierze ze swojej pamięci, wpisanej przez serwisanta przy fiskalizacji. Dane sprzedawcy i nazwa wystawcy z ustawień paragonu w Ritevo są przy druku fiskalnym pomijane i nie da się ich zmienić z panelu. ## Usunięcie integracji W szczegółach drukarki w panelu kliknij **Usuń integrację** - wydruki przestaną do niej trafiać. W aplikacji usuń ją przyciskiem **Usuń** przy drukarce. ## Czego integracja nie robi - Nie drukuje faktur ani korekt na drukarce fiskalnej - tylko paragony. - Nie drukuje paragonów w innej walucie niż PLN. - Nie obsługuje drukarek fiskalnych spoza Polski ani drukarek Novitus w protokole klasycznym. ## Integracja przez API Drukarki: `GET /integrations/printers` (lista), `GET /integrations/printers/{integrationId}` (szczegóły), `GET /integrations/printers/{integrationId}/queue` (aktualna kolejka), `GET /integrations/printers/{integrationId}/history` (historia wydruków, `status`: `SUCCESS` albo `ERROR`, przy błędzie `errorType` i `errorMessage`), `GET /integrations/printers/{integrationId}/token` (token do aplikacji). Dodanie: `POST /integrations/printers`, zmiana nazwy: `PATCH /integrations/printers/{integrationId}`, usunięcie: `DELETE /integrations/printers/{integrationId}`. Wydruk etykiety: `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}` (tylko przesyłka ze `status` = `SUCCESS`), wydruk paragonu: `POST /orders/billings/{billingId}/print/{printerIntegrationId}`. W akcjach dla zamówień kroki to `PRINT_SHIPMENT_LABEL` i `PRINT_RECEIPT` w `actionSteps[].action.type` z `uuidValue` = id drukarki, a wyzwalacz **Zlecenie wydruku** to `triggerType` = `CREATE_PRINT_JOB`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Kroki druku nie należą do kroków, które czekają na zewnętrzny system: następny krok rusza zaraz po przyjęciu wydruku do kolejki albo po błędzie (w historii `status` = `ERROR`, np. gdy zamówienie nie ma przesyłki ze `status` = `SUCCESS` albo nie ma paragonu). Etykieta jest zawsze z najnowszej przesyłki ze `status` = `SUCCESS`, paragon - z najnowszego nieusuniętego dokumentu z `billingType` = `RECEIPT`. Nie ma warunku akcji na wynik wydruku. Wyzwalacz `CREATE_PRINT_JOB` startuje akcję po każdym takim wyniku, udanym i nieudanym. Odrzucenia przez aplikację (zły rodzaj drukarki, drukarka niegotowa) nie wracają do akcji. --- Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.