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 ¶
const NamespaceEET = "http://fs.gov.cz/eet/schema/v4"
NamespaceEET is the namespace of the EET 2.0 messages, schema version 4.
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.
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 ¶
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.
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) UnmarshalXML ¶
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.
type Header ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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.
Source Files
¶
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. |