hypertractor / laravel-eet
Laravel package for Czech EET 2.0 electronic sales registration — SOAP signing, PKP/BKP generation, and certificate management
Requires
- php: ^8.2
- firebase/php-jwt: ^6.10 || ^7.0
- guzzlehttp/guzzle: ^7.10
- illuminate/database: ^12.0
- illuminate/events: ^12.0
- illuminate/filesystem: ^12.0
- illuminate/http: ^12.0
- illuminate/support: ^12.0
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^10.0
- phpunit/phpunit: ^11.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Laravel package for Czech Electronic Sales Registration (EET 2.0) — SOAP signing, PKP/BKP generation, certificate management, and receipt submission to the Financni sprava endpoint.
Requirements
- PHP 8.2+
- Laravel 12+
- PHP
opensslextension (for certificate handling and signing) - PHP
domextension (for XML building and signing)
Installation
composer require hypertractor/laravel-eet
Publish the config and bundleed playground certificates:
php artisan vendor:publish --tag=eet-config php artisan vendor:publish --tag=eet-certs
Run the migrations to add EET fields to your receipts table and create the eet_submissions audit table:
php artisan vendor:publish --tag=eet-migrations php artisan migrate
Configuration
The .env file:
EET_TEST_MODE=true EET_UNIT_ID=1 EET_TERMINAL_ID=1 EET_CERTIFICATE_PATH=storage/eet/certs/CA_EET-Playground-CZ00000019.p12 EET_CERTIFICATE_PASSWORD=aaaa1111
For production, swap to your real certificate:
EET_TEST_MODE=false EET_CERTIFICATE_PATH=/path/to/your-production.p12 EET_CERTIFICATE_PASSWORD=your-password
Full config reference (config/eet.php):
| Key | Env Variable | Default |
|---|---|---|
endpoint_playground |
EET_ENDPOINT_PLAYGROUND |
https://pg.trzbyeet.gov.cz/eet/services/EETServiceSOAP/v4 |
endpoint_production |
EET_ENDPOINT_PRODUCTION |
https://trzbyeet.gov.cz/eet/services/EETServiceSOAP/v4 |
test_mode |
EET_TEST_MODE |
true |
unit_id |
EET_UNIT_ID |
1 |
terminal_id |
EET_TERMINAL_ID |
1 |
certificate.path |
EET_CERTIFICATE_PATH |
bundled playground cert |
certificate.password |
EET_CERTIFICATE_PASSWORD |
aaaa1111 |
jwt_renewal.enabled |
EET_JWT_RENEWAL_ENABLED |
false |
jwt_renewal.api_url |
EET_JWT_API_URL |
https://ca.caeet.gov.cz/api (prod) |
jwt_renewal.api_url_test |
EET_JWT_API_URL_TEST |
https://ca.test.caeet.gov.cz/api |
jwt_renewal.renew_days_before_expiry |
EET_RENEW_DAYS_BEFORE |
14 |
timeouts.soap |
EET_SOAP_TIMEOUT |
30.0 |
retries.max_attempts |
EET_RETRY_MAX_ATTEMPTS |
3 |
validate_xml |
EET_VALIDATE_XML |
true |
verify_response |
EET_VERIFY_RESPONSE |
true |
eet_off.enabled |
EET_OFF_ENABLED |
false (§ 11 ZoET) |
offline.max_age_hours |
EET_OFFLINE_MAX_AGE_HOURS |
48 (§ 20 ZoET) |
models.receipt |
EET_RECEIPT_MODEL |
(required for EetSubmission::receipt()) |
db_connection |
EET_DB_CONNECTION |
tenant |
Quick Start
Using the Facade
use Pomocnik\Eet\Facades\Eet; use Pomocnik\Eet\DTOs\EetRequest; $request = new EetRequest( eicPopl: 'CZ1234567890', idJednotky: '1', idPokl: '1', poradCis: '1', datTrzby: '2026-07-13T10:00:00+02:00', celkTrzba: '100.00', ); $result = Eet::submit($request); if ($result->success) { echo $result->pokCode; // e.g. "ac51eb11-1f89-4c49-8b2f-986a62bc0ba2-ff" }
Using the Service directly
use Pomocnik\Eet\Services\EetService; $eet = app(EetService::class); $request = $eet->createRequestFromReceipt([ 'eic_popl' => 'CZ1234567890', 'porad_cis' => '1', 'celk_trzba' => 100.00, 'dat_trzby' => now()->format('Y-m-d\TH:i:s'), ]); $result = $eet->submit($request);
EetRequest DTO
Immutable value object representing an EET submission.
Properties
| Property | Type | Required | Description |
|---|---|---|---|
eicPopl |
string |
yes | EIC of the payer (CZ + 9-10 digits) |
idJednotky |
string |
yes | Evidence unit ID |
idPokl |
string |
yes | Cash register / terminal ID |
poradCis |
string |
yes | Receipt sequence number |
datTrzby |
string |
yes | Transaction date (ISO 8601) |
celkTrzba |
string |
yes | Total amount (2 decimal places) |
prvniZaslani |
bool |
no | First submission (default true; every repeated submission uses false and a new UUID, § 20 ZoET) |
uuidZpravy |
?string |
no | Message UUID (auto-generated if null) |
overeni |
bool |
no | Test mode flag |
urcenoCerpZuct |
?string |
no | Amount intended for withdrawal |
cerpZuct |
?string |
no | Amount withdrawn |
eicPoverujiciho |
?string |
no | EIC of the authorizing entity |
povereniVicePopl |
?bool |
no | Authorization for multiple payers |
Factory method
$request = EetRequest::fromReceipt( data: $receipt->toArray(), unitId: config('eet.unit_id'), terminalId: config('eet.terminal_id'), );
Expects array keys: eic_popl, porad_cis, celk_trzba, and optionally dat_trzby, prvni_zaslani, uuid_zpravy, overeni.
$request->validate() checks all fields against XSD v4.1 patterns (CZEICType, IdEvidJednotkyType, string20/25, CastkaType, ISO 8601 with zone, UUID v1-5). EetService::submit() calls it automatically and returns EetResult::failure(-2, ...) on violation.
$request->warnings() performs the non-blocking checks from the FS methodology (Eet_popis_polozek_datove_zpravy, 5. 10. 2026): warning 6 for an id_jednotky that does not match the DIS+ format (at least 2 digits, last digit 1–4) and warning 7 when eicPoverujiciho equals eicPopl. Warnings do not block submission; they are merged with server warnings into EetResult::$warnings.
Deprecated:
rezimandgetSignData()(EET 1.0). EET 2.0 v4.1 does not recordrezimor PKP/BKP — the parameters are ignored, kept only for BC, and will be removed in a major version.
EetResult DTO
Immutable value object returned by EetService::submit().
| Property | Type | Description |
|---|---|---|
success |
bool |
Whether the submission succeeded |
pokCode |
?string |
Potvrzení o přijetí (§ 12 ZoET, Odpoved/Potvrzeni@pok, on success) |
bkpCode |
?string |
Deprecated legacy audit value, not sent to FS |
pkpCode |
?string |
Deprecated legacy audit value, not sent to FS |
testPok |
?string |
test flag of the confirmation (playground) |
fikCode / testFikCode |
?string |
Deprecated aliases of pokCode / testPok |
errorCode |
?int |
FS error kod, or -1 transport, -2 validation, -3 EET OFF skip, -4 response verification |
errorMessage |
?string |
Human-readable error message |
uuidZpravy |
?string |
Message UUID |
warnings |
array<int, EetWarning> |
Server warnings (Odpoved/Varovani) merged with local checks; warningCodes() returns their codes |
transactionId |
?string |
X-Global-Transaction-Id response header (support diagnostics) |
rawResponse |
?string |
Raw XML response |
For repeated submissions (§ 20 ZoET, up to 48 h) use Eet::submitWithRetry($request). Each attempt is sent with prvni_zaslani=false and a new UUID generated by EetRequest::asRepeatedSubmission(); the receipt data itself never changes. This follows the FS methodology of 5. 10. 2026 — reusing the original UUID is a protocol error.
HasEetFields Trait
Add this trait to your Receipt model to get EET columns, accessors, scopes, and auto-defaults.
use Pomocnik\Eet\Models\Concerns\HasEetFields; class Receipt extends Model { use HasEetFields; }
Columns added to receipts table
| Column | Type | Description |
|---|---|---|
pok_code |
VARCHAR(64) null |
POK confirmation code (§ 12 ZoET) |
fik_code |
VARCHAR(64) null |
Deprecated alias of pok_code (EET 1.0 term) |
bkp_code |
VARCHAR(64) null |
Deprecated legacy audit value |
pkp_code |
TEXT null |
Deprecated legacy audit value |
eet_status |
ENUM('pending','sent','failed','cancelled') |
Current status |
eet_submitted_at |
TIMESTAMP null |
When submitted successfully |
eet_first_send |
BOOLEAN |
First submission flag |
eet_test_mode |
BOOLEAN |
Was submitted in test mode |
eet_uuid |
CHAR(36) null |
Message UUID |
Auto-defaults
On creating, the trait sets:
eet_status='pending'eet_first_send=trueeet_test_mode= currentconfig('eet.test_mode')
Accessors
$receipt->is_eet_registered; // true when status === 'sent' $receipt->is_eet_pending; // true when status === 'pending' $receipt->is_eet_failed; // true when status === 'failed'
Query scopes
Receipt::eetPending()->get(); Receipt::eetSent()->get(); Receipt::eetFailed()->get(); Receipt::eetMandatory()->get(); // receipts where paymentType->eet_mandatory = true
EetSubmission Model & Audit Trail
Every submission is logged in the eet_submissions table with full request/response XML. The EetSubmission model provides a receipt() relationship.
use Pomocnik\Eet\Models\EetSubmission; $submissions = EetSubmission::where('receipt_id', $receipt->id) ->orderByDesc('created_at') ->get(); $submissions->first()->request_xml; // full SOAP request $submissions->first()->response_xml; // full SOAP response $submissions->first()->pok_code; $submissions->first()->error_code;
Set EET_RECEIPT_MODEL=App\Models\Receipt (or your tenant model) to enable the receipt() relation, and EET_DB_CONNECTION for the connection (default tenant).
Events
The package dispatches events on submission result. Listen for them in your EventServiceProvider:
use Pomocnik\Eet\Events\EetSubmissionSucceeded; use Pomocnik\Eet\Events\EetSubmissionFailed; protected $listen = [ EetSubmissionSucceeded::class => [ UpdateReceiptEetFields::class, ], EetSubmissionFailed::class => [ LogEetFailure::class, ], ];
Both events expose public readonly EetResult $result.
Certificate Management
Checking certificate status
use Pomocnik\Eet\Certificates\CertificateManager; $cm = app(CertificateManager::class); $info = $cm->getInfo(); echo $info->subject; // "CN=CZ00000019, ..." echo $info->validTo->format('Y-m-d'); // "2027-05-14" echo $info->daysUntilExpiry(); // 304 echo $info->isExpired(); // false
Bundled playground certificates
The package ships with 3 playground .p12 files for testing:
CA_EET-Playground-CZ00000019.p12(password:aaaa1111)CA_EET-Playground-CZ683555118.p12CA_EET-Playground-CZ8551015704.p12
These are automatically published to storage/eet/certs/ via vendor:publish --tag=eet-certs.
JWT certificate renewal (CAEET API)
The package supports automated certificate renewal via the CAEET REST API (JwtRenewalClient: requestRenew() → getStatus() → claimDownload() → ackDownload()). Tokens are RS256 JWTs with the x5t#S256 header, exp max 5 minutes after iat. Endpoints per caeetapi_jwt.yml v2.0 (30. 9. 2026):
EET_JWT_RENEWAL_ENABLED=true EET_JWT_API_URL=https://ca.caeet.gov.cz/api EET_JWT_API_URL_TEST=https://ca.test.caeet.gov.cz/api EET_RENEW_DAYS_BEFORE=14
JwtRenewalClient::fromConfig() picks the test/prod URL from eet.test_mode. Renew 2–3 weeks before expiry; downloaded PKCS#12 expires 30 days after issuance if unclaimed.
EET OFF mode (§ 11 ZoET)
EET_OFF_ENABLED=true
Payers in the 1st flat-tax band (annual income up to CZK 1M) may opt out of registration by notifying the tax office of the CZK 1,400 monthly surcharge (§ 2b and § 38lk(8) of the Income Tax Act, § 11(3) ZoET). For 2027 the notification deadline is 11 January 2027. When enabled, EetService::submit() skips sending and returns EetResult::failure(-3, ...).
XML Validation
The package bundles the official EET XSD schema and can validate both request and response XML before/after submission:
use Pomocnik\Eet\Xml\XmlValidator; $validator = app(XmlValidator::class); $trzbaXml = app(XmlBuilder::class)->buildTrzbaXml($request); $validator->validateTrzba($trzbaXml); // true or throws XmlValidationException
Disable validation in config if needed:
EET_VALIDATE_XML=false
Exceptions
All exceptions extend Pomocnik\Eet\Exceptions\EetException (which extends RuntimeException).
| Exception | When |
|---|---|
CertificateException |
Certificate file not found, invalid, or missing private key |
SoapException |
SOAP transport failure or unparseable server response |
XmlValidationException |
XML fails XSD schema validation, invalid POK format, or UUID mismatch |
EetException |
XML signing failure, invalid request fields, or unconfigured receipt model |
Response verification
On success, EetService verifies that POK is present (unless overeni=true, where code 0 means success without POK), its format (PokType, 39 chars), and that Odpoved/Hlavicka@uuid_zpravy matches the request UUID (ResponseVerifier, enabled via EET_VERIFY_RESPONSE).
SoapResponse parses all <Varovani kod_varov="..."> elements (they are siblings of Potvrzeni/Chyba, up to 10 per response) and the X-Global-Transaction-Id header. EetSoapClient rejects a signed envelope larger than 12 kB (MAX_MESSAGE_BYTES), which is a critical check of the EET specification.
The package bundles the production EET CA chain (certs/ca_eet-root_prod.pem, certs/ca_eet-sub_prod.pem; EETv2 NCA Root CA valid until 2036, SubCA until 2030). Full XMLDSig verification of the FS response signature is not implemented yet — the playground response is signed by an I.CA certificate.
Low-Level Components
XmlBuilder
$xmlBuilder = app(XmlBuilder::class); $trzbaXml = $xmlBuilder->buildTrzbaXml($request); // bare <v4:Trzba> $unsignedEnvelope = $xmlBuilder->buildSoapEnvelope($request); // <soapenv:Envelope> $signedEnvelope = $xmlBuilder->buildSignedSoapEnvelope($request, $certManager); // WS-Security signed
PkpGenerator & BkpGenerator (deprecated)
EET 2.0 v4.1 does not record PKP/BKP (§ 12 ZoET confirms with POK). Both generators are kept only for local audit BC and will be removed in a major version. Their values are never sent to FS.
$pkp = app(PkpGenerator::class)->generate($request, $certManager); // deprecated $bkp = app(BkpGenerator::class)->generate($pkp); // deprecated
XmlSigner
Signs a SOAP envelope with WS-Security XML Digital Signature using Exclusive C14N and RSA-SHA256.
EET 2.0 Timeline (Act No. 180/2026 Sb., published 7. 10. 2026)
- 5. 6. 2026 — Technical documentation v1.0 for developers
- 1. 7. 2026 — Playground available for testing
- 25. 8. 2026 — Interface description v1.2 (UTF-8 + CORS clarifications, XSD/WSDL unchanged at v4.1)
- 2. 10. 2026 — English interface description v1.2a (
porad_cismax length corrected to 25) - 5. 10. 2026 — “Popis položek datové zprávy” v1.0 (field-level methodology, retry rules, warnings)
- 7. 10. 2026 — Act No. 180/2026 Sb. on sales records published in the Collection of Laws (eet.gov.cz news on 15. 10. 2026)
- 1. 11. 2026 — DIS+ registration, evidence units and certificates (MOJE daně)
- 1. 12. 2026 — MOJE EET app for small businesses
- 1. 1. 2027 — Act effective; production endpoint live. Evidence duty applies from day one; January is an onboarding month with methodological support
- 11. 1. 2027 — Deadline to notify the EET OFF surcharge for 2027
- 1. 2. 2027 — Full operation (Financial Administration schedule; the act itself has no transition period)
Only contact payments are registered (cash, card, QR on site); bank transfers and invoices are out of scope. No receipt-printing duty. EET OFF lump-sum opt-out available.
Testing
The package includes 145 tests (PHPUnit 11 + Orchestra Testbench):
cd packages/eet-client
php vendor/bin/phpunit
To run the live Playground test (requires internet):
php vendor/bin/phpunit --filter=EetServiceTest::testSubmitToPlayground
License
MIT