Intuiti Integrator KSeF do Symfonii

Instrukcja | AkceptujFaktury.pl | Intuiti Integrator KSeF do Symfonii (moduł akceptacji)

AkceptujFaktury.pl to moduł, który jest częścią rozwiązania Intuiti Integrator KSeF do Symfonii. Program umożliwia przeglądanie dokumentów w wygodnej siatce, zmianę statusów, dodawanie notatek oraz archiwizację. Rozwiązanie jest przeznaczone m.in. dla biur rachunkowych oraz organizacji wielofirmowych – działa w oparciu o prywatny serwer FTP użytkownika. Aplikacja obsługuje protokoły: FTP, FTPS oraz SFTP.

Spis treści

1. Wymagania i architektura
2. Logowanie i bezpieczeństwo
3. Tryb DEMO
4. Tryb wielofirmowy
5. Użytkownicy FTP i organizacje
6. Nowa firma – zakładanie katalogu NIP
7. Lista firm – wybór firmy
8. Dokumenty – siatka i operacje
9. Statusy dokumentów
10. Notatki
11. Podgląd pozycji z faktury
12. Struktura katalogów i pliki na serwerze
13. Import plików XML
14. Manager plików
15. Archiwum dokumentów
16. Zestawienia i raporty
17. Ustawienia i zachowanie interfejsu
18. FAQ i rozwiązywanie problemów

Wymagania i architektura

• Własny serwer FTP/FTPS/SFTP – prywatny, kontrolowany przez klienta. Aplikacja preferuje FTPS (TLS), w razie braku dostępności przechodzi na FTP. SFTP jest również obsługiwane.
• SFTP – po stronie PHP zalecane rozszerzenie ext-ssh2. Alternatywnie możliwy fallback do phpseclib 3 (jeśli dostępny w projekcie).
• Integrator KSeF – odpowiada za pobranie dokumentów z KSeF i umieszczenie plików w katalogach firmy na serwerze. Od wersji 1.076 AkceptujFaktury.pl również pobiera dokumenty sprzedaży i zakupu z serwerów KSeF 2.0
• Brak narzuconych limitów – liczba dokumentów zależy wyłącznie od zasobów serwera.

Logowanie i bezpieczeństwo

Ekran Logowanie zawiera pola: adres serwera, NIP, login, hasło (opcjonalnie „Zapamiętaj”). Dostępny jest także przycisk DEMO.

• FTPS → FTP (priorytet TLS, automatyczny fallback).
• SFTP – po adresie sftp://host lub porcie :22.
• CSRF – token we wszystkich działaniach zapisu.
• Sesja – limit czasu z licznikiem; odświeżanie aktywności pingiem; sygnał przy wylogowaniu.
• Walidacje – NIP (10 cyfr), bezpieczne nazwy plików, bezpieczny odczyt XML/JSON.

🔐 Protokoły połączenia i poziom bezpieczeństwa

Protokół	Opis	Poziom bezpieczeństwa	Przykład komunikatu
SFTP	Połączenie szyfrowane poprzez SSH (port 22).	🟢 Bezpieczny	SFTP — Bezpieczny
FTPS (TLS)	Połączenie szyfrowane TLS/SSL (zwykle port 21).	🟢 Bezpieczny	FTPS (TLS) — Bezpieczny
FTP	Połączenie nieszyfrowane – hasło i dane przesyłane jawnie.	🔴 Niebezpieczny	FTP — Niebezpieczny

Wskazówki:
– Dla FTPS użyj adresu w formacie ftps://ftp.twojadomena.pl
– Dla SFTP użyj adresu w formacie sftp://ftp.twojadomena.pl lub sftp://ftp.twojadomena.pl:22
– Jeśli widzisz komunikat „FTP — Niebezpieczny”, skontaktuj się z administratorem w celu włączenia FTPS/SFTP.

Tryb DEMO

Aplikacja zawiera organizację DEMO z przykładowymi danymi. W trybie DEMO można testować: przeglądanie dokumentów, zmianę statusów, notatki oraz podgląd szczegółów faktur.

Dostępna jest także funkcja Nowa firma – pozwala dodać firmę demonstracyjną. Uwaga: nowa firma w DEMO może być widoczna dla innych użytkowników DEMO.

Tryb wielofirmowy

Aplikacja obsługuje organizacje jedno- i wielofirmowe. Tryb wielofirmowy aktywuje się, gdy w organizacji istnieje więcej niż jedna firma (więcej katalogów NIP).

• Jedna firma → przejście bezpośrednio do dokumentów.
• Wiele firm → ekran listy firm i wybór NIP.
• Dodawanie kolejnej firmy możliwe z przycisku Dodaj firmę.

Użytkownicy FTP i organizacje

Organizacja w systemie odpowiada odrębnemu katalogowi na serwerze FTP. Dostęp regulowany jest przez konta FTP (login/hasło).

• Nowy użytkownik FTP otrzymuje dostęp do katalogu organizacji.
• Wewnątrz organizacji mogą istnieć podkatalogi firm (NIP), co umożliwia pracę wielofirmową.
• Możliwe jest ograniczenie dostępu do wybranych firm (katalogów NIP) zgodnie z polityką IT.

Przykładowa struktura organizacji (uproszczona)

public_ftp/Firmy/
└── DEMO/                      ← organizacja
    ├── 1234567890/            ← firma (NIP)
    │   ├── firma.json
    │   ├── Zakup/
    │   ├── Sprzedaz/
    │   └── Archiwum/
    └── 2223334445/
        ├── firma.json
        ├── Zakup/
        ├── Sprzedaz/
        └── Archiwum/

Nowa firma – zakładanie katalogu NIP i danych firmy

Jeżeli po zalogowaniu nie istnieje katalog o nazwie NIP, użytkownik może utworzyć firmę. System tworzy katalog NIP oraz zapisuje podstawowe dane firmy.

• Formularz: nazwa firmy, NIP + przycisk Pobierz z GUS (uzupełnienie danych, jeżeli dostępne).
• Tworzony jest katalog /NIP oraz plik firma.json.
• Tworzone są również obszary: Zakup, Sprzedaz, Archiwum.
• Gdy katalog już istnieje – pojawi się komunikat o duplikacie.

Minimalny firma.json:

{
            "nazwa_firmy": "Nazwa Firmy sp. z o.o.",
            "nip": "0000000001",
            "krs": "0015848",
            "regon": "0000123456",
            "kod_pocztowy": "00-00",
            "miejscowosc": "Poznań",
            "ulica": "Poznańska",
            "dom": "11",
            "lokal": null,
            "email": "demo@akceptujfaktury.pl",
            "ksef": {
              "company_name": "Nazwa Firmy sp. z o.o.",
              "nip": "0000000001",
              "ksef_token": "tokenKSeF",
              "env": "demo"
            }
          }

Lista firm – wybór firmy (wiele NIP-ów)

• Widok pokazuje: Nazwa firmy | NIP (z pliku firma.json) oraz przycisk Wybierz.
• Wyszukiwarka pozwala filtrować po nazwie i NIP.
• Przycisk Dodaj firmę przenosi do sekcji „Nowa firma”.

Dokumenty – widok siatki i operacje

Po wyborze firmy użytkownik przechodzi do listy dokumentów w wybranym obszarze (domyślnie: Zakup).

• siatka dokumentów z wyszukiwaniem i filtrowaniem,
• podgląd pozycji faktury (szczegóły),
• zmiana statusu dokumentu i notatki użytkownika.

Statusy dokumentów

Dostępne statusy: do akceptacji, zaakceptowany, wyjaśniany, odrzucony.

• Kliknięcie w status pozwala na zmianę.
• Status i metadane zapisywane są w pliku JSON powiązanym z dokumentem.

Notatki

• Notatka pozwala dopisać komentarz do dokumentu (np. informacja dla księgowości).
• W siatce dokumentów widoczny jest znacznik, jeśli notatka istnieje.

Podgląd pozycji z faktury

• W oknie szczegółów widoczne są dane nagłówka oraz pozycje faktury.
• System prezentuje podsumowania: netto, VAT, brutto.

Struktura katalogów i pliki na serwerze

Od wersji 1.073 dokumenty są rozdzielone na obszary: Zakup, Sprzedaz i Archiwum. Zmiana zwiększa czytelność i przygotowuje system do pełnej obsługi sprzedaży.

/
└─ 1234567890/                 ← firma (NIP)
   ├─ firma.json               ← dane firmy i konfiguracja
   │
   ├─ Zakup/                   ← faktury zakupowe (kosztowe)
   │   ├─ <nr_ksef>.xml
   │   ├─ <nr_ksef>.json
   │   └─ ...
   │
   ├─ Sprzedaz/                ← faktury sprzedażowe
   │   ├─ <nr_ksef>.xml
   │   ├─ <nr_ksef>.json
   │   └─ ...
   │
   └─ Archiwum/                ← dokumenty zarchiwizowane
       ├─ 2025/
       │   ├─ 01/
       │   │   ├─ <nr_ksef>.xml
       │   │   └─ <nr_ksef>.json
       │   └─ ...
       └─ ...

• Zakup – główny obszar pracy z fakturami kosztowymi.
• Sprzedaz – obszar dla faktur sprzedażowych.
• Archiwum – dokumenty przeniesione z obszarów roboczych, posegregowane wg roku i miesiąca.

Informacja dla administratorów FTP:
Nie należy usuwać katalogów obszarów ani pliku firma.json. Wymagane są uprawnienia zapisu w katalogach: Zakup, Sprzedaz, Archiwum.

Nazewnictwo plików:

• Dokument KSeF jest zapisany jako <numer_referencyjny>.xml.
• Metadane dokumentu są zapisane jako <numer_referencyjny>.json (status, notatka, historia).

Import plików XML

Import umożliwia wgranie wielu plików XML jednocześnie do wybranego obszaru: Zakup, Sprzedaz lub Archiwum.

• wybór obszaru docelowego,
• obsługa przeciągnij i upuść (drag & drop),
• akceptowane są wyłącznie pliki .xml,
• pliki o tej samej nazwie nie są nadpisywane.

Manager plików

Manager plików pozwala przeglądać zawartość katalogu firmy na serwerze oraz poruszać się po obszarach Zakup, Sprzedaz i Archiwum.

• przechodzenie między obszarami,
• podgląd plików XML i JSON,
• edycja pliku firma.json (bez możliwości jego usunięcia),
• ochrona katalogów obszarów przed przypadkowym usunięciem.

Archiwum dokumentów

Archiwum służy do przechowywania dokumentów zakończonych (np. po akceptacji) oraz historycznych. Dokumenty z archiwum pozostają dostępne do wglądu.

• automatyczna struktura według roku i miesiąca,
• zachowanie historii statusów i notatek,
• porządek i bezpieczeństwo pracy (oddzielenie dokumentów bieżących od archiwalnych).

Zestawienia i raporty

W kolejnych wersjach planowane jest rozwinięcie zestawień dokumentów według obszarów, statusów i okresów rozliczeniowych, aby ułatwić kontrolę obiegu dokumentów w firmach wieloosobowych i wielofirmowych.

Ustawienia i zachowanie interfejsu

• Przy akcjach zapisu/logowania/wyboru firmy pojawia się overlay, który zapobiega wielokrotnym kliknięciom.
• W liście firm wyszukiwarka ułatwia szybkie odnajdywanie firm po nazwie i NIP.
• Preferencje (np. filtry w widoku dokumentów) mogą być zapamiętywane w przeglądarce.

FAQ i rozwiązywanie problemów

Brak logowania do FTP – sprawdź host, login/hasło i dostępność FTPS. System może przełączyć się na FTP, jeśli FTPS jest niedostępny.

Logowanie SFTP – użyj adresu sftp://host lub portu :22. Jeśli serwer tego wymaga – skontaktuj się z administratorem.

Brak firmy po zalogowaniu – utwórz firmę w sekcji „Nowa firma” lub skontaktuj się z administratorem.

Status/Notatka nie zapisuje się – sprawdź uprawnienia zapisu do plików w katalogu firmy.

---

Masz pytania lub potrzebujesz pomocy? Zadzwoń: +48 61 307 40 00 lub napisz przez formularz: intuiti.pl/kontakt/.