Ksef

/ksef — Faktury z KSeF

Skill do pobierania i przegladania faktur kosztowych z polskiego Krajowego Systemu e-Faktur.

Konfiguracja

SKILL_DIR: [sciezka do tego skilla, np. ~/.claude/skills/ksef]

Dane runtime (tworzone automatycznie):

• .env — konfiguracja (NIP, token, srodowisko)
• faktury/ — pobrane faktury XML
• cert/ — certyfikaty (jesli auth certyfikatem)

Argumenty

• setup — wizard konfiguracji
• pobierz [dni] — pobierz faktury z KSeF (default 30 dni)
• faktury — lista pobranych faktur
• status — status polaczenia
• brak — menu

---

Workflow

/ksef (menu)

Sprawdz czy .env istnieje w SKILL_DIR:

• TAK — pokaz menu
• NIE — "Nie skonfigurowano. Wpisz /ksef setup"

== KSeF — Krajowy System e-Faktur ==

  /ksef pobierz [dni]  — pobierz faktury z KSeF (default 30 dni)
  /ksef faktury        — lista pobranych faktur
  /ksef status         — status polaczenia
  /ksef setup          — konfiguracja

---

/ksef setup

Wizard konfiguracji. Pyta usera krok po kroku:

1. "Jakie srodowisko? (TEST / PRODUCTION)"

• TEST = api-test.ksef.mf.gov.pl (do testow)
• PRODUCTION = api.ksef.mf.gov.pl (prawdziwe faktury)

1. "Podaj NIP firmy (10 cyfr):"

1. "Metoda autoryzacji? (token / certificate)"

• token: "Podaj token KSeF (wygeneruj w Aplikacji Podatnika)"
• certificate: "Podaj sciezke do certyfikatu (.crt) i klucza (.key)"

1. Zapisz do /.env (uzyj szablonu z .env.example)

1. Sprawdz czy Python deps zainstalowane:

``bash python3 -c "import lxml, ksef2, dotenv" 2>&1 ` Jesli blad: pip install -r /scripts/requirements.txt`

1. "Konfiguracja zapisana! Wpisz /ksef pobierz zeby pobrac faktury."

BEZPIECZENSTWO: NIGDY nie wyswietlaj tokenu, hasla klucza ani zawartosci certyfikatu.

---

/ksef pobierz [dni]

Pobiera faktury kosztowe (gdzie firma usera jest nabywca) z KSeF.

1. Preflight:

• Sprawdz .env — brak? "Wpisz /ksef setup"
• Sprawdz deps: python3 -c "import ksef2" — blad? pip install -r /scripts/requirements.txt

1. Uruchom:

``bash python3 /scripts/download_invoices.py [dni] ` Domyslnie 30 dni. User moze podac np. /ksef pobierz 60`

1. Pokaz output skryptu (lista pobranych faktur z kwotami)

1. Podsumowanie: "Pobrano X faktur do /faktury/"

Bledy:

• 401/403: "Token wygasl. Wygeneruj nowy w Aplikacji Podatnika i wpisz /ksef setup"
• Network error: "Sprawdz polaczenie internetowe"
• Brak faktur: "Brak faktur kosztowych w ostatnich [N] dniach"

---

/ksef faktury

Wyswietla liste pobranych faktur w czytelnej tabeli.

1. Uruchom parser:

``bash python3 /scripts/parse_invoice.py /faktury/ ` Opcjonalne flagi: --limit 20, --date 2026-03-22`

1. Pokaz output — sformatowana tabela z: numer, data, sprzedawca, NIP, kwoty

1. Jesli brak faktur: "Brak pobranych faktur. Wpisz /ksef pobierz"

Filtry:

• /ksef faktury — wszystkie (limit 50)
• /ksef faktury 2026-03 — filtr po dacie

---

/ksef status

1. Przeczytaj .env z SKILL_DIR (uzyj Read tool, NIE cat)
2. Wyswietl (MASKUJAC wrazliwe dane):

== Status KSeF ==
Srodowisko: [TEST/PRODUCTION]
NIP: [NIP]
Auth: [token/certificate]
Token: ****...[ostatnie 4 znaki]
Faktury pobrane: [liczba plikow w faktury/]
Python: [wersja]
ksef2: [wersja]

1. Sprawdz deps: python3 -c "import ksef2; print(ksef2.__version__)"

BEZPIECZENSTWO:

• Token: TYLKO ostatnie 4 znaki. Reszta zamaskowana.
• Haslo klucza: NIGDY nie wyswietlaj.
• Certyfikat: NIGDY nie czytaj zawartosci.

---

Obsluga bledow

| Blad | Komunikat | |------|-----------| | Brak .env | "Nie skonfigurowano. Wpisz /ksef setup" | | Brak deps | "Instaluje zaleznosci..." + pip install | | Token wygasl (401) | "Token wygasl. Wygeneruj nowy w Aplikacji Podatnika" | | Network error | "Sprawdz polaczenie z internetem" | | Brak faktur | "Brak faktur kosztowych w podanym okresie" | | XML parse error | "Blad parsowania faktury. Sprawdz plik XML" |

Linki pomocnicze:

• Aplikacja Podatnika TEST: https://ap-test.ksef.mf.gov.pl
• Aplikacja Podatnika PROD: https://ap.ksef.mf.gov.pl
• Dokumentacja KSeF: https://www.podatki.gov.pl/ksef/

Referencje

• references/fa3-fields.md — mapowanie pol XML faktury FA(3) na opisy po polsku
• scripts/download_invoices.py — skrypt pobierajacy faktury z API KSeF
• scripts/parse_invoice.py — parser XML faktur do czytelnej tabeli

Bezpieczenstwo

• Plik .env zawiera tokeny i hasla — NIGDY nie wyswietlaj pelnych wartosci
• Token KSeF: pokazuj TYLKO ostatnie 4 znaki
• Haslo klucza prywatnego: NIGDY nie wyswietlaj
• Certyfikat prywatny: NIGDY nie czytaj zawartosci pliku
• Faktury XML zawieraja dane firm (NIP, nazwy) — to nie sa sekrety (sa na fakturze)

Wymagania

• Python 3.10+
• pip install: lxml>=5.0, ksef2>=0.9.2, python-dotenv
• Token KSeF lub certyfikat XAdES

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Laptee
• Source: Laptee/ksef-skill
• License: MIT

Install and usage instructions live in the source repository linked above.