Integracje Systemu SerwisRun

Ten dokument opisuje w przystępny sposób, z jakimi zewnętrznymi usługami współpracuje system SerwisRun, jak wymienia z nimi dane i jak te połączenia są zabezpieczone.

Mapa integracji — co z czym się łączy?

1 Google Calendar — Harmonogram konserwacji

Co robi ta integracja?

Gdy w systemie zaplanowana jest konserwacja, automatycznie pojawia się ona w kalendarzu Google przypisanego technika. Technik widzi swoje zadania w telefonie, na zegarku, w przeglądarce — wszędzie, gdzie korzysta z Google Calendar.

Jak to działa w praktyce?

Wykrywanie konfliktów

Przed dodaniem wydarzenia system sprawdza, czy technik nie jest zajęty w tym terminie (przez mechanizm Google FreeBusy). Jeśli wykryje konflikt:

• Wydarzenie i tak zostaje utworzone, ale z oznaczeniem ⚠️ w tytule
• Koordynator otrzymuje listę konfliktów z datami i godzinami
• Może zdecydować, czy przesunąć termin, czy zaakceptować nakładkę

Zabezpieczenia

Porównanie: To ten sam mechanizm autoryzacji OAuth2, jakiego używają aplikacje typu Calendly, Zoom, czy Slack do integracji z Google Calendar. Używa oficjalnego SDK Google — nie jest to „obejście" czy niestandardowe rozwiązanie.

2 Wysyłka e-mail (Gmail / SMTP / Resend)

Co robi ta integracja?

System wysyła e-maile w Twoim imieniu — np. protokoły konserwacji do klientów, przypomnienia o terminach, potwierdzenia rejestracji. Obsługuje trzy niezależne kanały wysyłki w hierarchii awaryjnej:

Próba 1: Resend API  ──(jeśli skonfigurowany)──▸ wysłane ✓
    │ (niedostępny)
    ▼
Próba 2: Gmail API   ──(jeśli autoryzowany)────▸ wysłane ✓
    │ (niedostępny)
    ▼
Próba 3: SMTP        ──(serwer pocztowy)───────▸ wysłane ✓

Czym różnią się te kanały?

Co można wysyłać?

• Protokoły konserwacji w formacie PDF (jako załącznik)
• Powiadomienia o zgłoszeniach serwisowych
• Linki do resetowania hasła
• Potwierdzenia rejestracji konta
• Kosztorysy i oferty

Zabezpieczenia

Porównanie: Trzypoziomowy fallback to rozwiązanie stosowane w systemach klasy enterprise (np. Salesforce, HubSpot). Większość prostszych systemów obsługuje tylko jeden kanał — jeśli nie działa, e-maile nie wychodzą.

3 Google Contacts — Import i eksport kontaktów

Co robi ta integracja?

Umożliwia dwukierunkową synchronizację kontaktów między systemem SerwisRun a kontaktami Google:

Jakie dane są synchronizowane?

Zabezpieczenia

• OAuth2 — te same zabezpieczenia co Calendar i Gmail (wspólna autoryzacja Google)
• Kontrola tempa — system wysyła max 90 kontaktów na minutę (respektuje limity Google)
• Filtrowanie pustych — kontakty bez imienia, nazwiska lub e-maila są pomijane
• Zdjęcia kontaktów — system może pobrać zdjęcie profilowe z katalogu firmowego Google Workspace

Porównanie: Synchronizacja kontaktów na poziomie People API to ten sam mechanizm, jakiego używają CRM-y (HubSpot, Pipedrive) i komunikatory (WhatsApp Business).

4 Microsoft Outlook Contacts — Import i eksport kontaktów

Co robi ta integracja?

Analogicznie do Google Contacts, ale dla użytkowników Microsoft 365 / Outlook.

Zabezpieczenia

• OAuth2 przez Azure AD — autoryzacja Microsoft z pełnym bezpieczeństwem korporacyjnym
• Microsoft Graph API — oficjalne API Microsoft (nie web scraping)
• MSAL — oficjalna biblioteka Microsoft do uwierzytelniania

Porównanie: To ten sam mechanizm integracji, jakiego używają aplikacje z Microsoft AppSource (marketplace) — Dynamics 365, Teams, Power Automate.

5 OneDrive — Przechowywanie plików w chmurze

Co robi ta integracja?

Protokoły, załączniki umów, zdjęcia materiałów i inne pliki są przechowywane na Microsoft OneDrive zamiast na serwerze aplikacji. Daje to:

• Bezpieczeństwo — pliki chronione przez Microsoft (szyfrowanie, backupy, georedundancja)
• Dostępność — pliki dostępne z dowolnego urządzenia
• Pojemność — nie obciąża serwera aplikacji

Jak wygląda struktura plików?

Zabezpieczenia przesyłania plików

Obsługa dużych plików

Plan awaryjny

Jeśli OneDrive jest chwilowo niedostępny (awaria Microsoft, brak internetu na serwerze):

• Plik jest automatycznie konwertowany i zapisywany w bazie danych systemu
• Użytkownik nie odczuwa różnicy — plik jest normalnie dostępny
• Po przywróceniu OneDrive system wraca do normalnego trybu

Porównanie: Mechanizm OAuth2 + MSAL + Graph API to dokładnie ten sam sposób, w jaki Microsoft Teams, SharePoint i Power Automate komunikują się z OneDrive. System nie przechowuje hasła do konta Microsoft — używa tokenów, które administrator może w każdej chwili odwołać w panelu Azure AD.

6 Google Drive — Alternatywna chmura plików

Co robi ta integracja?

Identyczna funkcjonalność jak OneDrive, ale dla firm korzystających z Google Workspace zamiast Microsoft 365. Administrator wybiera w ustawieniach systemu, którego dostawcę chmury używać:

Porównanie: Scope drive.file oznacza, że system nie ma dostępu do żadnych Twoich prywatnych plików na Google Drive — widzi wyłącznie pliki, które sam utworzył. To jak klucz do jednego pokoju w biurowcu, nie do całego budynku.

7 KSeF — Krajowy System e-Faktur

Co to jest KSeF?

KSeF to rządowy system elektronicznych faktur prowadzony przez Ministerstwo Finansów RP. Od 2026 roku wszystkie firmy w Polsce będą zobowiązane do wystawiania faktur przez KSeF.

Co robi ta integracja?

Zabezpieczenia

Porównanie: Integracja z KSeF jest wymagana prawnie dla firm w Polsce. SerwisRun implementuje ją zgodnie ze specyfikacją Ministerstwa Finansów. Wiele mniejszych systemów serwisowych wymaga ręcznego logowania do portalu KSeF — tutaj wszystko dzieje się automatycznie z poziomu aplikacji.

8 Sztuczna inteligencja (Anthropic Claude)

Co robi ta integracja?

System wykorzystuje sztuczną inteligencję Claude (firmy Anthropic) do wspomagania codziennej pracy. AI nie podejmuje decyzji — sugeruje, a użytkownik zatwierdza lub modyfikuje propozycje.

Dostępne funkcje AI

Jak AI widzi Twoje dane?

Chatbot AI ma dostęp do danych w systemie, ale z pełnym respektowaniem uprawnień:

Pracownik oddziału Poznań pyta: „Pokaż klientów"
    → AI widzi TYLKO klientów oddziału Poznań (filtr oddziałowy)

Administrator pyta: „Pokaż klientów"
    → AI widzi wszystkich klientów (pełny dostęp)

Limity i kontrola kosztów

Porównanie: AI w SerwisRun to asystent, nie autopilot. W odróżnieniu od prostych chatbotów, tutaj AI ma kontekstowy dostęp do danych systemu z pełnym RBAC. To podejście stosowane w systemach enterprise — np. Salesforce Einstein, Microsoft Copilot, ServiceNow Virtual Agent.

9 API Ministerstwa Finansów — Weryfikacja NIP

Co robi ta integracja?

Przy dodawaniu nowego dostawcy wystarczy wpisać numer NIP — system automatycznie pobierze z rejestru Ministerstwa Finansów pełną nazwę firmy, numer REGON i adres siedziby.

Porównanie: To ta sama baza danych „Biała Lista VAT", z której korzystają systemy księgowe (Optima, Symfonia, wFirma) i banki do weryfikacji kontrahentów.

10 WebAuthn / FIDO2 — Logowanie biometryczne

Co robi ta integracja?

Umożliwia logowanie do systemu bez hasła — za pomocą odcisku palca, rozpoznawania twarzy, klucza USB lub passkey.

Zabezpieczenia

Porównanie: WebAuthn/FIDO2 to najwyższy dostępny standard logowania, stosowany przez Google, Apple, Microsoft, banki (ING, mBank) i organizacje rządowe. Jest uznawany za odporny na phishing.

11 PWA — Aplikacja mobilna bez instalacji ze sklepu

Co to jest?

SerwisRun działa jako Progressive Web App — to strona internetowa, która zachowuje się jak natywna aplikacja mobilna: ikona na pulpicie, pełny ekran, tryb offline, powiadomienia push. Instalacja jednym kliknięciem — bez App Store.

Widok mobilny technika

• Przycisk „Jadę" / „Na miejscu" / „Pracuję" / „Przerwa" / „Wracam" (maszyna stanów)
• Harmonogram dnia z listą zadań
• Kreator zgłoszeń serwisowych (4 kroki)
• Skaner kodów EAN (kamerą telefonu)
• Rejestracja czasu pracy i przebiegu

Porównanie: PWA to technologia stosowana przez Twitter, Pinterest, Starbucks, Uber. Łączy wygodę aplikacji mobilnej z prostotą aktualizacji strony internetowej (bez czekania na zatwierdzenie w App Store).

12 VoIP — Click-to-Call (IPfon i kompatybilne)

Co to robi: operator klika ikonę słuchawki obok numeru klienta — system inicjuje połączenie przez API VoIP (telefon operatora dzwoni, po odebraniu łączy się z klientem). Pełna historia połączeń trafia do bazy.

Jak to działa

1. Wpisanie tokenu API w Ustawieniach → Integracje → VoIP.
2. Każdy użytkownik dostaje numer wewnętrzny (`voip_extension`) — w Ustawieniach.
3. Klik „zadzwoń" w karcie klienta lub zgłoszenia → wywołanie `POST /click2call` z bearer token.
4. Provider wysyła webhook ze statusem (`connected` / `ended` / `failed`) — system potwierdza HMAC-SHA256.
5. Pełna historia w panelu Administracyjnym → Historia VoIP (filtry: data, operator, status).

Bezpieczeństwo webhooka

Webhook jest publicznym endpointem (provider nie ma naszego JWT), dlatego wymaga podpisu:

• HMAC-SHA256 — provider podpisuje payload sekretem; system weryfikuje zgodność (timing-safe).
• Plain shared secret — alternatywa dla providerów bez HMAC; sekret w nagłówku `X-Webhook-Secret`.
• Token API i sekret webhooka zaszyfrowane AES-256-GCM w bazie.

Porównanie: click-to-call w polskich systemach CRM rzadko wychodzi poza Twilio (zagraniczne, droższe). My obsługujemy IPfon (Polska) i kompatybilne — taniej w skali całego zespołu serwisowego.

13 Centralny dispatcher SMS (5 etapów pracy)

Co to robi: automatyczne SMS-y do klientów na 5 kluczowych etapach pracy serwisu, bez ręcznego wysyłania:

1. Zgłoszenie utworzone — informacja do klienta z numerem zgłoszenia.
2. Kosztorys wysłany — link do akceptacji online (1 klik).
3. Faktura wystawiona — link do akceptacji szkicu przed PDF.
4. Protokół naprawy do akceptacji — link do podpisu zdalnego.
5. Praca zakończona — informacja o gotowości do odbioru.

Jak to działa

Każdy event ma osobny szablon (z placeholderami `{{client_name}}`, `{{ticket_number}}`, `{{link}}` itp.) edytowalny przez admina w panelu. Dyspozytor / system woła dispatchNotification(eventCode, params) — backend automatycznie:

1. Sprawdza konfigurację kanałów (email/SMS/portal — admin może wyłączyć dowolny per event).
2. Pobiera szablon dla eventu i języka.
3. Renderuje treść z parametrami i wysyła przez SMSAPI.pl (z normalizacją numeru +48 → 48).
4. Loguje status w `notification_event_log`.

Wartość: zamiast każdy moduł miał własną kopię logiki SMS — jest jeden dispatcher. Konfiguracja kanałów (kiedy SMS, kiedy email, kiedy in-app) tylko w panelu admina.

14 Cenniki dostawców — szablony + AI kategoryzacja

Co to robi: import cenników od dostawców (XLSX / XLS / XLSB / ODS / PDF) bez ręcznego mapowania kolumn za każdym razem. Każdy dostawca ma własny szablon cennika — „przepis" mówiący systemowi, gdzie szukać indeksu, nazwy, ceny i EAN-u w pliku.

Jak to działa

1. Admin wgrywa plik na Panel Administracyjny → Integracje → Cenniki dostawców.
2. System wybiera odpowiedni szablon (np. „Satel — cennik handlowy"), wczytuje arkusz i mapuje kolumny zgodnie z konfiguracją.
3. AI Claude Haiku przypisuje kategorię materiału (np. „Centrale alarmowe", „Klawiatury") na podstawie nazwy — w paczkach po 50 wierszy.
4. Tryb dry-run pokazuje co zostanie dodane / zaktualizowane / pominięte — bez zapisu do bazy.
5. Po akceptacji — UPSERT po kluczu (dostawca, kod katalogowy) lub EAN. Istniejący materiał aktualizowany, nowy tworzony.
6. Historia każdego importu w supplier_pricelist_imports (status, ile dodano/zaktualizowano/pominięto, lista błędów per wiersz).

Wsparte formaty i waluty

Aktualnie wspierani dostawcy (12)

AAT, AG Neovo, Arpol, EMU, IFTER, IronWave, Polon Alfa, Pulsar, Satel, TAP, Trikon, UTC. Lista rośnie — każdy nowy szablon to ~30 minut konfiguracji bez zmian w kodzie.

Odporność: applier używa savepointów per wiersz — jeden zły rekord (np. brak ceny) nie wywala całego importu kilkutysięcznego cennika. System loguje błąd i kontynuuje.

15 Bezpieczeństwo wszystkich integracji — wspólny mechanizm

Wszystkie sekrety używane przez integracje (tokeny OAuth Google/Microsoft, klucz API Claude, sekret webhooka VoIP, klucz SMSAPI, hasła SMTP, token KSeF) są przechowywane w bazie w postaci zaszyfrowanej AES-256-GCM. Klucz szyfrujący (INTEGRATION_SECRET_KEY) trzymany jest w zmiennych środowiskowych Railway — odrębnie od bazy danych.

Konsekwencja: Nawet bezpośredni dostęp do bazy danych (np. wykradziony zrzut) nie ujawnia sekretów integracji. Klucz i dane są fizycznie w innych miejscach. Procedura rotacji klucza opisana w docs/SECURITY.md.

Podsumowanie — Jak wyglądają integracje na tle rynku?

Kluczowe przewagi integracyjne

1. Redundancja — krytyczne funkcje (e-mail, pliki) mają automatyczny plan awaryjny
2. Spójne zabezpieczenia — wszędzie OAuth2/API Key, nigdy hasła w systemie
3. Automatyzacja — NIP auto-fill, import faktur z KSeF, AI kategoryzacja — mniej ręcznej pracy
4. Oficjalne SDK — integracja przez oficjalne biblioteki Google, Microsoft i Anthropic (nie „obejścia")
5. Kontrola uprawnień w AI — sztuczna inteligencja respektuje te same reguły dostępu co interfejs