Monorepo zawierające biblioteki SDK do integracji z KSeF oraz opcjonalnie pełną platformę do fakturowania na Laravel 11.
Dwa główne sposoby użycia:
- Tylko SDK — użyj pojedynczych pakietów (
ksef-client,ksef-xml-parser,ksef-crypto-proxy,ksef-qr-code) w dowolnym projekcie PHP - Pełna platforma — uruchom kompletny system (API + frontend) poprzez Docker
Etap: Early public alpha (v0.2.0-alpha)
Co jest gotowe:
- 4 pakiety SDK z testami jednostkowymi
- PHPStan level 5 przechodzi
- Generowanie i parsowanie XML FA(3)
- Uwierzytelnianie tokenem i XAdES
- Sesje interaktywne KSeF
- Generowanie kodów QR
Czego brakuje:
- Testów integracyjnych z realnym API KSeF
- Wsadowego/asynchronicznego wysyłania
- Publikacji na Packagist
Przy adopcji: API może się zmienić przed v1.0. Zweryfikuj z produkcyjnym API KSeF przed użyciem w production.
| Cel | Co zrobić |
|---|---|
| Chcę zintegrować KSeF z moją istniejącą aplikacją | Przejdź do Pakiety SDK |
| Chcę uruchomić gotowy system do fakturowania | Przejdź do Pełna platforma |
Samodzielne biblioteki PHP — można używać bez Laravela.
| Pakiet | Przeznaczenie |
|---|---|
fakturka/ksef-client |
HTTP client dla KSeF API 2.0 |
fakturka/ksef-xml-parser |
Generator i parser XML FA(3) |
fakturka/ksef-crypto-proxy |
Szyfrowanie AES/RSA, podpisy XAdES |
fakturka/ksef-qr-code |
Generowanie kodów QR dla faktur |
Status: Pakiety nie są na Packagist. Użyj VCS repozytorium.
{
"repositories": [{ "type": "vcs", "url": "https://github.com/IvY-Rsearch/fakturka-sdk.git" }],
"require": {
"fakturka/ksef-xml-parser": "dev-main"
}
}composer update| Pakiet | PHP | Zależności |
|---|---|---|
| ksef-client | 8.2+ | openssl, Guzzle HTTP 7.x |
| ksef-xml-parser | 8.2+ | xml, simplexml, dom |
| ksef-crypto-proxy | 8.2+ | openssl, json |
| ksef-qr-code | 8.2+ | endroid/qr-code ^5.0 |
use Fakturka\KsefXmlParser\{InvoiceBuilder, Invoice, Models\Party};
$seller = new Party(
name: 'Firma Sp. z o.o.',
nip: '5261040065',
addressLine1: 'ul. Marszałkowska 1',
postalCode: '00-001',
city: 'Warszawa',
);
$buyer = new Party(
name: 'Klient S.A.',
nip: '5260001246',
addressLine1: 'ul. Nowy Świat 15',
postalCode: '00-029',
city: 'Warszawa',
);
$invoice = new Invoice(
id: 'inv-001',
invoiceNumber: 'FV/2026/001',
issueDate: '2026-04-15',
serviceDescription: 'Usługi programistyczne',
amount: 123000, // grosze = 1230.00 PLN
paymentMethod: \Fakturka\KsefXmlParser\Models\PaymentMethod::TRANSFER,
);
$xml = (new InvoiceBuilder())->generateXml($invoice, $buyer, $seller);
echo $xml; // prawidłowy XML FA(3)Wynik: Poprawny dokument XML FA(3) zgodny ze schematem KSeF.
Aby wysłać do KSeF: uwierzytelnianie → sesja → szyfrowanie → wysyłka.
Szczegóły: Integracja z KSeF
Kompletny system do fakturowania z REST API i frontendem webowym.
┌──────────────────────────────────────┐
│ fakturka-web │ ← Frontend (Blade + Tailwind)
└──────────────┬───────────────────────┘
│ HTTP
┌──────────────▼───────────────────────┐
│ fakturka-api │ ← Backend (Laravel 11 + Sanctum)
├──────────────────────────────────────┤
│ SDK Libraries │ ← ksef-client, ksef-xml-parser,
│ │ ksef-crypto-proxy, ksef-qr-code
└──────────────────────────────────────┘
| Komponent | Rola |
|---|---|
fakturka-api |
REST API, logika biznesowa, baza danych |
fakturka-web |
Interfejs użytkownika |
ksef-* |
Integracja z KSeF |
git clone https://github.com/IvY-Rsearch/fakturka-sdk.git
cd fakturka-sdk
docker-compose up -dAplikacja: http://localhost:8080
- Docker + Docker Compose
- PostgreSQL 14+ (w docker-compose)
- Redis (w docker-compose)
- Modularne SDK — użyj tylko co potrzebujesz, reszta opcjonalna
- Oficjalny format FA(3) — nie własny XML, lecz schemat KSeF
- Kryptografia gotowa do integracji — AES-256-CBC, RSA, XAdES
- Czysty podział — parser/walidacja/szyfrowanie/wysyłka osobno
- Pełny przepływ KSeF — od auth po UPO
- Elastyczność — biblioteki albo cały stack na Laravel
| Kto | Przypadek |
|---|---|
| Dostawcy ERP | Dodanie KSeF do istniejącego systemu |
| Platformy SaaS | E-fakturowanie jako funkcja produktu |
| Software house'y | Integracja KSeF dla klientów |
- Biura rachunkowe
- E-commerce (automatyczne faktury)
Dla produkcyjnego użycia sprawdź status i przetestuj z realnym API.
| Cel | Dokument |
|---|---|
| Integracja KSeF | KSEF-INTEGRATION.md |
| Pełna instalacja | INSTALLATION.md |
| Co zaimplementowane | KSEF-FEATURE-MATRIX.md |
| API reference | API-REFERENCE.md |
| Przykłady | EXAMPLES.md |
| Kody QR | QR-CODES.md |
| Licencja | LICENSING-FAQ.md |
Open source: AGPL-3.0
Komercyjna: Wymagana dla SaaS, zamkniętych produktów, ERP.
Szczegóły: LICENSE-COMMERCIAL.md | FAQ: LICENSING-FAQ.md
Kontakt: licencja@fakturka.dev
Nota: To nie jest porada prawna.
Pomoc mile widziana! Repozytorium jest młode.
- Większe zmiany → otwórz issue najpierw
- Małe zmiany (docs, testy) → wcinaj bezpośrednio
- PR musi przechodzić testy + PHPStan
- Styl: PSR-12, PHP 8.2+, DocBlocks
Szczegóły: CONTRIBUTING.md
Zgłaszanie problemów: https://github.com/IvY-Rsearch/fakturka-sdk/issues