# Ksef

> >

- **Type:** Skill
- **Install:** `agentstack add skill-laptee-ksef-skill-ksef-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Laptee](https://agentstack.voostack.com/s/laptee)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Laptee](https://github.com/Laptee)
- **Source:** https://github.com/Laptee/ksef-skill

## Install

```sh
agentstack add skill-laptee-ksef-skill-ksef-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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)

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

3. "Metoda autoryzacji? (token / certificate)"
   - token: "Podaj token KSeF (wygeneruj w Aplikacji Podatnika)"
   - certificate: "Podaj sciezke do certyfikatu (.crt) i klucza (.key)"

4. Zapisz do `/.env` (uzyj szablonu z `.env.example`)

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

6. "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`

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

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

4. 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`

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

3. 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]
```

3. 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](https://github.com/Laptee)
- **Source:** [Laptee/ksef-skill](https://github.com/Laptee/ksef-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-laptee-ksef-skill-ksef-skill
- Seller: https://agentstack.voostack.com/s/laptee
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.