n8n-nodes-librus-2

Community node dla n8n umożliwiający automatyczne pobieranie danych z Librus Synergia — najpopularniejszego dziennika elektronicznego w polskich szkołach.

Pakiet łączy się z oficjalnym REST API Librusa przez autoryzację portalową OAuth2 — tak samo jak oficjalna aplikacja mobilna. Od wersji 2.2.0 obsługuje również BFF API (Backend For Frontend) — nowszy backend aplikacji mobilnej, który zwraca bogatsze dane z rozwiązanymi relacjami.

⚠️ BFF API (testbff.librus.pl) może być niedostępne. Serwer BFF jest utrzymywany przez Librus i bywa offline lub nieosiągalny. Jeśli operacja BFF zwraca błąd 502/503, przełącz API Source na Classic (Synergia API) — wszystkie podstawowe operacje (wiadomości, oceny, plan lekcji itp.) działają przez stabilne REST API api.librus.pl.

Co potrafi ten node?

9 zasobów, 34 operacje — pełna rozpiska poniżej.

| Zasób | Dostępne operacje | BFF | |-------|-------------------|:---:| | 📨 Wiadomości | Lista odebranych · Lista wysłanych · Pobierz wiadomość · Wyślij wiadomość · Usuń wiadomość · Nieprzeczytane | ✅ list | | 📊 Oceny | Lista ocen · Pobierz ocenę · Kategorie ocen · Komentarze · Oceny punktowe · Kategorie ocen punktowych | ✅ list | | 📅 Plan lekcji | Plan na wybrany tydzień (classic) / zakres dat (BFF) | ✅ | | ✅ Frekwencja | Lista obecności (z filtrami dat) · Pobierz obecność · Typy obecności | — | | 📝 Zadania domowe | Lista zadań · Pobierz zadanie · Kategorie zadań | — | | 🏫 Szkoła | Ogłoszenia · Dni wolne szkoły · Pobierz dzień wolny · Dni wolne klasy · Dni wolne nauczycieli · Kalendarz · Przedmioty · Nauczyciele · Lekcje · Wywiadówki · Zachowanie · Kolory | ✅ kalendarz | | ℹ️ Informacje | Dane konta · Dane klasy · Szczęśliwy numerek | — | | 🕐 Timeline (BFF) | Feed zdarzeń z aplikacji mobilnej (artykuły, zmiany, powiadomienia) | ✅ | | 📌 Custom Events (BFF) | Lista własnych wydarzeń z zakresu dat | ✅ |

Instalacja

n8n self-hosted

cd ~/.n8n
npm install n8n-nodes-librus-2

Zrestartuj n8n — node Librus pojawi się w liście node'ów.

n8n w Dockerze

Ustaw zmienną środowiskową i zrestartuj kontener:

environment:
  - N8N_COMMUNITY_PACKAGES=n8n-nodes-librus-2

Konfiguracja credentials

1. W n8n przejdź do Credentials → Add Credential → Librus Portal API
2. Wypełnij:

| Pole | Wymagane | Opis | |------|:--------:|------| | Email | ✅ | E-mail konta na portal.librus.pl | | Password | ✅ | Hasło do konta portalu Librus | | Refresh Token | — | Opcjonalne. Pozwala pominąć pełne logowanie przy kolejnych uruchomieniach. |

⚠️ Hasło portalu ≠ hasło Synergii! Podaj hasło, którym logujesz się na portal.librus.pl — nie hasło do dziennika Synergia. Jeśli logujesz się przez Google lub Facebook, najpierw ustaw hasło portalu w ustawieniach konta.

Przykłady użycia

Pobierz wiadomości z dziennika

| Parametr | Wartość | |----------|---------| | Resource | Messages | | Operation | List Messages | | Page | 1 | | Limit | 20 |

Pobierz wszystkie oceny

| Parametr | Wartość | |----------|---------| | Resource | Grades | | Operation | List Grades |

Plan lekcji na ten tydzień

| Parametr | Wartość | |----------|---------| | Resource | Timetable | | Operation | Get Timetable | | Week Start | (puste = bieżący tydzień) |

Szczęśliwy numerek

| Parametr | Wartość | |----------|---------| | Resource | Info | | Operation | Get Lucky Number |

Frekwencja z zakresu dat

| Parametr | Wartość | |----------|---------| | Resource | Attendance | | Operation | List Attendances | | Date From | 2026-01-01 | | Date To | 2026-03-31 |

Ogłoszenia szkolne

| Parametr | Wartość | |----------|---------| | Resource | School | | Operation | School Notices |

BFF: Wiadomości z pełnym body (jeden request)

| Parametr | Wartość | |----------|---------| | API Source | BFF (Mobile App API) | | Resource | Messages | | Operation | List Messages |

BFF: Plan lekcji z zakresu dat

| Parametr | Wartość | |----------|---------| | API Source | BFF (Mobile App API) | | Resource | Timetable | | Operation | Get Timetable | | Date From | 2026-04-14 | | Date To | 2026-04-18 |

BFF: Timeline (feed zdarzeń)

| Parametr | Wartość | |----------|---------| | API Source | BFF (Mobile App API) | | Resource | Timeline | | Operation | Get Timeline |

Pełna rozpiska operacji i parametrów

Parametry globalne

| Parametr | Typ | Domyślnie | Opis | |----------|-----|-----------|------| | Account Login | string | (puste) | Login konta Synergia (np. 12345u). Puste = pierwsze aktywne konto. Przydatne gdy jedno konto portalu ma wielu uczniów. | | API Source | options | Classic | Classic (Synergia API) — standardowe REST API. BFF (Mobile App API) — nowszy backend z bogatszymi danymi (nazwy rozwiązane inline, pełne body wiadomości). |

📨 Wiadomości (Messages)

| Operacja | Parametry | Opis | |----------|-----------|------| | List Messages | Page (number, domyślnie 1), Limit (number, domyślnie 300), After ID (number, domyślnie 0) | Lista wiadomości odebranych. After ID > 0 zwraca tylko wiadomości z ID wyższym niż podana wartość — przydatne do inkrementalnego pollingu. BFF: zwraca pełne body + imiona nadawców w jednym request (bez Page/Limit/After ID). | | List Sent | Page (number, domyślnie 1), Limit (number, domyślnie 300), After ID (number, domyślnie 0) | Lista wiadomości wysłanych (tylko Classic) | | Get Message | Message ID (string, wymagany) | Pobierz pojedynczą wiadomość po ID | | Send Message | Receiver IDs (string, wymagany), Subject (string, wymagany), Body (string, wymagany) | Wyślij nową wiadomość. Receiver IDs to lista ID użytkowników rozdzielona przecinkami. | | Delete Message | Message ID (string, wymagany) | Usuń wiadomość po ID | | Get Unread | — | Liczba nieprzeczytanych wiadomości |

ℹ️ API Librusa nie wspiera filtrowania wiadomości po datach. Filtrowanie trzeba robić w n8n (np. node IF/Filter po polu SendDate).

📊 Oceny (Grades)

| Operacja | Parametry | Opis | |----------|-----------|------| | List Grades | — | Lista wszystkich ocen. BFF: oceny pogrupowane po przedmiotach z period1Grades/period2Grades, nazwami nauczycieli i kategoriami inline. | | Get Grade | Grade ID (string, wymagany) | Pobierz pojedynczą ocenę po ID | | List Categories | — | Lista kategorii ocen | | List Comments | — | Lista komentarzy do ocen | | Point Grades | — | Lista ocen punktowych | | Point Grade Categories | — | Lista kategorii ocen punktowych |

📅 Plan lekcji (Timetable)

| Operacja | Parametry | Opis | |----------|-----------|------| | Get Timetable | Classic: Week Start (string, opcjonalny). BFF: Date From (dateTime, wymagany), Date To (dateTime, wymagany) | Classic: plan na tydzień (YYYY-MM-DD, puste = bieżący). BFF: płaska lista lekcji z zakresu dat z nazwami przedmiotów i nauczycieli inline. |

✅ Frekwencja (Attendance)

| Operacja | Parametry | Opis | |----------|-----------|------| | List Attendances | Date From (dateTime, opcjonalny), Date To (dateTime, opcjonalny) | Lista obecności. Daty opcjonalne — puste = wszystkie. | | Get Attendance | Attendance ID (string, wymagany) | Pobierz pojedynczy wpis obecności po ID | | List Types | — | Lista typów obecności (obecny, nieobecny, spóźniony itp.) |

📝 Zadania domowe (Homework)

| Operacja | Parametry | Opis | |----------|-----------|------| | List Homework | — | Lista wszystkich zadań domowych | | Get Homework | Homework ID (string, wymagany) | Pobierz pojedyncze zadanie po ID | | List Categories | — | Lista kategorii zadań domowych |

🏫 Szkoła (School)

| Operacja | Parametry | Opis | |----------|-----------|------| | School Notices | — | Lista ogłoszeń szkolnych | | School Free Days | — | Lista dni wolnych szkoły | | Get School Free Day | Free Day ID (string, wymagany) | Pobierz dzień wolny po ID | | Class Free Days | — | Lista dni wolnych klasy | | Teacher Free Days | — | Lista dni wolnych nauczycieli | | Calendar | Classic: brak parametrów. BFF: Date From (dateTime, wymagany), Date To (dateTime, wymagany) | Classic: przegląd kalendarza. BFF: schoolFreeDays + teacherFreeDays w jednym response z filtrem miesięcy. | | Subjects | — | Lista wszystkich przedmiotów | | Teachers (Users) | — | Lista użytkowników (nauczyciele, rodzice) | | Lessons | — | Lista definicji lekcji | | Parent-Teacher Conferences | — | Lista zaplanowanych wywiadówek | | Behaviour Grades | — | Lista punktów z zachowania | | Colors | — | Lista definicji kolorów używanych w systemie |

ℹ️ Informacje (Info)

| Operacja | Parametry | Opis | |----------|-----------|------| | Get Account Info | — | Dane zalogowanego konta | | Get Classes | — | Dane klasy ucznia | | Get Lucky Number | — | Dzisiejszy szczęśliwy numerek |

🕐 Timeline (BFF only)

| Operacja | Parametry | Opis | |----------|-----------|------| | Get Timeline | — | Feed zdarzeń z aplikacji mobilnej — artykuły, zmiany ocen, nowe wiadomości itp. Wymaga API Source = BFF. Używa metody HTTP QUERY. |

📌 Custom Events (BFF only)

| Operacja | Parametry | Opis | |----------|-----------|------| | List Custom Events | Date From (dateTime, wymagany), Date To (dateTime, wymagany) | Lista własnych wydarzeń użytkownika z podanego zakresu dat. Wymaga API Source = BFF. |

Wymagania

• n8n ≥ 1.0
• Node.js ≥ 18
• Aktywne konto na portal.librus.pl z dostępem do Synergii

Dlaczego ten pakiet?

Istniejący pakiet n8n-nodes-librus-synergia przestał działać — opierał się na scrapingu HTML i nieaktualnym kluczu OAuth. Ten pakiet rozwiązuje problem od podstaw:

| | n8n-nodes-librus-synergia | n8n-nodes-librus-2 | |-|:---------------------------:|:--------------------:| | Autoryzacja | HTML scraping | Portal OAuth2 | | Pobieranie danych | Web scraping | REST API + BFF API | | Wiadomości | ❌ nie działa | ✅ (z pełnym body w BFF) | | Odporność na zmiany UI | ❌ | ✅ | | Odświeżanie sesji | ❌ | ✅ automatyczne | | Oceny z nazwami przedmiotów | ❌ | ✅ (BFF) | | Plan lekcji z zakresem dat | ❌ | ✅ (BFF) |

Licencja

MIT

Autor

bbijoch

Pochodzenie

Ten pakiet jest forkiem (przepisanym od zera) pakietu n8n-nodes-librus-synergia. Oryginalny pakiet przestał działać z powodu zmian w API Librusa — ta wersja zastępuje HTML scraping nowym podejściem opartym o portal OAuth2 i oficjalne REST API.