EFR Rule Set

Important Information to the generic Interface

The API is a generic interface that can be used for all countries. If there are additional country-specific requirements, these are described in the country-specific guides. The generic interface is available from EFR version 2.5.0. The changes to the interface are backwards compatible.

Webservice Reference

EFR operates as local webserver on the cash register or within LAN. Local installation is recommended, otherwise the cash register could not issue fiscal receipts in case of network failure. Port 5618 is used for HTTP communication and UDP messaging (reserved with IANA).

Example URL: http://localhost:5618/register

Query Parameters, Request Body and Headers are specified, if needed. On GET requests commonly the body may be left empty.

By default query parameter names are not case sensitive. Be sure to encode special characters in parameter values (read more on w3schools.com).

Some requests can deliver XML or JSON response content. The format is choosen upon the request body format or is set to XML, if an optional request header accept: xml was set. Default response format is JSON.

Communication Workflow

After finishing processing positions and payment, the cashier application transfers resulting transaction data to the EFR for signing. The generated signature is to be printed on the sales slip.

The success status of the transactions registration with the EFR is returned within tag <Result>. The relevant information is ResultCode RC:

Result Code RC	HTTP-Statuscode	Reason	Action within frontend application
OK	200 OK	Transaction processd successfully	Print receipt
BAD	400 Bad Request	Invalid request data	Terminate transaction Check transaction data
NO	406 Not Acceptable	Could not process transaction, another try at a later time might be successful though	Retry Y/N On "N" terminate transaction

EFR software will always will respond 200 OK when

• Software installation was successful
• The request complies with formal parameters (XML structure)
• Local infrastructure is operational (i.e. hard disk)

Timing Considerations

EFR is designed to respond reliably within 10 seconds, so a request timeout of 10 sec should be set. Typically transaction registration with online fiscal systems will need about 1 sec for completion, local signature about 250 ms.

An exception to this behaviour are installations, where the transaction has to be printed over a Fiscal Printer (e.g. [IT, PL, SK,…] ). In this case, printout completion is awaited before response. Depending on printer speed and number of positions, the printout may require up to 30 sec. A delay also may occur when the paper out (and insertion of a new paper reel) is handled internally by printer firmware.

For fiscal printer installations there are following valid methods of interaction:

Without Timeout

Wait infinitely for /register response. In case of system crash, resend the transaction on restart (preferably with /restart instead of /register, duplicate detection operates more specific this way; see Restart Handling).

With Timeout

Set a timeout of 10000 ms on your request. In case of a timeout, use subsequent GET /last requests in a loop (e.g. once a second). During transaction processing HTTP status "423 Locked" is responded, after completion the usual registration response. If no response is received, the communication to EFR may be broken. After restoration perform Restart Handling (see 4.3 Restart Handling).

Full RFC 2518 Implementation

In this configuration a HTTP status 102 is given as interim response to inform the client, that the server has accepted the request, but not yet completed it. For this, enter the following string in the Profile field Attributes (see 6.1 profile.cfg | Attributes):

HttpServer_respond102=9000

The value represents the interim response interval in ms.

Good to know

At any time GET /last (or GET /last?\_=Tra, GET /state, GET /log) requests may be used, even during transaction processing. These requests are responded from cache and will not affect the system performance.

Restart Handling

It is essential to keep the fiscal system and the cash register database in parallel. A transaction has to be in both systems, or none of them. A classic test case is the start of a transaction and power loss before completion. In this case the EFR expects the repetition of the last transaction immediately after restart. If the transaction had been processed before, the registration result is delivered, else the whole registration is performed.

To initiate this restart behaviour use WebRequest /restart instead of /register.

If the transaction was registered successfully before, the result is returned containing the notification #DUPLICATE:

<TraC SQ="2345">
    <Result RC="OK">
        <ErrorCode>#DUPLICATE</ErrorCode>
    </Result>
    <Fis>…
</TraC>

Cfg - Configuration

The configuration must be sent before the first transaction. It is recommended to send the configuration to the EFR service every time the cash register is started in order to keep it up to date. The individual parts of the configuration are described in the following tables.

Cmp - Company

Name	Description	Country	Example
Nam	Company name		"My Company"
label	Company short name for digital receipt		"MyComp"
Adr	Company address		"Street"
AdrNr	Street number		"3"
Zip	Postcode		"1000"
City	City		"City"
Ctry	Country ISO-3166		"XY"
TaxId	Intra community VAT identifier. Please configure the tax id in the profile		"XY99999999999"
TIN	Tax Identification e.g.: "Steuernummer"	DE	"123456789"
Org	Organization number assigned by Swedish tax authority, required for CCU enrollment and usage. Format: NNNNNN-NNNN	SE	"373737-3737"
VATonPayment	VAT chargeable on receipt of payment (default: on issuance of invoice)	FR	0
FR_NAF	Code NAF/APE / Activity Type Code in France	FR	"47.11D"
FR_SRN	SIREN / Business Register Identifier	FR	"732 829 32"
FR_RCS	Lieu d'immatriculation + lettre "A" ou "B" (commerce ou société) / City of Registration + Category	FR	"PARIS A"
FR_TYPE	Legal Form	FR	"XXX"
FR_CAPITAL	Social Capital	FR	"XXX"
FR_METIER	Trades Directory Registration Number	FR	"XXX"

Loc - Location

Name	Description	Country	Example
TL	Transaction Location code / store number		"001"
Nam	Location name		"My Location"
label	Location name Location short name for bill.efsta		"MyLoc"
Adr	Store address		"Long Road"
AdrNr	Street number		"123"
Zip	Postcode		"12345"
City	City		"Metropolis"
State	State/Region		"XXX"
Ctry	Country ISO-3166		"XY"
TaxId	Intra community VAT identifier		"XY99999999999"
FR_SIR	SIRET / Geographic Identification of a French Establishment	FR	"732 829 320 0007"

Trm - Terminal

Name	Description	Country	Example
TT	Transaction Terminal code / number of cash register		"1"
SW	POS software name		"My POS Software"
SWVersion	Software Version	DE, FR, SE	"3.2.7"
HW	Hardware brand		"POS Brand"
HWModel	Hardware model	DE, SE	"POS Model"
Serial	Hardware serial number		"POS serial number"

Doc - e-Invoicing

Name	Description	Example
ContactName	Contact Name of the Sender	"Invoicing Department"
ContactTelephone	Contact Phone Number of the sender	"123456789"
ContactElectronicMail	EMail address of the sender	"office@efsta.eu"
PaymentTerms	Terms of the payment	"30 days net"
PaymentPeriod	Terms of the payment in days (payment deadline)	30
AccountName	Bank account holder	"my company"
AccountIBAN	IBAN of the bank account	"AT00000000000000000000"
AccountBIC	BIC of the bank account	"ASPAKAT2LXXX"

Dev - Input Devices

Name	Description	Country	Example
Id	Input Device Identification	DE	"1"
HW	Input Device Hardware brand	DE	"Dev Brand"
HWModel	Input Device Hardware model	DE	"Dev Model"
SW	Input Device Sofware name	DE	"My Dev Software"
SWVersion	Input Device Software version	DE	"1.5.7"
Serial	Input Device Serial	DE	"POS serial number"

DE_Agentur - Agency

Name	Description	Country	Example
Id	Agency Identification	DE	"1"
Nam	Agency Name	DE	"Test Company"
Adr	Agency Adr	DE	"177 Long Road"
Zip	Agency Postcode	DE	"12345"
City	Agency City	DE	"Metropolis"
Ctry	Agency Country ISO-3166	DE	"XY"
TaxId	Agency Intra community VAT identifier	DE	"XY99999999999"

ESR – "efsta Simple Receipt" Format

This section describes the standard elements. Beyond these the XML document may contain company specific additional elements and fields. Please note that the list of standardized elements may be extended, in this case only 1 to 4-letter tag names are used. Consequently we advise that for additional tags at least 5-letter denominations or separate XML-namespaces be used.

note

All amounts (Datatype Currency) within the datasets shall be local currency except otherwise noted.

License

The "efsta Simple Receipt" format described in this chapter is intellectual property of efsta and is licensed under the terms of GNU General Public License (GPL).

It may be used freely, provided the following provisions are kept:

• Denomination of the format remains ESR "efsta Simple Receipt"
• Extensions as such conform to the formal rules of ESR (attribute names at least 5 letters length)
• Publicly accessible storage systems (Internet) must provide suitable access control to personal vouchers or receipts

Request Tra (Transaction)

Registration of a sales transaction.

ESR Elements

Attribute	Name	Description	Datatype	Mandatory
	efsta Simple Receipt	Receipt Body		MANDATORY
D	Date Time	Date Time Seconds have to be specified according to fiscal law Example: "2016-08-01T13:28:22"	DateTime	MANDATORY Default: system time
D0	Date Time Start	Timestamp of the process start Example: "2016-08-01T13:28:22"	DateTime	[DE]
TaxId	VAT Number	Important for centralized multi company multi client EFR installations with RN__TT=true Example: "DE123456789"	Text	Optional
TL	Transaction Location	Business Premise / Store ID Has to be unique within a company. For compatibility, if omitted TL is extracted from TT, e.g.: TT="44/7" => TL="44" TT="7" Example: "4012"	Text
TT	Transaction Terminal	Cash Register Terminal Number Has to be unique within TL. TL+"/"+TT is used as unique terminal identification within a Company Example: "7"	Text	MANDATORY Default: '1'
TN	Transaction Number	Sequential receipt number If only fiscally mandatory transactions are registered, continuous (gapless) sequence of receipt numbers has to be shown by TLOG of the cashier system Default: TN is incremented automatically starting with "1". Example: "450023"	Text	MANDATORY Default: autoincrement
T	Total	Amount of total sum of collected means of payment Can be omitted for nonfiscal transactions Default: for fiscal transactions total of TaxA\[\] or PosA\[\] amounts respectively. Example: "123.00"	Currency	Recommended Default: sum(PosA\[\].Amt)
TaxN	Net Tax Flag	Positions are Net Tax, tax is added at end of printout Not supported in all countries! Example: "1"	Boolean 0/1
Opr	Operator ID	Operator-ID	Text	[DE] [FR]
OprN	Operator Name	Operator-Name	Text	[DE]
DT	Document Type	Indicates a class of document, controls fiscal treatment of transaction; Viable for Fiscal, NF, NFS; not defined = fiscal Example: "Fiscal, ticket, invoice"	Text	[FR]
DN	Document number	Sequential number; Number range is of a specific document type DT, e.g. invoice number; additional to TN Example: "A23"	Text
DD	Document Delivery	Sets the delivery method for this transaction. (see there) Example: "Email, digital, noprint"	Text
NF	Nonfiscal Transaction Type	This attribute denominates nonfiscal transaction (e.g. balance | closure, operator login/logout, payin/payout). These are registered in the receipt journal so the sequence of receipt numbers TN is gapless, but not added to the fiscal Grand Totals. Example: "PAYIN"	Text	[DE]
NFS	Nonfiscal Signed	Equal to NF, but a fiscal signature is applied if required by law Example: "TRAINING"	Text	MANDATORY (except [CZ] [HR] [SI])
Void	Void Transaction	A transaction registered before is voided; usually amount fields (except Pos.Pri) are negative. Specify ESR.RD, RTL, RTT, RTN Example: "1"	Boolean 0/1	[AT] [DE]
Test	Test / Training Transaction	Training transactions are sent to the fiscal system marked as "test". The Response <Fis> element then contains a "*** TEST ***" info tag. Example: "1"	Boolean 0/1	[AT] [FR]
RFN	Reference Fiscal Number	Needed in some countries in case of return or void as reference to original sale	Text	[IT] [PT] [SK]
TP	Transaction Point	Point of transaction (e.g. table number, department) Example: "Tisch 5"	Text	[DE]
Rsn	Reason	Reason text for exceptional transaction, position or modifier, e.g. reason for return of goods, reprint Example: "Erreur d'imprimante"	Text	[FR] [PT]
BE_OperatorId	Operator	Social Security Number of employee (NISS/INSZ) Required only if value differs from field Opr Example: "79100590097"	Number	[BE]
CZ_id_provoz	Business premise ID	Can also be specified in EFR profile	Text	[CZ]
FR_OperationType	Operation Type	"Vente" or "Remboursement" Depending on ESR.T signum	Text	[FR]
FR_Trainer	Trainer / Supervisor	Fiscal regulations require the ID of the trainer/supervisor to be stored with the training transaction	Text	[FR]
HR_OibOper	Operator	Tax Number Default: specify in EFR profile	Text	[HR]
HR_SpecNamj	Additional Invoice Information		Text	[HR]
SI_OperatorTaxNumber	Operator	Tax Number	Text	[SI]
SK_ParagonNumber	Paragon Number	Number of Paragon	Text	[SK]

Ctm Elements

Attribute	Name	Description	Datatype	Mandatory
	Customer	Customer data If registered for invoice or if required by law		[DE] [FR] [IT] [PL]
Nam	Name	Customer or Company Name	Text	[DE] [FR]
Nam2	Name 2	Name Extension	Text	[DE]
Adr	Address	Customer or Company Address within City	Text	[DE]
Adr2	Address 2	Address Extension	Text	[DE]
AdrNr	Address Number	Street number	"Text	[DE]
Zip	Postal Code	According to national rules without country prefix	Text	[DE] [FR]
City	City	City Name	Text	[DE]
Ctry	Country	Country ISO 3166 ALPHA-2	Text	[DE]
TaxId	VAT Number	Customer or Company VAT Number including eventual country prefix	Text	[DE] [FR]
CN	Customer Number	Number of the Customer	Text	[DE]
Cat	Category	Category of the Customer	Text	[DE]
FR_SIR	SIRET	For B2B invoices see NF525	Text	[FR]
FR_SRN	SIREN	For B2B invoices see NF525	Text	[FR]
FR_NAF	NAF/APE	For B2B invoices see NF525	Text	[FR]
IT_CodiceLotteria	Lottery Code	Customers lottery code	Text	[IT]

POS Elements

Attribute	Name	Description	Datatype	Mandatory
	Position	Position element
PTY	Position Type	If not "Pos", e.g. "Mod" accepted methods to set: <PosA><Mod … <PosA><Pos PTY="Mod" … "PosA":\["\_":"Mod",… "PosA":\["PTY":"Mod",... Examples: "Mod", "Dep", "Vou", "Adv", "Tip", "FoC"	Text
PN	Position Number	Modifier positions PTY="Mod" may refer to multiple positions, e.g. PN="\*" Examples: PN="1", PN="\*"	Text	Recommended
IN	Item Number	Public article number (GTIN, EAN, UPC)	Text	[FR] invoice (Others: Recommended)
ID	Item Identity	Serial or batch number	Text
SKU	Stock Keeping Unit	Article number
Dsc	Description	Usual denomination of goods or services	Text	MANDATORY
TaxG	Tax Group	Tax group Usually tax groups are identified by letters or numerals. If an article besides VAT tax group is attributed other tax groups, these can be noted as an array (delimiter: space) Examples: "B", "B N"	Text[]	MANDATORY
Amt	Position Amount	Position amount (Qty*Pri) Example: "199.00"	Currency	MANDATORY
Qty	Quantity	Quantity Qty="1" may be omitted if QtyU="pc" or lump sums default value used: Math.sign(parseFloat(Amt))	Decimal	MANDATORY
QtyU	Quantity Unit	Quantity Unit QtyU="pc" ("piece") may be omitted.	Text
Pri	Unit Price	Price per Unit may be omitted if Qty="1" or Qty="-1" and QtyU="pc"	Currency
Note	Position Note	Individual position text Replaces deprecated field Pos.Info	Text
Void	Position Void	Void of position within same receipt	Boolean 0/1	Recommended
RFN	Reference Fiscal Number	Needed in some countries in case of return or void as reference to original sale	Text	[IT] [SK]
VouN	Voucher Number	Unique number of voucher	Text
Dev	Device	ID of the capture device	Text	[DE]
InH	inhouse	Inhouse consumption flag	Boolean 0/1	[DE]
DE_AGENTUR_ID	Agency ID	ID of the agency Example: "123"	Integer	[DE]
Cat	Category ID	ID of the Category	Text	[BE] [DE]
CatN	Category name	Name / description of the Category	Text	[BE] [DE]
RD*	Reference Date Time	Reference to the original transaction If the whole transaction is voided, specify reference fields directly in ESR object.
RTL*	Reference Transaction Location	Reference to the original transaction If the whole transaction is voided, specify reference fields directly in ESR object.
RTT*	Reference Transaction Terminal	Reference to the original transaction If the whole transaction is voided, specify reference fields directly in ESR object.
RTN*	Reference Transaction Number	Reference to the original transaction If the whole transaction is voided, specify reference fields directly in ESR object.
RPN*	Reference Position Number	Reference to the original transaction If the whole transaction is voided, specify reference fields directly in ESR object.
Rsn	Reason	Return reason for SAF-T export	Text	[PT]
PT_TaxExemptionCode	Exemption Code	If not specified in field TaxG, alternatively this field can be used Example: "M11"	Text M01-M99	[PT]
PT_TaxExemptionReason	Exemption Reason	For printing and SAF-T override tax table exemption description as in [PT] country guide Example: "Regime particular do tabaco"	Text	[PT]
SK_SellerIdType	Seller ID Type	Type of the Seller ID. Allowed Values: NONE IC_DPH DIC	Text	[SK]
SK_SellerId	Seller ID		Text	[SK]
SK_SpecialRegulation	Special Regulation	A flag that specifies which "reason" tax allocation of 0, if the item is assigned	Text	[SK]
SK_InvoiceNumber	Invoice Number		Text	[SK]

Mod Elements

Attribute	Name	Description	Datatype	Mandatory
	Modifier	Discount/Uplift on position(s)
PN	Position Number	Reference to Pos.PN Default: previous position (position discount) "*": all positions (discount on subtotal/total) Multiple position numbers may referred as range (from-to) or space delimited array Examples: "1", "1-3", "", "1 2 7"*	Text
Dsc	Description	Description to be printed	Text	[DE]
Prc	Percent	Rebate percentage for printing Example: "10", "10%"	Text
Cat	Category	Discount code To be used in reports Example: "DISC002"	Text	[BE]
Amt	Modifier Amount	Amount Negative: rebate or discount Positive: markup Example: "-50.00"	Currency	MANDATORY

Lin Elements

Attribute	Name	Description	Datatype
	Print Line	Print line
PN	Position Number	The print line may be attributed to a position. Usually the print line is attributed to the last position or payment line. Example: "1"	Integer
Dsc	Description	Text in description column	Text
LAmt	Line Amount	Text in amount column, can show subtotal amount	Text

Pay Elements

Attribute	Name	Description	Datatype	Mandatory
	Payment	Payment line
Dsc	Description	Denomination of payment method Example: "Cash"	Text	[DE]
Amt	Payment Amount	Amount paid Example: "735.00"	Currency	MANDATORY
UID	Unique Identifier	Unique payment identifier Electronic payment or document reference	Text
PayG	Payment Group	Method/category of payment as required in some countries - details see country EFR Guide For convenience use ESR standard codes (See Payment Groups)	Text	[DE] [HR] [PT]
CC	Foreign Currency Code	Foreign currency code ISO 4217 (3 characters) Example: "CHF"	Text
FAmt	Foreign Amount	Amount of the foreign payment Example: "100.00"	Currency

Tax Elements

Attribute	Name	Description	Datatype	Mandatory
	Tax Line	Tax element
TaxG	Tax Group	Tax group Example: "A"	Text	MANDATORY
Prc	Tax Percent	Tax percentage Examples: "21", "0"	Decimal	MANDATORY
Net	Excluding Tax	Net (excl. Tax) Example: "165.29"	Currency
TAmt	Tax Amount	Tax amount Example: "34.71"	Currency
Amt	Including Tax	Gross amount (incl. Tax) Example: "200.00"	Currency	MANDATORY

Other Elements

Element	Name	Description	Datatype	Mandatory
Head	Header	Running text head
Txt	Text	Text block	Text
PosA	Position Array	Array of position lines		MANDATORY (except [AT] [CZ] [HR])
PayA	Payment Array	Array payment elements		MANDATORY (except [AT] [CZ] [FR])
TaxA	Tax Array	Array tax elements Auto-generated if ESR.PosA is available		MANDATORY (except [IT] [PL] [SK])
Foot	Footer	Running text footer
Txt	Text	Text block	Text

*Reference attributes only for void/reversal or return-of-good positions (usually in combination with negative Qty)

info

Country specific fiscal regulations may require addtional fields to be delivered. Refer to country specific documentation for details.

Response TraC (Tra Completion)

Response for a fiscal sale transaction:

Element	Name	Description	Datatype	Countries	Example
TraC ([DE]: TraSC / TraUC / TraVC)	Transaction Completion	Response to a Tra-command
SQ (attribute)	Sequence Number	SQ is incremented on each successful registration	Integer		1
Result	Registration Result	Result of a registration
RC (attribute)	Result Code	Code for program control OK: registered NO: not registered (fixable) BAD: not registered (termination)	OK, BAD, NO		"OK"
ErrorCode	Error Code	Error Code according to list of error constants. In combination with RC="OK" this is to be understood as a warning (e.g. "#DUPLICATE" when restarting a registration)	Text		"#OFFLINE"
UserMessage	User Message	Information for the operator (local language) Must be displayed by the foreground application if present!	Text		"Systémem EET offline"
Warning	Debug Message	Error Debug information (english)	Text[]
Fis	Fiscal Data	Fiscal Signature
D	Date Time	Date and time of fiscal device	DateTime	[IT] [PL] [SK]
FN	Fiscal Number	Fiscal number created by fiscal device	Text	[IT] [PL] [SK]
DN	Document Number	Receipt number created by fiscal device	Integer	[IT] [SK]
ZI	Z-Index	Index of current Z-report of fiscal device	Integer	[IT] [PL]
ID	Device Serial	Serial number of fiscal device	Text	[IT] [PL]
OKP	Verification Code		Text	[SK]
Type	Transaction Type	Type of the transaction	Text	[DE]
TID	Transaction ID	ID of a transaction coming from TSE	Integer	[DE]
Code	QR Code Data	Data for a possible QR code	Text	[AT] [DE]
Link	Link	efsta link for printing instead of QR code	Text	[AT]
Payload		Signature Payload	Text	[FR]
Signature		Signature	Text	[FR]
Tag	Fiscal Tag	Fiscal text To be printed on the sales slip according to fiscal regulation
Name	Field Name	Field name for computation in the foreground application (for optional saving by the cashier application)	Text		"Sign"
Value	Field Value	Field Value	Text		"987a6be5-6af5-44f3-b4fc-987654321000-03"
Label	Field Label	Denomination of the Field on the print-out (in local language, may be empty)	Text		"FIK"
Z	Z Data	End of day data of fiscal device		[IT] [PL]
T	Z Total	End of day total	Currency	[IT] [PL]
CAmt	Credit Amount	End of day return / void amount	Currency	[IT]
LastD	Date Time	Time of last Z-report	DateTime	[IT]
LastSQ	Last Sequence Number	Sequence number of last Z-report	Integer	[IT]
ZTax	Z Tax Data	End of Day Tax Data of fiscal device		[IT] [PL]
TaxG	Tax Group	Tax Group	Text	[IT] [PL]
TaxI	Tax Index	Tax Index of fiscal device	Integer	[IT] [PL]
Prc	Percent	Percentage of tax group / tax index	Decimal	[IT] [PL]
TAmt	Tax Amount	Tax Amount	Currency	[IT] [PL]
Amt	Amount	Total amount of tax group / tax index	Currency	[IT] [PL]

note

Main program flow is controlled by ResultCode RC.

<ErrorCode> may contain additional information

<Warning> elements provide debugging information for interface developers respectively cashier support. These serve for informational purposes only, success of registration of a transaction is expressed within ResultCode RC only.

Payment Groups - Pay.PayG

In many countries the type of payment has to be specified per payment line for the fiscal printer or subsequent export. You may always use the national coding rules as given in the EFR Country Guide documentation, but you can also use the following efsta constants for all countries, which then are translated accordingly:

efsta PayG	+\-	Description	Examples, local naming
cash	+	Payment in local currency (coins, notes)	Bar
change	-	Change money in case of overpayment, usually negative e.g. total € 9.00: cash € 10.00, change € -1.00	Rückgeld
refund	-	Money paid back on return of goods, usually negative
atm	+	Cash withdrawal
foreign	+	Foreign currency, Pay.Amt is local currency, also specify - currency code Pay.CC and - foreign currency amount Pay.FAmt	CHF
debitcard	+	Electronic bank card payment, also specify - unique transfer ID Pay.UID	EFT, EC, Giro, Maestro, ATM card
mobile	+	Mobile phone app
creditcard	+	Electronic credit card payment, also specify - unique transfer ID Pay.UID	Visa, Master, American, Diners, JCB
open		Open item, e.g. commercial invoice/bill	Pos.OpI
creditnote		Issue or redemption of a credit note
voucher	+	Redemption of a multi purpose voucher	gift card or cheque
loyalty	+	Fidelity points	coupon
title	+	Compensation title (digital or paper), e.g. meal voucher	Sodexo
check	+	Bank check	check
rounding		Automatic rounding applied for cash payment

+ = payment
- = return

Tax Group Assignment - TaxG

Depending on the capabilities of the sender program there are different methods specifying tax groups within the ESR structure.

1. Set field PosA/Pos/@TaxG according to the tax group definition in the country EFR Guide (e.g. "A" to "E"), omit TaxA array; for each position the predefined tax rate is taken, the TaxA/Tax elements are computed automatically, values TaxA/Tax/@Amt are added to the fiscal turnover.
   

   ESR Example:

   <PosA>  
       <Pos … TaxG="A"/>  
   </PosA>

2. Load tax rate in PosA/Pos/TaxG, e.g. TaxG="20%", omit TaxA; array TaxA is computed automatically, Tax Group is matched over tax rate percentage. With this method a percentage mismatch may occur in fiscal countries requiring exact tax group reference (e.g. [AT]), because for example PosA/Pos/@TaxG="21%" is not referring to predefined "20%".
   

   ESR Example:

   <PosA>  
       <Pos … TaxG="20%"/>  
   </PosA>

3. Set position PosA/Pos/@TaxG according to TaxA/Tax/@TaxG, specify tax rate in TaxA/Tax/@Prc; In this case the field value in TaxG serves only as link between both elements, so the naming can be selected freely. In fiscal countries with exact tax group reference (e.g. [AT]) the matching is done upon TaxA/Tax/@Prc. The fiscal turnover is determined by TaxA/Tax/@Amt.
   

   ESR Example:

   <PosA>  
       <Pos … Amt="123.45" TaxG="XY"/>  
   </PosA>  
   <TaxA>  
       <Tax TaxG="XY" Prc="20" Amt="123.45" …/>  
   </TaxA>

Automatic Value Assignment D and TN

If not provided by the cash register application, Date D (system time) and receipt number TN (serial number, on change of year beginning with 1) are generated automatically by the EFR and returned within the response.

Request:

<Tra>
  <ESR T="1.49">
    <PosA>
      <Pos PN="1" IN="4012345678901" Dsc="Hesp.-Essig" TaxG="B" Amt="1.99"/>
      <Mod PN="1" Dsc="Aktionsnachlass" Amt="-0.50"/>
    </PosA>
    <TaxA>
      <Tax TaxG="B" Prc="10" Net="1.35" TAmt="0.14" Amt="1.49"/>
    </TaxA>
  </ESR>
</Tra>

Response

<TraC SQ="1234">
  <Result RC="OK"/>
  <ESR D="2016-03-01T14:46:43" TN="39"/>
...

ESR Validation Rules

• Total of position elements PosA/\*/@Amt equals transaction total ESR/@T
• Total of payment elements PayA/\*/@Amt equals transaction total
• Total of tax elements TaxA/\*/@Amt (including tax) equals transaction total
• For each tax element TaxA/Tax: @Net + @TAmt = @Amt
• Amount in PosA/Lin/@LAmt is used for transaction display only (e.g. subtotal), not regarded in any computation
• In position elements PosA/\* fields quantity PosA/\*/@Qty and price per piece PosA/\*/@Pri may be skipped in case of PosA/\*/@Qty=1
• Assign position modifiers PosA/Mod (discount, rebate, addition) to their relevant position(s) PosA/\*/@PN using @PN, internally aliquot modification
• Position elements PosA/\*/@Amt per tax group PosA/\*/@TaxG modified by PosA/Mod/@Amt assigned equal tax element amount TaxA/Tax/@Amt per tax group TaxA/Tax/@TaxG

Numbering of Documents

Bookkeeping systems always require an ascending number for each document issued (e.g. receipt / ticket / invoice), being unique at least within the year of creation.

Transaction Number TN

Usually, the POS system identifies fiscal and nonfiscal transactions with a Transaction Number TN assigned incrementally (e.g. per year or within a recurring number range of 00001-99999). Assuming that the company is using more than one cash register, transaction numbers are emitted per POS (Transaction Terminal TT), if multiple business premises (stores, locations) are driven also per Transaction Location TL.

The full unique document identifier is then TL/TT/TN, e.g. "001/1/1234".

If TN is omitted in the "Tra" request, EFR automatically assigns a number incrementally.

Fiscal Number FN

Fiscal Number FN is allocated for each fiscal (=sales) transaction according to country specific fiscal rules, the format of the field varies. It has to be printed on the document and stored on POS side with each transaction.

Good to know

In some countries, TL/TT/TN is used as unique transaction identifier, no separate FN exists (e.g. in [AT]).

Reference to a Document

The number assigned to a transaction is relevant on return of goods or void transactions. Here, the original transaction has to be referred to by specifying RTL/RTT/RTN or RFN to avoid double return or void.

Internal SQ

SQ is a SeQuel number used internally by EFR and efsta cloud for synchronization. A strictly ascending number is assigned to each data record in journal files .../\*.jou. One journal file contains 1000 records and is named after the number range it contains (SQ 1000-1999; e.g. "0001.jou"). SQ is independent of TN and FN, and as it is for internal use only, there is no need to print it or store it at POS side.

Directory Structure /EFR

By default EFR data is kept in the following directories:

Windows

C:\\ProgramData\\EFR

Linux

/home/efr

note

A different path can be choosen on EFR program startup:
C:\\ProgramData\\EFR> node app/app –RootPath D:/EFR

Good to know

Directories are created on demand.

Directory	Content
/app	Application folder
/cer	Certificate storage: Certificates of smart cards, Company public key (for encryption)
/gbl	Global configuration: profile.cfg, regmain.xml
/log	Process logging
/rn	Main directory for clients
/rn/def	Register Number RN def (default)
/rn/def/cfg	RN configuration
/rn/def/dat	RN totals
/rn/def/jou	Journal storage ('Transaction Journal', [AT] 'Datenerfassungsprotokoll')
/rn/def/log	Transaction logging in case of error
/rn/def/retry	[CZ, HR, SI] optional directory for offline transactions waiting for retry
/req	Optional request directory for File Interface - FileWatch (p. )
/res	Optional response directory

Storage Management

Actions on Software Installation / Uninstall

On installation the basic directory structure is created on default RootPath, subdirectories are created when required. If EFR is uninstalled the software is removed, but data folders are kept! Legal relevant data may not be discarded automatically, please delete manually after having assured its backup.

Storage Transaction Capacity

By default an EFR is allowed to keep 1000 MB of data on disk, this value can be modified setting parameter DiskQuota in /profile. Space consumption is checked once per hour and in case of overrun old .log files are deleted, transaction journal files .jou are gzipped to .jou.gz, old .jou.gz are deleted. Files modified within the last 3 months are always kept. Therefore the EFR should run online with cloud backup or in offline mode a periodic backup using /backup request or via file system has to be established. The number of transactions which can be kept locally mainly depends on the configuration of the DiskQuota and the average length of one transaction. Here's a short calculation using typical values:

DiskQuota: 1000 MB
Application space: approx. 100 MB
Remainder for transaction data: 900 MB
Mean transaction length: assumed 2 KB
Capacity: 450000 transactions

Good to know

Transaction journal files (.jou) are zipped automatically (to .jou.gz) as soon as the threshold of 80% DiskQuota is reached. Capacity with compressed files: 2000000 transactions

EFR Versioning

EFR is intended to be under permanent development as a result of adapting to national regulations and implementation of new countries and functions. Development is performed in an agile, common multi country environment, resulting in new minor versions per sprint, typically every 1-2 months. In the meantime, "hotfixes" may be released to respond to urgent demands.

Version Numbering Scheme:

EFR v2.3.4.5
Means platform: 2, major: 3, minor: 4, hotfix: 5

Part_	e.g.	Description
platform	2	Denotes the nodejs platform version and basic runtime environment, it usually does not affect program functionality. From REST client perspective v1.13.4.5 == v2.3.4.5. Following platforms exist: 1 … node v4.4.4, source in minified .js 2 … node v10.15.3, launch with boot.node, source in EFR.zip 3 … node v12.19.0, launch with boot.js, compiled source in EFR.zip
major	3	A new major version shows a possible change in the program API. Although most widely compatibility in interfaces is aimed, new functions or legal requirements may cause minor changes. Refer to changelog for details, and testing on software partner side is strongly recommended!
minor	4	A new sprint will contain bugfixes and new (country) functionality No general testing required.
hotfix (optional)	5	Like a minor version a hotfix contains bugfixes and new (country) functionality It is released on demand for one or more countries
appendix (optional)	B	Used for beta versions, which always are provided for a specific customer only

info

Release of platform 3 is planned for 2025

Because all country versions of EFR use common base modules, EFR version numbering is performed independently of country modules. Since new versions may not be of interest for all countries, on the download page public.efsta.net the different latest versions are listed for each country individually.

A complete history of relevant changes to the program can be found in file CHANGELOG.md in EFR.zip (or can be downloaded from http://localhost:5618/changelog ).