Search by

hypertractor / laravel-eet

hypertractor

Laravel package for Czech EET 2.0 electronic sales registration — SOAP signing, PKP/BKP generation, and certificate management

Package info

github.com/hypertractor/laravel-eet

pkg:composer/hypertractor/laravel-eet

Statistics

Installs: 10

Dependents: 0

Suggesters: 0

Stars: 2

Open Issues: 4

1.1.0 2026-11-11 12:17 UTC

This package is auto-updated.

Last update: 2026-11-11 13:05:02 UTC


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 openssl extension (for certificate handling and signing)
  • PHP dom extension (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: rezim and getSignData() (EET 1.0). EET 2.0 v4.1 does not record rezim or 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 = true
  • eet_test_mode = current config('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.p12
  • CA_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_cis max 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