Download the PHP package labapawel/ksef-api without Composer

On this page you can find all versions of the php package labapawel/ksef-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of labapawel/ksef-api

Informations about the package ksef-api

KsefApi

Komponent Laravel do integracji z API KSeF.

Repozytorium/paczka: labapawel/ksef-api

Quick Start

Zakres

Aktualny szkielet paczki zawiera:

Wymagania

Instalacja

Publikacja konfiguracji

Publikacja migracji i seeders

Paczka rejestruje też migracje przez loadMigrationsFrom, więc publikacja migracji jest opcjonalna.

Załadowanie domyślnych środowisk

Aby załadować 3 domyślne środowiska (test, demo, prod):

Lub po opublikowaniu seeders:

Generowanie klucza szyfrowania

Pakiet używa standardowego mechanizmu Laravel Encryption z kluczem APP_KEY.

⚠️ UWAGA: Klucz APP_KEY służy do szyfrowania poświadczeń. Po zaszyfrowaniu danych zmiana klucza uniemożliwi ich odczyt!

⚠️ Ostrzeżenie: Zmiana klucza APP_KEY po zaszyfrowaniu danych w bazie uniemożliwi ich odczyt! Zawsze twórz backup klucza przed jego zmianą.

Zmienne środowiskowe

Przykładowe wartości .env:

Konfiguracje środowisk (environment + api_url) są przechowywane w tabeli ksef_environments, co pozwala na obsługę wielu środowisk bez potrzeby zmian w .env. Poświadczenia są przechowywane w ksef_credentials z certyfikatem i innymi danymi wrażliwymi (kolumny certificate_encrypted, private_key_encrypted, certificate_password_encrypted).

Opis parametrów

Parametr Wymagany Domyślna wartość Opis
KSEF_CHALLENGE_TOKEN_LIFETIME ❌ 10 Czas ważności challenge tokena w minutach. Po tym czasie wymagane ponowne logowanie.
KSEF_API_TIMEOUT ❌ 30 Timeout dla żądań HTTP do API KSeF w sekundach.
KSEF_CREDENTIALS_TABLE ❌ ksef_credentials Nazwa tabeli w bazie danych dla poświadczeń KSeF.
KSEF_ENVIRONMENTS_TABLE ❌ ksef_environments Nazwa tabeli w bazie danych dla konfiguracji środowisk KSeF.
KSEF_INVOICES_TABLE ❌ ksef_invoices Nazwa tabeli w bazie danych dla faktur.

Środowiska KSeF

Pakiet przechowuje konfiguracje środowisk w tabeli ksef_environments, co pozwala na obsługę wielu środowisk (test, demo, prod) bez potrzeby konfigurowania wartości w .env.

Domyślne środowiska

Po uruchomieniu migracji i seedera, w bazie będą dostępne trzy środowiska:

Seeder

Aby załadować domyślne środowiska do bazy:

Lub dodaj do DatabaseSeeder:

Ręczne dodanie środowiska

Powiązanie poświadczeń ze środowiskiem

Każde poświadczenie jest powiązane z jednym środowiskiem przez ksef_environment_id:

Autentykacja

Logowanie do KSeF

Paczka automatycznie zarządza challenge tokenami i access tokenami.

Używając AuthenticationService (rekomendowane)

Używając KsefAuthClient (niski poziom)

Challenge Token Lifecycle

Pakiet automatycznie zarządza challenge tokenami:

  1. Pierwszy request — API zwraca nowy challenge token (ważny przez N minut, domyślnie 10)
  2. Challenge token przechowywany — zapisany w bazie w ksef_token_encrypted
  3. Challenge token wygasa — jeśli upłynęło N minut od otrzymania
  4. Automatyczne odświeżenie — przy następnym logowaniu pobierany jest nowy token

Czas ważności challenge tokena kontroluje parametr .env:

Poświadczenia w bazie danych

Wszystkie dane są automatycznie szyfrowane i przechowywane w tabeli ksef_credentials:

Model danych

Diagram relacji

ksef_environments

Tabela przechowuje konfiguracje środowisk (test, demo, prod):

Relacja: Jedno środowisko może mieć wiele poświadczeń (1:N)

ksef_credentials

Tabela przechowuje zaszyfrowane dane wrażliwe KSeF dla pary ksef_environment_id + nip:

ksef_invoices

Tabela przechowuje metadane biznesowe faktury oraz zaszyfrowany XML:

Modele Eloquent

Paczka udostępnia modele Eloquent z potężnymi scopes i metodami pomocniczymi.

Model KsefEnvironment

Przechowuje konfiguracje środowisk KSeF.

Model Credential

Przechowuje poświadczenia KSeF dla pary environment + nip.

Model Invoice

Przechowuje metadane faktury oraz zaszyfrowany XML.

Planowane API (szkielet gotowy)

Szyfrowanie

Modele Credential i Invoice automatycznie szyfrują wrażliwe dane za pomocą Laravel Encryption (AES-256-CBC) używając klucza APP_KEY z głównej konfiguracji aplikacji.

Klucz szyfrowania: APP_KEY z pliku .env Twojej aplikacji Laravel

Algorytm: AES-256-CBC z HMAC SHA-256 (Laravel Encryption)

Model Credential szyfruje:

Model Invoice szyfruje:

Szyfrowanie/deszyfrowanie odbywa się automatycznie podczas odczytu i zapisu:

⚠️ Wymagania:

Uwagi bezpieczeństwa

Klucz szyfrowania (APP_KEY)

Certyfikaty i klucze prywatne

Separacja środowisk

Dostęp do bazy danych

Backup i recovery

Typowe użycie

Przechowywanie poświadczeń

Rejestrowanie faktury

Wyszukiwanie faktur

Development

Po sklonowaniu uruchom:

Testowanie

Paczka zawiera kompleksowy zestaw testów dla modeli Eloquent.

Instalacja zależności testowych

Uruchamianie testów

Struktura testów

Używanie DataFactory w testach

Fabryka DataFactory zawiera pomocne metody do tworzenia testowych instancji:

Szyfrowanie i Bezpieczeństwo

Dane zaszyfrowane

Pakiet automatycznie szyfruje wszystkie wrażliwe dane za pomocą Laravel Encryption (AES-256-CBC):

Model Credential:

Model Invoice:

Klucz szyfrowania

Bezpieczeństwo producyjnego

⚠️ Krytyczne:

  1. Nigdy nie commituj APP_KEY do repozytorium — używaj .env
  2. Zawsze konfiguruj APP_KEY w .env.production
  3. Backup klucza przed rotacją — zmiana klucza uczyni dane niezrozumiałymi
  4. HTTPS — komunikacja z API KSeF zawsze po HTTPS
  5. Certifikaty — przechowuj certyfikaty KSeF bezpiecznie poza repozytorium
  6. Database credentials — chroni dostęp do bazy z poświadczeniami

Przykładowe bezpieczne środowisko

Architektura

Warstwa aplikacji

Przepływ autentykacji

Troubleshooting

Problem: "Brak poświadczeń w bazie dla NIP XXX"

Przyczyna: Poświadczenia nie zostały zapisane w bazie danych.

Rozwiązanie:

Problem: "Zmiana klucza APP_KEY uczyni dane niezrozumiałymi"

Przyczyna: Zmieniłeś APP_KEY v1 na v2 — istniejące dane były szyfrowane kluczem v1.

Rozwiązanie:

Problem: "cURL error 60: SSL certificate problem"

Przyczyna: Weryfikacja SSL w KsefAuthClient jest wyłączona ('verify' => false).

Rozwiązanie (production):

Problem: "UNIQUE constraint failed: ksef_credentials.ksef_environment_id, nip"

Przyczyna: Próbujesz stworzyć drugi rekord dla tej samej pary (środowisko + nip).

Rozwiązanie:

FAQ

P: Czy mogę używać różne certyfikaty dla tego samego NIP w różnych środowiskach?

O: Tak! Jeśli masz:

System automatycznie wybierze poprawny rekord na podstawie środowiska.

P: Czy access_token jest automatycznie odświeżany?

O: Nie w obecnej wersji. Musisz ręcznie wywoływać $auth->login() gdy token wygaśnie. Jeśli challenge token jest jeszcze ważny, logowanie jest szybkie.

P: Co zrobić ze starymi poświadczeniami (legacy environment/api_url)?

O: Pola environment i api_url w ksef_credentials są opcjonalne dla backward compatibility. Nowe projekty powinny używać relacji:

P: Czy mogę migrować istniejące kredencje z kolumn na foreign key?

O: Tak, wykonaj artisan command (jeśli istnieje) lub ręcznie:

P: Jaka jest maksymalna wielkość faktury (XML)?

O: Praktycznie bez limitu — kolumna xml_encrypted to longText (4GB w MySQL). Realistycznie: faktury XML są zwykle < 1MB.

P: Czy mogę wyłączyć automatyczne szyfrowanie pól?

O: Nie z modelu Eloquent — szyfrowanie jest wbudowane. Jeśli chcesz przechowywać dane niezaszyfrowane, musisz zmienić migracje i usunąć $encrypted z modeli.

P: Czy paczka obsługuje offline mode (offline KSeF)?

O: Nie w obecnej wersji. Offline mode wymaga lokalnego certyfikatu i jest obsługiwany przez dedykowany KSeF offline API.

Licencja

MIT License — patrz plik LICENSE

Wkład (Contributing)

Zapraszamy do współtworzenia! Zgłaszaj issues i pull requests na: https://github.com/labapawel/ksef-api

Kontakt i Wsparcie

Ostatnia aktualizacja: 2026-03-04
Wersja: 1.0.0
Status: Stable Release $invoice = DataFactory::createA

All versions of ksef-api with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
ext-curl Version *
ext-json Version *
ext-openssl Version *
illuminate/support Version ^10.0|^11.0|^12.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package labapawel/ksef-api contains the following files

Loading the files please wait ...