API

api/README.md

@@ -43,6 +43,30 @@ return [
 ];
 ```
 
+### Akademia Wodociągowca (harmonogram w sekcji 04)
+
+Tabela terminów na stronie głównej i na `szkolenia.html` pobiera webinary
+i kursy z publicznego API Akademii. Dopisz klucz wygenerowany w panelu
+Akademii (Ustawienia -> Klucze API - pokazywany tylko raz):
+
+```php
+// wariant ze stałymi
+define('SOFTSPM_AKADEMIA_API_KEY', 'tutaj_klucz_z_panelu_akademii');
+
+// wariant z tablicą
+'softspm_akademia_api_key' => 'tutaj_klucz_z_panelu_akademii',
+```
+
+Adres API domyślnie to `https://akademiawodociagowca.pl/api/public/v1`.
+Zmieniasz go tylko wtedy, gdy instancja stoi pod innym adresem:
+
+```php
+define('SOFTSPM_AKADEMIA_API_URL', 'https://inna-domena/api/public/v1');
+```
+
+Bez tego klucza nic się nie psuje: `api/schedule.php` zwraca
+`source: "error"`, a w tabeli zostają statyczne wiersze wpisane w HTML.
+
 ### Wpisy opcjonalne
 
 ```php
@@ -145,7 +169,44 @@ szablon endpointu nie zamienia `\n` na `<br>`. `send_email_api.php` jest wasz,
 więc najczystszą poprawką jest tam jedno `nl2br()` na sanityzowanej treści -
 nic po stronie tej strony nie wymaga wtedy zmian.
 
-## 5. Zabezpieczenia przed botami
+## 5. Harmonogram z Akademii Wodociągowca
+
+[schedule.php](schedule.php) pobiera `GET /webinars` i `GET /courses` z API
+Akademii (dokumentacja: `akademiawodociagowca/docs/api_public_v1.html`), scala
+je w jedną listę i oddaje stronie jako JSON. Klucz `X-API-Key` zostaje na
+serwerze - punkt 9 dokumentacji Akademii wprost tego wymaga.
+
+- **Cache:** odpowiedź leży w `api/storage/cache/schedule.json` przez
+  `akademia_cache_ttl` (domyślnie 300 s, zgodnie z zaleceniem 1-5 minut).
+  Pusty wynik i błąd trzymane są krócej, maksymalnie minutę.
+- **Kolejność:** webinary z terminem rosnąco, potem kursy na żądanie.
+- **Linki:** akceptujemy wyłącznie adresy prowadzące do domeny Akademii -
+  gdyby API zwróciło cokolwiek innego, link jest pomijany.
+- **Limit:** `?limit=` (1-40). Strona główna prosi o 8 pozycji,
+  `szkolenia.html` o 12.
+
+Odpowiedź ma pole `source`:
+
+| `source` | Znaczenie | Co widzi użytkownik |
+|---|---|---|
+| `api` | Są pozycje | Tabela, nagłówki i notatka podmienione na dane z Akademii; kolumna wraca z „Termin" na „Data" |
+| `empty` | API odpowiedziało pustą tablicą | Statyczne wiersze z HTML-a zostają nietknięte |
+| `error` | Brak klucza albo API nie odpowiada | Jak wyżej |
+
+Statyczne wiersze to pełnoprawny plan awaryjny: działają bez JavaScriptu,
+bez klucza i przy niedostępnym API. Strona nigdy nie pokazuje pustej tabeli.
+Są w `index.html` (8 pozycji) i `szkolenia.html` (11 pozycji) - jeśli chcesz
+zmienić te tematy zastępcze, edytujesz je wprost w HTML.
+
+Test:
+
+```bash
+curl -s "https://softspm.com/api/schedule.php?limit=5" | head -c 400
+```
+
+Oczekiwane: `{"ok":true,"source":"api",...}` z tablicą `items`.
+
+## 6. Zabezpieczenia przed botami
 
 Suwak sam z siebie niczego nie gwarantuje - jest elementem interfejsu, a nie
 kryptografią. Blokady, które faktycznie odsiewają automaty, działają na
@@ -166,7 +227,7 @@ Jeśli mimo to zacznie przechodzić spam, następnym krokiem jest Cloudflare
 Turnstile albo hCaptcha - obie działają na tej samej zasadzie co obecny token,
 więc podmiana dotknie tylko `send.php` i `assets/forms.js`.
 
-## 6. Test po wdrożeniu
+## 7. Test po wdrożeniu
 
 ```bash
 # 1. Token - powinien zwrócić {"ok":true,"token":"t.szkolenia...."}