PHPackages                             nozugroup/ksef-client-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. nozugroup/ksef-client-php

ActiveLibrary[API Development](/categories/api)

nozugroup/ksef-client-php
=========================

Thin PHP wrapper client for the Polish KSeF 2.0 API.

0.1.0(2mo ago)08MITPHP ^8.2

Since May 3Compare

[ Source](https://github.com/nozugroup/ksef-client-php)[ Packagist](https://packagist.org/packages/nozugroup/ksef-client-php)[ RSS](/packages/nozugroup-ksef-client-php/feed)WikiDiscussions Synced 3w ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

KSeF Client PHP
===============

[](#ksef-client-php)

Thin, modular PHP wrapper for the KSeF 2.0 REST API.

The endpoint surface was mapped from the official OpenAPI document:

- `https://api.ksef.mf.gov.pl/docs/v2/index.html`
- `https://api.ksef.mf.gov.pl/docs/v2/openapi.json`

The production contract checked for this scaffold reports API build `2.4.0-pr-20260423.2` and base URL `https://api.ksef.mf.gov.pl/v2`.

Install
-------

[](#install)

```
composer install
```

Shape
-----

[](#shape)

Endpoints are grouped into final resource classes:

- `$client->auth()`
- `$client->activeAuthSessions()`
- `$client->certificates()`
- `$client->security()`
- `$client->limits()`
- `$client->permissions()`
- `$client->invoices()`
- `$client->sessions()`
- `$client->tokens()`
- `$client->peppol()`

The public API avoids raw request arrays. JSON/XML bodies, query parameters, headers, path parameters, requests, response headers, and decoded JSON are represented by final classes.

Basic Usage
-----------

[](#basic-usage)

```
use Nozu\KsefClient\Http\JsonBody;
use Nozu\KsefClient\KsefClient;

$client = KsefClient::test();

$challenge = $client->auth()->createChallenge()->json()?->object();

$auth = $client->auth()->authenticateWithKsefToken(
    JsonBody::fromObject((object) [
        'challenge' => $challenge?->challenge,
        'contextIdentifier' => (object) [
            'type' => 'Nip',
            'value' => '1234567890',
        ],
        'encryptedToken' => '...',
    ])
)->json()?->object();

$authStatus = $client->auth()->status($auth->referenceNumber)->json()?->object();
```

After you redeem an access token, pass it into the client:

```
use Nozu\KsefClient\Http\QueryParameters;

$client = KsefClient::test($accessToken);

$sessions = $client->sessions()->list(
    QueryParameters::empty()
        ->withString('sessionType', 'Online')
        ->withInt('pageSize', 10)
)->json()?->object();
```

For repeated OpenAPI query parameters, use `StringList`:

```
use Nozu\KsefClient\Http\StringList;

$query = QueryParameters::empty()
    ->withString('sessionType', 'Online')
    ->withValues('statuses', new StringList('InProgress', 'Succeeded'));
```

For paginated endpoints with continuation tokens, use `Headers`:

```
use Nozu\KsefClient\Http\Headers;

$tokens = $client->tokens()->list(
    QueryParameters::empty()->withInt('pageSize', 10),
    Headers::continuationToken('...')
);
```

For operations that return XML or binary-like payloads, use `body()`:

```
$invoiceXml = $client->invoices()->getByKsefNumber('...')->body();
$upoXml = $client->sessions()->upo('...', '...')->body();
```

Generic Request Escape Hatch
----------------------------

[](#generic-request-escape-hatch)

The client exposes typed resource methods for every endpoint in the current OpenAPI contract, but you can still call new or changed endpoints directly:

```
use Nozu\KsefClient\Http\KsefRequest;

$response = $client->send(KsefRequest::get('/rate-limits'));
```

Notes
-----

[](#notes)

This package does not implement cryptographic preparation of XAdES signatures, encryption of KSeF tokens, or invoice XML generation. Those are separate domain steps; this client is responsible for HTTP transport, authentication headers, endpoint paths, query/header handling, JSON/XML bodies, and response/error wrapping.

QR Codes
--------

[](#qr-codes)

KSeF QR codes are generated locally from invoice data. The package supports:

- KOD I: invoice verification/download URL and QR code.
- KOD II: offline certificate verification URL and QR code signed with the KSeF Offline certificate private key.

```
use Nozu\KsefClient\Qr\InvoiceHash;
use Nozu\KsefClient\Qr\IssueDate;
use Nozu\KsefClient\Qr\QrCodeService;
use Nozu\KsefClient\Qr\QrLabel;
use Nozu\KsefClient\Qr\SellerNip;

$qr = QrCodeService::test();

$link = $qr->invoiceLink(
    new SellerNip('1111111111'),
    IssueDate::fromKsefFormat('01-02-2026'),
    InvoiceHash::fromBase64Url('UtQp9Gpc51y-u3xApZjIjgkpZ01js-J8KflSPW8WzIE')
);

$png = $qr->invoiceQr(
    new SellerNip('1111111111'),
    IssueDate::fromKsefFormat('01-02-2026'),
    InvoiceHash::fromInvoiceXml($invoiceXml),
    QrLabel::offline()
);
```

For KOD II:

```
use Nozu\KsefClient\Qr\CertificateSerialNumber;
use Nozu\KsefClient\Qr\ContextIdentifier;
use Nozu\KsefClient\Qr\OfflineCertificatePrivateKey;

$certificateQr = $qr->certificateQr(
    ContextIdentifier::nip('1111111111'),
    new SellerNip('1111111111'),
    new CertificateSerialNumber('01F20A5D352AE590'),
    InvoiceHash::fromInvoiceXml($invoiceXml),
    OfflineCertificatePrivateKey::fromPem($offlineCertificatePrivateKeyPem)
);

$bytes = $certificateQr->bytes();
```

KOD II signing follows the MF rules: RSA uses RSASSA-PSS with SHA-256, MGF1 SHA-256, and 32-byte salt; ECDSA uses P-256/SHA-256 and IEEE P1363 signature encoding.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance84

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

82d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/22442118?v=4)[Yusuke Yoshinobu](/maintainers/nozu)[@Nozu](https://github.com/Nozu)

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nozugroup-ksef-client-php/health.svg)

```
[![Health](https://phpackages.com/badges/nozugroup-ksef-client-php/health.svg)](https://phpackages.com/packages/nozugroup-ksef-client-php)
```

###  Alternatives

[leantime/leantime

Open source project management system for non-project managers. Simple like Trello, powerful like Jira. Built with neurodiversity in mind.

10.2k4.0k](/packages/leantime-leantime)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)[n1ebieski/ksef-php-client

PHP API client that allows you to interact with the API Krajowego Systemu e-Faktur

9067.8k](/packages/n1ebieski-ksef-php-client)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k46](/packages/civicrm-civicrm-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M600](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)