Agent Ksiegowy KSeF

Specjalistyczna wiedza do obslugi Krajowego Systemu e-Faktur (KSeF) w srodowisku KSeF 2.0 ze struktura FA(3). Wspiera zadania ksiegowe zwiazane z fakturowaniem elektronicznym w Polsce.

Model bezpieczenstwa

Ten skill jest wylacznie instrukcyjny — sklada sie z plikow Markdown zawierajacych wiedze domenowa, wzorce architektoniczne i przyklady kodu. Nie zawiera zadnego kodu wykonywalnego, binarek, skryptow instalacyjnych ani zaleznosci runtime.

Gwarancje po stronie skilla:

• disableModelInvocation: true / disable-model-invocation: true — zadeklarowane zarowno w metadanych frontmatter (oba formaty: camelCase i kebab-case) jak i w dedykowanym manifescie skill.json. Skill nie powinien byc wywolywany autonomicznie przez model.
• secret: true — zmienne srodowiskowe KSEF_TOKEN i KSEF_ENCRYPTION_KEY sa oznaczone jako sekrety w frontmatter i skill.json, sygnalizujac platformie, ze musza byc izolowane i nie moga byc logowane ani wyswietlane.
• Brak kodu wykonywalnego — wszystkie przyklady (Python, XML, JSON) to ilustracje pogladowe, NIE kod uruchamiany przez skill.
• Brak instalacji — skill nie zapisuje plikow na dysk, nie pobiera zaleznosci, nie modyfikuje konfiguracji systemu.
• Dedykowany manifest skill.json — maszynowo czytelny plik z metadanymi bezpieczenstwa, deklaracjami zmiennych srodowiskowych i ograniczeniami. Jesli platforma nie parsuje frontmatter SKILL.md poprawnie, powinna odczytac metadane z skill.json.

UWAGA — weryfikacja metadanych rejestru przed instalacja:

Flagi bezpieczenstwa sa zadeklarowane w dwoch zrodlach: frontmatter SKILL.md i skill.json. Mimo to, platforma hostingowa moze nie odczytac lub nie wymusic tych flag. Przed instalacja MUSISZ wykonac ponizsze kroki:

1. Sprawdz metadane rejestru — po dodaniu skilla do platformy, otworz widok metadanych rejestru (registry metadata) wyswietlany przez platforme. Zweryfikuj, ze pole disable-model-invocation jest ustawione na true oraz ze zmienne srodowiskowe (KSEF_TOKEN, KSEF_ENCRYPTION_KEY, KSEF_BASE_URL) sa widoczne z oznaczeniem secret. Jesli platforma pokazuje not set, false lub nie wyswietla tych pol — flagi NIE sa wymuszane.
2. Jesli metadane rejestru nie pasuja do frontmatter/skill.json — traktuj skill jako wyzszego ryzyka: NIE udostepniaj danych uwierzytelniajacych (tokenow, certyfikatow, kluczy), NIE konfiguruj zmiennych srodowiskowych (KSEF_TOKEN, KSEF_ENCRYPTION_KEY), NIE zezwalaj na autonomiczne uzycie.
3. Zweryfikuj izolacje zmiennych srodowiskowych — potwierdz, ze platforma izoluje env vars i nie loguje/wyswietla ich wartosci w konwersacji.
4. Jesli platforma nie wymusza flag — skontaktuj sie z dostawca platformy w celu wlaczenia obslugi disableModelInvocation (lub parsowania skill.json) lub nie instaluj skilla z dostepem do jakichkolwiek danych uwierzytelniajacych.

Gwarancje zalezne od platformy:

• Wymuszanie flagi disableModelInvocation zalezy od platformy hostingowej. Sam frontmatter nie zapewnia ochrony — wymaga wsparcia po stronie platformy.
• Izolacja zmiennych srodowiskowych (env vars) zalezy od platformy. Skill deklaruje je jako opcjonalne, ale nie kontroluje jak platforma je przechowuje i udostepnia.
• Jesli platforma nie wymusza tych ustawien, traktuj skill jako wyzszego ryzyka i nie udostepniaj mu danych uwierzytelniajacych ani dostepu produkcyjnego.

Ograniczenia

• Tylko wiedza — brak wykonywania kodu - Dostarcza wiedze domenowa, wzorce architektoniczne i wskazowki. Wszystkie przyklady kodu (w tym ML/AI) sa edukacyjne i pogladowe. Skill NIE uruchamia modeli ML, NIE wykonuje inferencji, NIE wymaga runtime'ow Python/sklearn ani zadnych binarek. Agent wyjasnia algorytmy i sugeruje kod do implementacji przez uzytkownika.
• Nie jest porada prawna ani podatkowa - Informacje odzwierciedlaja stan wiedzy na dzien sporadzenia i moga byc nieaktualne. Zawsze zalecaj konsultacje z doradca podatkowym przed wdrozeniem.
• AI wspiera, nie decyduje - Opisy funkcji AI (klasyfikacja kosztow, wykrywanie fraudu, predykcja cash flow) to architektura referencyjna i wzorce implementacyjne. Agent dostarcza wiedze o algorytmach i pomaga pisac kod — nie podejmuje wiazacych decyzji podatkowych ani finansowych.
• Wymagane potwierdzenie uzytkownika - Zawsze wymagaj jawnej zgody uzytkownika przed: blokowaniem platnosci, wysylaniem faktur na produkcyjny KSeF, modyfikacja zapisow ksiegowych lub jakimkolwiek dzialaniem z konsekwencjami finansowymi.
• Dane uwierzytelniajace zarzadzane przez uzytkownika - Tokeny KSeF API, certyfikaty i klucze szyfrowania musza byc dostarczone przez uzytkownika przez zmienne srodowiskowe (zadeklarowane w metadanych: KSEF_TOKEN, KSEF_ENCRYPTION_KEY, KSEF_BASE_URL) lub menedzer sekretow. Skill nigdy nie przechowuje, nie generuje, nie przesyla ani nie prosi o dane uwierzytelniajace niejawnie. NIGDY nie wklejaj danych uwierzytelniajacych (tokenow, kluczy, certyfikatow) bezposrednio w rozmowie z agentem — uzyj zmiennych srodowiskowych lub menedzera sekretow platformy. Przyklady uzycia Vault/Fernet w dokumentacji referencyjnej to wzorce architektoniczne do implementacji przez uzytkownika.
• Uzyj DEMO do testow - Produkcja (https://ksef.mf.gov.pl) wystawia prawnie wiazace faktury. Uzyj DEMO (https://ksef-demo.mf.gov.pl) do developmentu i testow.
• Wylaczone autonomiczne wywolanie - Skill ustawia disableModelInvocation: true i disable-model-invocation: true w metadanych frontmatter (oba formaty nazewnictwa) oraz w dedykowanym manifescie skill.json. Oznacza to, ze model nie powinien wywolywac tego skilla autonomicznie — wymaga jawnej akcji uzytkownika. UWAGA: Frontmatter i skill.json to deklaracje — nie gwarancje. Wymuszanie zalezy od platformy. Przed uzyciem zweryfikuj, ze metadane rejestru (registry metadata) wyswietlane przez platforme rowniez pokazuja disable-model-invocation: true. Jesli platforma pokazuje not set lub false, flaga nie jest wymuszana i skill moze byc wywolywany autonomicznie (patrz sekcja "Model bezpieczenstwa" powyzej).

Checklist przed instalacja

Przed instalacja skilla i konfiguracja zmiennych srodowiskowych wykonaj ponizsze kroki:

• Zweryfikuj metadane rejestru platformy — pole disable-model-invocation musi pokazywac true
• Zweryfikuj, ze platforma odczytala deklaracje env vars z frontmatter lub skill.json — zmienne KSEF_TOKEN i KSEF_ENCRYPTION_KEY musza byc widoczne jako sekrety (secret: true)
• Potwierdz, ze platforma izoluje zmienne srodowiskowe (nie loguje, nie wyswietla w konwersacji)
• Przetestuj skill wylacznie ze srodowiskiem DEMO (https://ksef-demo.mf.gov.pl) przed jakimkolwiek uzyciem produkcyjnym
• NIE wklejaj tokenow, kluczy ani certyfikatow bezposrednio w rozmowie — uzyj env vars lub menedzera sekretow
• Jesli metadane rejestru nie pasuja do frontmatter/skill.json — NIE konfiguruj danych uwierzytelniajacych i zglos problem dostawcy platformy

Glowne kompetencje

1. Obsluga KSeF 2.0 API

Wystawianie faktur FA(3), pobieranie faktur zakupowych, zarzadzanie sesjami/tokenami, obsluga trybu Offline24 (awaryjny), pobieranie UPO (Urzedowe Poswiadczenie Odbioru).

Kluczowe endpointy:

POST /api/online/Session/InitToken     # Inicjalizacja sesji
POST /api/online/Invoice/Send          # Wyslanie faktury
GET  /api/online/Invoice/Status/{ref}  # Sprawdzenie statusu
POST /api/online/Query/Invoice/Sync    # Zapytanie o faktury zakupowe

Zobacz references/ksef-api-reference.md - pelna dokumentacja API z uwierzytelnianiem, kodami bledow i rate limiting.

2. Struktura FA(3)

Roznice FA(3) vs FA(2): zalaczniki do faktur, typ kontrahenta PRACOWNIK, rozszerzone formaty konta bankowego, limit 50 000 pozycji w korekcie, identyfikatory JST i grup VAT.

Zobacz references/ksef-fa3-examples.md - przyklady XML (faktura podstawowa, wiele stawek VAT, korekty, MPP, Offline24, zalaczniki).

3. Przeplywy ksiegowe

Sprzedaz: Dane -> Generuj FA(3) -> Wyslij KSeF -> Pobierz nr KSeF -> Ksieguj Wn 300 (Rozrachunki) | Ma 700 (Sprzedaz) + Ma 220 (VAT nalezny)

Zakupy: Odpytuj KSeF -> Pobierz XML -> Klasyfikuj AI -> Ksieguj Wn 400-500 (Koszty) + Wn 221 (VAT) | Ma 201 (Rozrachunki)

Zobacz references/ksef-accounting-workflows.md - szczegolowe przeplywy z dopasowywaniem platnosci, MPP, korektami, rejestrami VAT i zamknieciem miesiaca.

4. Funkcje wspomagane AI (architektura referencyjna)

Ponizsze opisy to wzorce implementacyjne i architektura referencyjna. Skill NIE uruchamia modeli ML — dostarcza wiedze o algorytmach, pomaga projektowac pipeline'y i pisac kod do implementacji w systemie uzytkownika. Przyklady kodu w plikach referencyjnych (Python, sklearn, pandas) to pseudokod pogladowy — skill nie zawiera wytrenowanych modeli, artefaktow ML ani plikow wykonywalnych.

• Klasyfikacja kosztow - Wzorzec: historia kontrahenta -> dopasowanie slow kluczowych -> model ML (Random Forest). Flaguj do przegladu jesli confidence < 0.8.
• Wykrywanie fraudu - Wzorzec: Isolation Forest dla anomalii kwotowych, scoring dla phishing invoices, analiza grafow dla VAT carousel.
• Predykcja cash flow - Wzorzec: Random Forest Regressor na podstawie historii kontrahenta, kwot i wzorcow sezonowych.

Zobacz references/ksef-ai-features.md - koncepcyjne algorytmy i wzorce implementacji (wymagaja sklearn, pandas — nie sa zaleznoscia tego skilla).

5. Compliance i bezpieczenstwo (wzorce implementacyjne)

Ponizsze to rekomendowane wzorce bezpieczenstwa do implementacji w systemie uzytkownika. Skill dostarcza wiedze i przyklady kodu — nie implementuje tych mechanizmow sam.

• Weryfikacja Bialej Listy VAT przed platnosciami
• Szyfrowane przechowywanie tokenow (wzorce Fernet/Vault — do implementacji przez uzytkownika)
• Audit trail wszystkich operacji
• Strategia backup 3-2-1
• Zgodnosc z RODO (anonimizacja po okresie retencji)
• RBAC (kontrola dostepu oparta na rolach)

Zobacz references/ksef-security-compliance.md - wzorce implementacji i checklista bezpieczenstwa.

6. Faktury korygujace

Pobierz oryginal z KSeF -> Utworz korekte FA(3) -> Powiaz z nr KSeF oryginalu -> Wyslij do KSeF -> Ksieguj storno lub roznicowo.

7. Rejestry VAT i JPK_V7

Generowanie rejestrow sprzedazy/zakupow (Excel/PDF), JPK_V7M (miesieczny), JPK_V7K (kwartalny).

Troubleshooting - szybka pomoc

Problem	Przyczyna	Rozwiazanie
Faktura odrzucona (400/422)	Nieprawidlowy XML, NIP, data, brak pol	Sprawdz UTF-8, waliduj schemat FA(3), weryfikuj NIP
Timeout API	Awaria KSeF, siec, godziny szczytu	Sprawdz status KSeF, retry z exponential backoff
Nie mozna dopasowac platnosci	Niezgodna kwota, brak danych, split payment	Rozszerzone wyszukiwanie (+/-2%, +/-14 dni), sprawdz MPP

Zobacz references/ksef-troubleshooting.md - pelny przewodnik troubleshooting.

Pliki referencyjne

Laduj w zaleznosci od zadania:

Plik	Kiedy czytac
skill.json	Manifest metadanych — flagi bezpieczenstwa, deklaracje env vars, ograniczenia. Zrodlo prawdy dla rejestrow i skanerow.
ksef-api-reference.md	Endpointy KSeF API, uwierzytelnianie, wysylanie/pobieranie faktur
ksef-legal-status.md	Daty wdrozenia KSeF, wymagania prawne, kary
ksef-fa3-examples.md	Tworzenie lub walidacja struktur XML faktur FA(3)
ksef-accounting-workflows.md	Zapisy ksiegowe, dopasowanie platnosci, MPP, korekty, rejestry VAT
ksef-ai-features.md	Klasyfikacja kosztow, wykrywanie fraudu, algorytmy predykcji cash flow
ksef-security-compliance.md	Biala Lista VAT, bezpieczenstwo tokenow, audit trail, RODO, backup
ksef-troubleshooting.md	Bledy API, problemy walidacji, wydajnosc

Zasoby oficjalne

• Portal KSeF: https://ksef.podatki.gov.pl
• KSeF DEMO: https://ksef-demo.mf.gov.pl
• KSeF Produkcja: https://ksef.mf.gov.pl
• API Bialej Listy VAT: https://wl-api.mf.gov.pl
• KSeF Latarnia (status): https://github.com/CIRFMF/ksef-latarnia