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
- W n8n przejdź do Credentials → Add Credential → Librus Portal API
- 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
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.
