Dokumentacja aplikacji ksefapi-cli
Aplikacja kliencka ksefapi-cli.exe to konsolowe narzędzie (CLI) umożliwiające szybką i bezproblemową integrację z Krajowym Systemem e-Faktur (KSeF) za pośrednictwem serwisu ksefapi.pl. Program pozwala na automatyzację procesów wysyłki, pobierania oraz wizualizacji dokumentów księgowych bezpośrednio z poziomu wiersza poleceń.
Ogólny opis i zastosowanie aplikacji
Program ksefapi-cli.exe został zaprojektowany z myślą o programistach, administratorach systemów oraz działach IT, którzy potrzebują narzędzia do masowej lub zautomatyzowanej obsługi faktur w KSeF bez konieczności pisania dedykowanego oprogramowania API.
Poniżej przedstawiamy najważniejsze funkcjonalności aplikacji:
- Wysyłka dokumentów: Pojedyncze lub masowe (w paczkach) przesyłanie faktur w formacie XML do systemu KSeF.
- Pobieranie danych: Wyszukiwanie i pobieranie faktur ustrukturyzowanych z KSeF (kosztowych lub sprzedażowych) z określonego przedziału czasowego.
- Pobranie metadanych faktur: Super szybkie wyszukanie i pobranie tylko podstawowych metadanych opsiujących znalezione faktury.
- Wizualizacja: Generowanie czytelnych plików PDF lub HTML na podstawie surowych danych XML faktur oraz Urzędowych Poświadczeń Odbioru (UPO).
- Automatyzacja (skrypty): Możliwość łatwego osadzenia w harmonogramach zadań (np. Windows Task Scheduler, skrypty bash/bat) w celu cyklicznej wymiany danych z Krajowym Systemem e-Faktur.
Pobranie aplikacji
Aplikacja została udostępniona na stronach naszego serwisu w sekcji Pobierz i jest dostępna w dwóch wersjach:
Po pobraniu aplikacji należy ją rozpakować (plik ZIP lub TAR.GZ) w katalogu docelowym. Po rozpakowaniu z archiwum, aplikacja jest gotowa do użycia. Wymaga tylko podania jako parametrów: identyfikatora klucza oraz klucza API. W celu uzyskania obu parametrów niezbędne jest wykonanie Rejestracji i utworzenie konta w serwisie.
Konfiguracja aplikacji
Aplikacja ksefapi-cli.exe nie wymaga skomplikowanej instalacji. Do poprawnego działania i autoryzacji zapytań w serwisie ksefapi.pl niezbędne jest posiadanie:
- Identyfikatora klucza API (
--key-id) - Klucza API (
--key)
Parametry autoryzacyjne oraz konfigurację środowiska (testowe/produkcyjne) przekazuje się bezpośrednio podczas każdego wywołania programu za pomocą odpowiednich opcji. W przypadku pracy w sieciach korporacyjnych aplikacja wspiera również konfigurację połączenia przez serwer proxy (–proxy).
Sposób uruchamiania
Aplikację należy pobrać z naszej strony – sekcja Pobierz, a następnie uruchomić z poziomu terminala (Wiersz polecenia cmd lub PowerShell). Uruchomienie aplikacji jest możliwe również z poziomu systemu operacyjnego Linux.
Podstawowa składnia wywołania wygląda następująco:
ksefapi-cli.exe <command> [options]
Aby sprawdzić poprawność działania aplikacji lub wyświetlić szybką pomoc, należy wykonać komendę:
ksefapi-cli.exe --help
Opis składni wywołania
Każde zapytanie do systemu wymaga zdefiniowania jednej głównej komendy (Commands) oraz opcjonalnego zestawu parametrów opcji (Options).
Komendy (Commands)
Wybierz jedną z poniższych komend, aby określić działanie programu:
| Komenda | Opis |
--help |
Wyświetla tekst pomocy z opisem składni. |
--version |
Wyświetla aktualną wersję programu. |
--upload-invoice |
Przesyła pojedynczą fakturę do systemu KSeF. |
--upload-batch |
Przesyła paczkę faktur (plik ZIP) do systemu KSeF. |
--download-invoices |
Pobiera faktury z systemu KSeF na podstawie kryteriów. |
--invoice-visualize |
Generuje wizualizację dla wskazanej faktury. |
--upo-visualize |
Generuje wizualizację dla dokumentu UPO (Urzędowe Poświadczenie Odbioru). |
Opcje (Options)
Modyfikatory i parametry uzupełniające dla komend:
| Opcja | Opis i format danych |
--env |
Środowisko API KSeF. Dostępne wartości: prod lub test (domyślnie: prod). |
--key-id |
Identyfikator Twojego klucza API. |
--key |
Wartość Twojego klucza API. |
--proxy |
Adres URL serwera proxy HTTP. Format: http[s]://user:password@hostname:port |
--ksef-number |
Unikalny numer identyfikacyjny faktury w systemie KSeF. |
--range-from |
Data początkowa zakresu czasowego. Format: yyyy-mm-dd (rok – miesiąc – dzień). Zakres dat (from –to) nie może przekraczać 3 miesięcy. |
--range-to |
Data końcowa zakresu czasowego. Format: yyyy-mm-dd (rok – miesiąc – dzień). Zakres dat (from –to) nie może przekraczać 3 miesięcy. |
--format |
Format pliku wyjściowego. Dostępne wartości: csv, json, html, pdf, xml (domyślnie: xml). |
--csv-variant |
Format pliku CSV. Dostępne wartości: excel, std który jest zgodny z RFC 4180 (domyślnie: excel) |
--lang |
Język wyjściowy dokumentu. Dostępne wartości: en, pl (domyślnie: pl). |
--file-name |
Szablon nazwy pliku wyjściowego. Dostępne:
|
--subject-type |
Typ faktur do pobrania. Dostępne wartości: Subject1(faktury sprzedażowe) Subject2(faktury kosztowe) Subject3, SubjectAuthorized (domyślnie: Subject2). |
--in-file |
Ścieżka do pliku wejściowego. |
--out-file |
Ścieżka do pliku wyjściowego. |
--out-dir |
Ścieżka do katalogu wyjściowego. |
Przykłady użycia
Poniżej znajdują się praktyczne przykłady użycia aplikacji do najczęstszych scenariuszy (wartości kluczy abcdefgh oraz ijklmnop należy zastąpić własnymi).
Wysyłka faktury XML i odbiór UPO
Wysyła pojedynczą fakturę XML i zapisuje wygenerowane poświadczenie UPO:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --upload-invoice --in-file invoice.xml --out-file upo.xml
Wysyłka paczki faktur i odbiór UPO
Przesyła archiwum ZIP zawierające wiele faktur i zapisuje wygenerowane poświadczenie UPO:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --upload-batch --in-file invoices.zip --out-file upo.xml
Pobieranie faktur z określonego zakresu czasu jako pliki XML
Pobiera faktury wystawione w podanym przedziale czasowym i zapisuje je jako pliki XML we wskazanym folderze:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --download-invoices --range-from 2026-03-01 \--range-to 2026-03-31 --subject-type Subject2 --out-dir invoices
Pobieranie faktur z określonego zakresu czasu jako pliki PDF
Pobiera faktury z podanego przedziału czasowego, automatycznie generuje z nich pliki PDF z określonym formatem nazewnictwa i zapisuje we wskazanym folderze:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --download-invoices --range-from 2026-03-01 \--range-to 2026-03-31 --subject-type Subject2 --format pdf --file-name yyyy-mm-buyer-num --out-dir invoices
Generowanie wizualizacji faktury
Generuje plik PDF w języku angielskim dla podanej faktury na podstawie jej numeru KSeF:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --invoice-visualize --in-file invoice.xml \--ksef-number 123456789 --format pdf --lang en --out-file invoice.pdf
Generowanie wizualizacji UPO
Tworzy czytelny dokument PDF w języku angielskim na podstawie surowego pliku XML z poświadczeniem odbioru UPO:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --upo-visualize --in-file upo.xml \--format pdf --lang en --out-file upo.pdf
Pobranie metadanych opisujących faktury z określonego zakresu czasu w formacie CSV lub JSON
Pobiera metadanych faktur wystawionych w podanym przedziale czasowym i zapisuje je jako pliki CSV w bieżącym folderze:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --download-metadata --range-from 2026-03-01 \ --range-to 2026-03-31 --subject-type Subject2 --format csv --out-file invoices.csv
Aby uzyskać plik w formacie JSON wystarczy zastosować opcję --format json oraz wspiać nazwę pliku wyjściowego z odpowiednim rozszerzeniem: --out-file invoices.json
Poniżej opis zwracanych metadanych opisujących fakturę:
| Kolumna | Opis |
issue_date |
Data wystawienia faktury |
invoice_number |
Numer faktury nadany przez Sprzedawcę |
ksef_number |
Numer KSeF faktury |
invoice_type |
Typ faktury |
seller_number |
NIP Sprzedawcy |
seller_name |
Nazwa Sprzedawcy |
buyer_number |
NIP Kupującego |
buyer_name |
Nazwa Kupującego |
currency |
Waluta |
net_amount |
Kwota netto |
vat_amount |
Wartość podatku VAT |
gross_amount |
Kwota brutto. |
invoicing_mode |
Tryb wystawienia faktury |