Integracje — Konfiguracja krok po kroku

Praktyczny przewodnik po konfigurowaniu kazdej integracji zewnetrznej w SerwisRun — OAuth, tokeny API, klucze, webhooki. Zawiera wszystkie kroki z wyjasnieniem co robic i gdzie szukac wartosci.

Glowny ekran konfiguracji: Panel Administracyjny → Integracje (/settings/integrations) — 5 zakladek: Email i Kalendarz / Cloud Storage / Sztuczna inteligencja / KSeF / Integracje dostawcow. Kazda zakladka ma przycisk „Testuj polaczenie".

1 Google Calendar

Ekran konfiguracji integracji dane zanonimizowane — 5 zakladek.

Cel: Automatyczne tworzenie zdarzen w kalendarzu technikow dla konserwacji / interwencji. Wykrywanie konfliktow (FreeBusy API). Synchronizacja statusow.

Model integracji

Shared OAuth2 — jedno konto Google autoryzowane przez admina. Per-technik kalendarz przez pole users.google_calendar_email. Technik musi udostepnic swoj kalendarz kontu systemowemu z uprawnieniem „Wprowadzanie zmian w wydarzeniach".

Krok po kroku

Etap A: Utworzenie projektu w Google Cloud Console

1. 1Przejdz do console.cloud.google.com
2. 2Utworz nowy projekt (np. „SerwisRun-Prod")
3. 3W menu bocznym wybierz APIs & Services → Library
4. 4Wlacz nastepujace API:
   • Google Calendar API
   • Google People API (opcjonalne — dla kontaktow)
   • Admin SDK (dla avatarow z Directory)

Etap B: Utworzenie OAuth Client ID

1. 1Menu boczne → APIs & Services → Credentials
2. 2Klik „Create Credentials" → OAuth 2.0 Client ID
3. 3Application type: Web application
4. 4Authorized redirect URIs: https://api.serwis.cloud/api/settings/integrations/google/callback
5. 5Skopiuj Client ID i Client Secret

Etap C: Konfiguracja w SerwisRun

1. 1Zaloguj jako admin → Panel Administracyjny → Integracje → Email i Kalendarz
2. 2Wklej Client ID i Client Secret
3. 3Klik „Autoryzuj z Google" → nastepuje redirect na ekran zgody Google
4. 4Zaloguj sie kontem systemowym (np. [email protected]) i zatwierdz scope
5. 5Powrot do SerwisRun → status: „Polaczono"
6. 6Klik „Testuj polaczenie" → test kalendarza (POST /settings/integrations/test-calendar)

Etap D: Udostepnienie kalendarzy przez technikow

1. Technik loguje sie do calendar.google.com
2. Ustawienia → Konkretny kalendarz → „Udostepnij wybranym osobom"
3. Dodaje adres systemowy z uprawnieniem „Dokonywanie zmian w wydarzeniach"
4. Admin w SerwisRun: Uzytkownicy → edycja uzytkownika → pole google_calendar_email → wpisuje adres email technika

2 Google Drive (cloud storage)

Cel: Przechowywanie zalacznikow (skany umow, protokoly PDF, zdjecia z napraw) w strukturze SerwisRun/{moduł}/{identyfikator}/.

Konfiguracja

1. 1W Google Cloud Console (ten sam projekt) wlacz Google Drive API
2. 2Utworz Service Account:
   • APIs & Services → Credentials → „Create Service Account"
   • Nadaj role roles/storage.objectAdmin
   • Utworz klucz JSON → pobierz plik
3. 3W SerwisRun: Integracje → Cloud Storage → Google Drive
4. 4Wybierz providera: „Google Drive"
5. 5Wklej zawartosc pliku JSON (credentials) w pole „Service Account JSON"
6. 6Utworz w Google Drive folder SerwisRun i udostepnij go service accountowi (z email z pliku JSON) jako „Editor"
7. 7Klik „Testuj polaczenie" — system utworzy testowy plik

Struktura folderow

SerwisRun/
├── Kosztorysy/{Skrocona_nazwa_klienta}/{rok}/
├── Umowy/{klient}/{rok_startu}/{nr_umowy}/{kategoria}/
├── Protokoly konserwacji/{klient}/{rok}/
├── Protokoly naprawy/{klient}/{rok}/
├── Zgloszenia/{klient}/{rok}/{nr_zgloszenia}/
├── Klienci/{klient}/{rok}/
├── Kadry/{Imie Nazwisko}/
├── Samochody/{nr_rejestracyjny}/
└── Obiekty-Materialy/
    ├── Wyposazenie/{kategoria}/
    └── Materialy/{kategoria}/

3 Gmail API (wysylka emaili)

Cel: Wysylka protokolow, kosztorysow, powiadomien o fakturach przez Gmail API (zamiast SMTP).

1. 1Wlacz Gmail API w Google Cloud Console (ten sam projekt co Calendar)
2. 2Uzyj istniejacego OAuth Client ID (z kroku 1.B)
3. 3W SerwisRun: Integracje → Email i Kalendarz → Gmail
4. 4Klik „Autoryzuj" — dodaje scope https://www.googleapis.com/auth/gmail.send
5. 5Ustaw adres wysylajacy (from_email) — moze byc alias (wymaga konfiguracji w ustawieniach Gmaila „Send mail as...")
6. 6Test: „Wyslij testowy email"

4 Google Contacts (People API)

Cel: Import i eksport kontaktow z Google Contacts — synchronizacja z baza contacts w SerwisRun.

1. 1Wlacz People API w Google Cloud Console
2. 2W SerwisRun: Kontakty → Import/Eksport → „Z Google Contacts"
3. 3Klik „Autoryzuj" — dodaje scope contacts.readonly / contacts (dla eksportu)
4. 4Wybierz kontakty do importu (checkbox na liscie)
5. 5Klik „Importuj" — system dopasowuje po email, tworzy lub aktualizuje rekordy

5 OneDrive (Microsoft 365)

Cel: Alternatywa do Google Drive — przechowywanie dokumentow w OneDrive (konto firmowe lub osobiste).

Krok po kroku

1. 1Przejdz do portal.azure.com (Azure Portal)
2. 2Azure Active Directory → App Registrations → New registration
3. 3Nazwa: „SerwisRun", Redirect URI: https://api.serwis.cloud/api/settings/integrations/microsoft/callback
4. 4Po utworzeniu: sekcja API Permissions → dodaj:
   • Files.ReadWrite.All
   • User.Read
   • offline_access (dla refresh tokenow)
5. 5Sekcja Certificates & secrets → utworz „Client secret" → skopiuj wartosc (jednorazowo widoczna!)
6. 6Skopiuj Application (client) ID i Directory (tenant) ID
7. 7W SerwisRun: Integracje → Cloud Storage → OneDrive
   • Wklej Client ID, Tenant ID, Client Secret
   • Klik „Autoryzuj z Microsoft"
   • Zaloguj kontem firmowym (np. [email protected])
8. 8Klik „Testuj polaczenie" — system tworzy folder SerwisRun/

6 Outlook Contacts (Microsoft Graph)

Cel: Import/eksport kontaktow z Outlook przez Microsoft Graph API.

1. 1Uzyj istniejacej rejestracji Azure AD (z kroku 5)
2. 2Dodaj scope Contacts.ReadWrite w API Permissions
3. 3W SerwisRun: Kontakty → Import/Eksport → „Z Outlook"
4. 4Reszta jak przy Google Contacts

7 Google Maps (Directions + Geocoding)

Cel: Kalkulacja rzeczywistej odleglosci drogowej i czasu dojazdu miedzy oddzialem a obiektem. Geokodowanie adresow do wspolrzednych GPS.

Wymagane API

• Directions API — trasa i czas dojazdu
• Geocoding API — adres → GPS
• Maps JavaScript API — map w przegladarce (opcjonalne)
• Distance Matrix API — wiele par adresow naraz
• Places API (New) — autocomplete adresow

Krok po kroku

1. 1W Google Cloud Console wlacz powyzsze API
2. 2APIs & Services → Credentials → „Create Credentials" → API Key
3. 3Zabezpiecz klucz: „Restrict Key" → ograniczenie do wybranych API + ograniczenia HTTP referrer (np. *.serwis.cloud/*)
4. 4W SerwisRun: Integracje → Google Maps → wklej klucz
5. 5Klik „Testuj polaczenie" — wykonuje testowa trase Warszawa → Krakow
6. 6Ustaw GPS oddzialow: Dane firmy → Oddzialy → Wspolrzedne GPS

Uzycie w systemie

Przy tworzeniu/edycji obiektu serwisowego (/service-sites) pole „Odleglosc z oddzialu" pokazuje przycisk „Oblicz". Po klikniciu:

1. System geokoduje adres obiektu → GPS (service_sites.latitude/longitude)
2. Wyznacza trase z GPS oddzialu do GPS obiektu (Directions API)
3. Zapisuje distance_to_branch_km i travel_time_minutes
4. Wyswietla badge: „trasa drogowa" (zielony) lub „szacunek" (niebieski — fallback Haversine)

8 NIP Lookup + Biala Lista VAT (MF)

Cel: Pobieranie danych podatnika po NIP z Ministerstwa Finansow. Weryfikacja statusu VAT (aktywny / nieaktywny).

API

• Endpoint: https://wl-api.mf.gov.pl/api/search/nip/{nip}
• Autoryzacja: BRAK — publiczne API
• Limit: 10 zapytan / minute

Konfiguracja

Nic nie trzeba konfigurowac! NIP Lookup dziala od razu. System wywoluje API z backendu — brak ryzyka ujawnienia kluczy.

Uzycie

W kreatorze klienta (/clients/wizard) i dostawcy (/suppliers/wizard) pole NIP ma przycisk „Pobierz z MF":

1. Wpisz NIP (10 cyfr)
2. Klik „Pobierz z MF"
3. System wypelnia: nazwe pelna, nazwe skrocona, adres, REGON, KRS, status VAT, numer konta bankowego
4. Badge statusu: Aktywny VAT / Nieaktywny VAT

9 KSeF — Krajowy System e-Faktur

Cel: Wysylka faktur wystawionych do KSeF. Import faktur zakupu z KSeF. Od 2026-07 obowiazkowe dla duzych podatnikow.

Srodowiska

Uwierzytelnianie — 2 opcje

Opcja A — Token autoryzacyjny (latwiejsze)

1. 1Zaloguj sie do KSeF przez Profil Zaufany lub certyfikat kwalifikowany
2. 2Wygeneruj token autoryzacyjny
3. 3Skopiuj token
4. 4W SerwisRun: Integracje → KSeF → wklej token + NIP firmy

Opcja B — Certyfikat kwalifikowany (produkcja wiekszych firm)

1. 1Uzyj certyfikatu od zaufanego dostawcy (np. Certum, KIR)
2. 2Wykonaj initSessionSigned na endpoint KSeF z podpisem XML XAdES
3. 3Otrzymasz SessionToken waznie ~2h
4. 4W SerwisRun: upload certyfikatu jako .p12/.pfx + haslo

10 Claude API (Anthropic)

Cel: Wszystkie funkcje AI w systemie — chatbot, kategoryzacja zgloszen, generowanie protokolow, kosztorysy, analiza dokumentow, identyfikacja materialow (vision).

Krok po kroku

1. 1Zaloz konto na console.anthropic.com
2. 2Dodaj metode platnosci (karta kredytowa)
3. 3API Keys → Create Key
4. 4Skopiuj klucz (format: sk-ant-api03-...)
5. 5W SerwisRun: Integracje → Sztuczna inteligencja → Claude API
   • Wklej ANTHROPIC_API_KEY
   • Ustaw AI_DAILY_TOKEN_LIMIT (domyslnie 100 000)
   • Ustaw AI_DAILY_REQUEST_LIMIT (domyslnie 50)
6. 6Klik „Testuj polaczenie" — wysyla probne zapytanie

Modele uzywane

11 Delta-Poznan (katalog dystrybutora)

Import katalogu Delta-Poznan — mapowanie kategorii, SSE progress.

Cel: Import katalogu ~10 000 produktow z dystrybutora Delta-Poznan. Synchronizacja stanow magazynowych i cen zakupu.

Wymagania

• Konto B2B w Delta-Poznan (sklep.delta.poznan.pl)
• Token API (wymagany kontakt z opiekunem handlowym)

Krok po kroku

1. 1W SerwisRun: Integracje → Integracje dostawcow → Delta-Poznan
2. 2Wklej token API (Bearer)
3. 3Klik „Testuj polaczenie"
4. 4Przejdz do Ustawienia → Import Delta
5. 5Krok A — Mapowanie kategorii:
   • Klik „Pobierz kategorie" → lista kategorii Delta
   • Klik „AI auto-mapowanie" (opcjonalne) → Claude sugeruje mapowania
   • Recznie przypisz kazda kategorie Delta do lokalnej material_categories
   • Zapisz mapowanie
6. 6Krok B — Import katalogu:
   • Wybierz kategorie do importu (checkbox)
   • Klik „Importuj" → SSE progress bar (XML streaming ~155MB)
   • Czas: 10-20 min dla pelnego katalogu
7. 7Krok C — Synchronizacja stanow i cen:
   • Klik „Synchronizuj stany i ceny"
   • Trwa ~2-3 min
   • Automatyczna synchronizacja raz dziennie o 2:00 (opcja „delta_auto_sync")

12 WebAuthn / FIDO2 (biometria)

Cel: Logowanie biometryczne (odcisk palca, Face ID, YubiKey, passkey).

Konfiguracja

Nic nie trzeba konfigurowac w Integracjach! WebAuthn dziala od razu, bo RP ID jest derywowany z FRONTEND_URL (np. app.serwis.cloud).

Rejestracja urzadzenia przez uzytkownika

1. Uzytkownik loguje sie (haslem)
2. Przechodzi do Ustawienia systemu → „Logowanie biometryczne"
3. Klik „Dodaj urzadzenie"
4. Przegladarka pyta o biometrie (odcisk / Face ID / PIN)
5. Urzadzenie rejestruje sie w webauthn_credentials

Logowanie biometryczne

1. Na ekranie logowania uzytkownik wpisuje email
2. Po blur system sprawdza POST /webauthn/check
3. Jesli email ma zarejestrowane urzadzenie → wyswietlany przycisk „Zaloguj biometrycznie"
4. Klik → autoryzacja biometryczna → JWT

13 Web Push Notifications (VAPID)

Cel: Powiadomienia push do technikow o nowych interwencjach, wygasnieciu SLA, pilnych zgloszeniach.

Generowanie kluczy VAPID

1. 1Na serwerze: npx web-push generate-vapid-keys
2. 2Skopiuj Public Key i Private Key
3. 3W SerwisRun: Integracje → Powiadomienia push
   • vapid_public_key: public key
   • vapid_private_key: private key
   • vapid_email: mailto:[email protected]
4. 4Zapisz

Subskrypcja przez uzytkownika

1. Uzytkownik na aplikacji mobilnej (/mobile) otrzymuje prompt „Chcesz otrzymywac powiadomienia?"
2. Klik „Tak" → subscribe z public key → zapis do push_subscriptions
3. Serwer moze teraz wysylac powiadomienia przez webPush.service.sendPushToUser()

Monitorowanie i diagnostyka

Zarzadzanie backupami (Cloudflare R2) — status, lista, diagnostyka env.

Modul Import/Eksport — szablon Excel z dropdownami, podglad, tryby.

Gdzie szukac bledow?

Odswiezanie tokenow OAuth

Tokeny Google i Microsoft wygasaja. System automatycznie odswieza przez googleAuth.helper.ts uzywajac refresh tokenow. Jesli jednak uzytkownik cofnie zgode (revoke) → konieczna ponowna autoryzacja:

1. Status „Rozlaczono" w Integracjach
2. Klik „Autoryzuj ponownie"