eet

package module
v0.0.0-...-bcc8f5e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

README

GOBL ⬅️➡️ Czech EET 2.0

Czech EET 2.0 sales recording for GOBL: the cz-eet-v1 addon, a converter from invoices to the EET data message, a WS-Security signer, and a reader for the service's responses.

Released under the Apache 2.0 LICENSE, Copyright 2026 Invopop S.L..

Lint Test Go Go Report Card codecov GoDoc Latest Tag

EET 2.0 in short

From 1 January 2027, every sale paid in person in the Czech Republic (cash, card at the counter, vouchers and similar) is sent to the Financial Administration as a signed data message, Trzba, which answers with a confirmation code, the POK. The message has no lines, taxes or customer: only the merchant's tax ID, the recording unit and device of the sale, its sequence number and time, and the total in CZK. Each merchant signs with their own certificate from the CA EET. The interface description, schema and samples are on eet.gov.cz.

The addon

Import the addon to register it, then declare cz-eet-v1 on a standard or simplified invoice, or a credit note for a refund:

import _ "github.com/invopop/gobl.cz.eet/addon"
$schema: "https://gobl.org/draft-0/bill/invoice"
$regime: "CZ"
$addons:
  - "cz-eet-v1"
series: "PRG"
code: "000135"
issue_date: "2027-01-09"
issue_time: "16:45:36"
tax:
  ext:
    cz-eet-unit: "303"
    cz-eet-device: "POS-1"
supplier:
  name: "Kavárna u Mostu s.r.o."
  tax_id:
    country: "CZ"
    code: "12345679"
# ...
Key Kind EET item
cz-eet-unit Extension in tax.ext id_jednotky, the recording unit number from DIS+
cz-eet-device Extension in tax.ext id_pokl, the end device within the unit
cz-eet-pok Stamp pok, the confirmation code

The rules ask for what the message needs and an invoice may lack: a Czech supplier tax ID, an issue time, both extensions, CZK or an exchange rate to CZK, a series and code that fit porad_cis, and a total within ±99,999,999.99 CZK. Full examples are in examples.

The issue date and time are the moment of the sale in Czech local time (Europe/Prague), which EET records with seconds. An issue time taken from a server clock in another zone records the sale at the wrong hour without any error.

Sending a sale

import (
	eet "github.com/invopop/gobl.cz.eet"
	_ "github.com/invopop/gobl.cz.eet/addon"
)

signer, err := eet.NewSignerFromPKCS12(p12, password) // the merchant's CA EET certificate

sale, err := eet.NewSale(inv)  // a calculated invoice with the cz-eet-v1 addon
request, err := signer.Sign(sale)

// POST the request over HTTP/1.1 with these headers, eet.SOAPAction quoted:
//   Content-Type: text/xml; charset=utf-8
//   SOAPAction: "http://fs.gov.cz/eet/OdeslaniTrzby"
// then read the answer:
res, err := eet.ParseResponse(body, sale, eet.DefaultTrust())
switch {
case err != nil:
	// a SOAP fault, an unreadable answer, a confirmation that isn't genuine,
	// or the answer to another message (eet.ErrWrongMessage): nothing to
	// keep, send again later
case res.Confirmation != nil:
	// keep res.Confirmation.POK as the cz-eet-pok stamp
case res.Error.Code.Retry():
	// send again later, within 48 hours: eet.NewSale(inv, eet.WithResend())
default:
	// fix the data or the setup: res.Error says what failed
}

NewSale makes a new message, with its own UUID and send time, on every call, so build one per attempt. Data.SaleKey() identifies the sale across attempts. WithVerification() asks the service to check a message without recording it.

ParseResponse only accepts a confirmation signed by a certificate the trust accepts, for the very message it is given. DefaultTrust is the I.CA chain described in ca and accepts production confirmations only; set its Playground field when sending to the Playground, whose replies are signed under the same chain. Build your own Trust to change the roots or the expected organisation. Revocation is not checked: an app that needs it fetches I.CA's revocation lists itself.

The response checks rely on Go's certificate and XML code, so the module asks for Go 1.26.10, the first release that fixes what govulncheck finds reachable from them. Build the app with the latest Go 1.26 patch release.

Development

go test ./...
go test . -update      # rewrite the golden files in examples/out

The signer is tested against the three official signed sample requests in test/samples, and the response reader against Playground replies in test/responses.

Documentation

Overview

Package eet sends GOBL invoices to the Czech Financial Administration's EET 2.0 sales-recording service: it builds the Trzba message, signs it with WS-Security and reads the Odpoved response. The GOBL addon with the EET extensions and rules lives in the addon subpackage.

Index

Constants

View Source
const NamespaceEET = "http://fs.gov.cz/eet/schema/v4"

NamespaceEET is the namespace of the EET 2.0 messages, schema version 4.

View Source
const OrganizationGFR = "Generální finanční ředitelství"

OrganizationGFR is the organisation in the subject of the certificates that sign the service's confirmations: the General Financial Directorate.

View Source
const SOAPAction = "http://fs.gov.cz/eet/OdeslaniTrzby"

SOAPAction is the action of the service's one operation, OdeslaniTrzby. SOAP 1.1 sends it in quotes: SOAPAction: "http://fs.gov.cz/eet/OdeslaniTrzby".

Variables

View Source
var ErrWrongMessage = errors.New("eet: response answers another message")

ErrWrongMessage says the response answers another message than the sale it was read for, as a replayed or crossed answer would. Treat it like no answer at all: the sale is not confirmed, send it again.

Functions

This section is empty.

Types

type Confirmation

type Confirmation struct {
	// POK (pok) is the confirmation code. A resend gets a new one, so keep
	// the first.
	POK string `xml:"pok,attr"`
	// Test (test) is true outside production.
	Test bool `xml:"test,attr"`
}

Confirmation (Potvrzeni) that the sale was recorded.

func (*Confirmation) UnmarshalXML

func (c *Confirmation) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML reads a Potvrzeni element, refusing one without a POK rather than giving an empty confirmation code.

type Data

type Data struct {
	// TaxID (eic_popl) of the merchant, the CN of the signing certificate.
	TaxID string `xml:"eic_popl,attr"`
	// DelegatingTaxID (eic_poverujiciho) of the merchant that delegated the
	// recording, when there is one.
	DelegatingTaxID string `xml:"eic_poverujiciho,attr,omitempty"`
	// DelegatedByMany (povereni_vice_popl) when several merchants delegated
	// the recording.
	DelegatedByMany bool `xml:"povereni_vice_popl,attr,omitempty"`
	// UnitID (id_jednotky) of the recording unit, as registered in DIS+.
	UnitID string `xml:"id_jednotky,attr"`
	// DeviceID (id_pokl) of the end device within the unit.
	DeviceID string `xml:"id_pokl,attr"`
	// Number (porad_cis) of the sale in the device's sequence.
	Number string `xml:"porad_cis,attr"`
	// SoldAt (dat_trzby) is the local time of the sale.
	SoldAt string `xml:"dat_trzby,attr"`
	// Total (celk_trzba) amount paid, in CZK.
	Total string `xml:"celk_trzba,attr"`
	// PrepaidLoad (urceno_cerp_zuct) is the part of the total meant to be
	// drawn down or settled later, such as a voucher sold.
	PrepaidLoad string `xml:"urceno_cerp_zuct,attr,omitempty"`
	// PrepaidUse (cerp_zuct) is the part paid by drawing down an earlier
	// prepayment.
	PrepaidUse string `xml:"cerp_zuct,attr,omitempty"`
}

Data (Data) describes the sale itself.

func (*Data) SaleKey

func (d *Data) SaleKey() string

SaleKey identifies a sale: its six values joined with '|'. Messages with the same key are attempts to record the same sale, so the key tells a duplicate confirmation apart from a new sale.

type Error

type Error struct {
	Code    ErrorCode `xml:"kod,attr"`
	Test    bool      `xml:"test,attr"`
	Message string    `xml:",chardata"`
}

Error (Chyba) explains why a sale was not recorded. In verification mode, code 0 says the message passed every check.

func (*Error) Error

func (e *Error) Error() string

Error gives the code and the service's text.

func (*Error) UnmarshalXML

func (e *Error) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML reads a Chyba element, refusing one without a numeric code: a missing code would otherwise read as 0, the verification success.

type ErrorCode

type ErrorCode int

ErrorCode (kod) of a response. Match on the code, not on the text, which differs between versions of the spec.

const (
	// ErrorCodeTemporary is a temporary technical error: send again later.
	ErrorCodeTemporary ErrorCode = -1
	// ErrorCodeVerified says, in verification mode, that the message passed
	// every check.
	ErrorCodeVerified ErrorCode = 0
	// ErrorCodeEncoding says the XML encoding is not valid.
	ErrorCodeEncoding ErrorCode = 2
	// ErrorCodeSchema says the message fails the XML schema.
	ErrorCodeSchema ErrorCode = 3
	// ErrorCodeSignature says the signature is invalid, or the certificate is
	// not trusted, not valid or revoked.
	ErrorCodeSignature ErrorCode = 4
	// ErrorCodeTaxID says the merchant's tax ID (eic_popl) has a wrong
	// structure.
	ErrorCodeTaxID ErrorCode = 6
	// ErrorCodeTooLarge says the message is over 12 kB.
	ErrorCodeTooLarge ErrorCode = 7
	// ErrorCodeProcessing is a technical or data error in processing: send
	// again later.
	ErrorCodeProcessing ErrorCode = 8
)

Error codes of the interface description, chapter 3.5. Code 1 does not exist and 5 was used before version 4 only.

func (ErrorCode) Retry

func (c ErrorCode) Retry() bool

Retry reports whether the sale can be sent again later as it is, as a resend with a new message (codes -1 and 8). The others need the data or the setup fixed first.

type Header struct {
	// UUID (uuid_zpravy) of the message, new for every attempt, resends
	// included.
	UUID string `xml:"uuid_zpravy,attr"`
	// SentAt (dat_odesl) is when the message was sent.
	SentAt string `xml:"dat_odesl,attr"`
	// FirstAttempt (prvni_zaslani) is false on a resend.
	FirstAttempt bool `xml:"prvni_zaslani,attr"`
	// Verification (overeni) asks the service to check the message without
	// recording it: the response has error code 0 and no POK.
	Verification *bool `xml:"overeni,attr,omitempty"`
}

Header (Hlavicka) identifies one attempt to send a sale.

type Option

type Option func(*options)

Option adjusts the message built for a sale.

func WithResend

func WithResend() Option

WithResend marks the message as a resend (prvni_zaslani false), for any attempt after the first. Resends are due within 48 hours of the sale.

func WithVerification

func WithVerification() Option

WithVerification asks the service to check the message without recording the sale (overeni): the response carries error code 0 and no POK. Useful to test a merchant's setup.

type Response

type Response struct {
	Header       *ResponseHeader `xml:"http://fs.gov.cz/eet/schema/v4 Hlavicka"`
	Confirmation *Confirmation   `xml:"http://fs.gov.cz/eet/schema/v4 Potvrzeni"`
	Error        *Error          `xml:"http://fs.gov.cz/eet/schema/v4 Chyba"`
	Warnings     []*Warning      `xml:"http://fs.gov.cz/eet/schema/v4 Varovani"`
}

Response (Odpoved) is the service's answer to a sale message: a confirmation with the POK when the sale is recorded, or an error, and up to ten warnings either way.

func ParseResponse

func ParseResponse(data []byte, sale *Sale, trust *Trust) (*Response, error)

ParseResponse reads the service's SOAP response to the sale message sent. A confirmation must be signed by a certificate the trust accepts and answer that very message, or ParseResponse fails: the POK is only worth keeping when it's genuine and for this sale. Errors come unsigned, as the service sends them, and may leave out the UUID of the message they answer. A response to another message fails with ErrWrongMessage.

type ResponseHeader

type ResponseHeader struct {
	// UUID (uuid_zpravy) of the message answered.
	UUID string `xml:"uuid_zpravy,attr"`
	// ReceivedAt (dat_prij) is when the sale was recorded.
	ReceivedAt string `xml:"dat_prij,attr"`
	// RejectedAt (dat_odmit) is when the message was rejected.
	RejectedAt string `xml:"dat_odmit,attr"`
}

ResponseHeader (Hlavicka) of a response.

type Sale

type Sale struct {
	XMLName xml.Name `xml:"v4:Trzba"`
	Header  *Header  `xml:"v4:Hlavicka"`
	Data    *Data    `xml:"v4:Data"`
}

Sale is the data message of a recorded sale (Trzba), the one request the EET service accepts. Values are kept as they go on the wire: the converter formats amounts and times, and optional attributes that don't apply stay empty so they're left out, as the service rejects empty ones.

func NewSale

func NewSale(inv *bill.Invoice, opts ...Option) (*Sale, error)

NewSale builds the EET data message for a sale recorded as a calculated GOBL invoice with the cz-eet-v1 addon. The invoice's issue date and time are read as Czech local time. Each call makes a new message, with its own UUID and send time, so build one for every attempt, resends included; the sale data stays the same across attempts.

type Signer

type Signer struct {
	// contains filtered or unexported fields
}

Signer signs EET requests with the merchant's own certificate, the one the CA EET issues through DIS+ with the merchant's tax ID as CN.

func NewSigner

func NewSigner(cert *x509.Certificate, key crypto.Signer) (*Signer, error)

NewSigner prepares a signer from the merchant's certificate and its private key, which must be RSA: the service only takes RSA-SHA256.

func NewSignerFromPKCS12

func NewSignerFromPKCS12(data []byte, password string) (*Signer, error)

NewSignerFromPKCS12 prepares a signer from a PKCS#12 (.p12) file as the CA EET issues it, including the legacy RC2 and 3DES encryption it uses.

func (*Signer) Certificate

func (s *Signer) Certificate() *x509.Certificate

Certificate returns the certificate the signer signs with.

func (*Signer) Sign

func (s *Signer) Sign(sale *Sale) ([]byte, error)

Sign returns the SOAP request that carries the sale, signed the way the EET service requires: only the body is signed, with exclusive canonicalization, SHA-256 and RSA-SHA256, and the certificate travels in a BinarySecurityToken. Element IDs derive from the message UUID.

type Trust

type Trust struct {
	Roots         *x509.CertPool
	Intermediates *x509.CertPool
	Organization  string

	// Playground accepts only the Playground's test confirmations (test
	// true) instead of production ones. Both environments sign with the
	// same chain and organisation, so this is what keeps a test POK off a
	// real sale.
	Playground bool
	// contains filtered or unexported fields
}

Trust decides which certificates may sign the service's confirmations: those that chain up to one of the Roots, through the Intermediates when needed, are valid at the time of the check, and name the Organization in their subject. The common name is not checked: it differs between the Playground and production and may change on renewal. Nor is revocation: an app that needs it fetches and caches I.CA's revocation lists itself.

func DefaultTrust

func DefaultTrust() *Trust

DefaultTrust trusts the Financial Administration's certificates issued by I.CA Public CA/RSA 06/2022 under I.CA Root CA/RSA 05/2022, the chain that signs the Playground's confirmations and that the operations documents name for production. It accepts production confirmations only: set Playground to work against the Playground. The ca directory has the certificates' sources.

type Warning

type Warning struct {
	Code    WarningCode `xml:"kod_varov,attr"`
	Message string      `xml:",chardata"`
}

Warning (Varovani) about a sale that was recorded all the same.

type WarningCode

type WarningCode int

WarningCode (kod_varov) of a response.

const (
	// WarningCodeTaxIDMismatch says the merchant's tax ID differs from the
	// CN of the signing certificate.
	WarningCodeTaxIDMismatch WarningCode = 1
	// WarningCodeDelegatingTaxID says the delegating merchant's tax ID has a
	// wrong structure.
	WarningCodeDelegatingTaxID WarningCode = 2
	// WarningCodeSaleTimeAhead says the sale time is more than 2 hours after
	// the message was received.
	WarningCodeSaleTimeAhead WarningCode = 4
	// WarningCodeSaleTimeOld says the sale time is more than 2 years before
	// the message was received, or before the environment's first day.
	WarningCodeSaleTimeOld WarningCode = 5
	// WarningCodeUnitID says the unit ID doesn't have the form DIS+ gives
	// units.
	WarningCodeUnitID WarningCode = 6
	// WarningCodeSelfDelegation says the delegating merchant is the merchant
	// itself.
	WarningCodeSelfDelegation WarningCode = 7
)

Warning codes of the interface description, chapter 3.4.

Directories

Path Synopsis
Package addon provides the cz-eet-v1 GOBL addon for Czech EET 2.0 sales recording: the extensions that identify where a sale happened, the stamp for the confirmation code, and the rules an invoice must meet before it can be sent.
Package addon provides the cz-eet-v1 GOBL addon for Czech EET 2.0 sales recording: the extensions that identify where a sale happened, the stamp for the confirmation code, and the rules an invoice must meet before it can be sent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL