EFR API

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.

This collection of EFR API requests are all the API requests needed to send transaction data, add/edit company data, or administer the EFR. REGISTER and CFG are mandatory to use the EFR. In fiscal printer countries, PERI is required to directly print and request printer related data required for these countries. All other API requests can be used as additional functionality for your system. The recommanded workflow can be found at Communication Workflow.

If you have any comments or questions to this document please contact us at: ticket@efsta.eu

Important

If the EFR is used for multiple companies (see EFR Architecture) the ESR.TaxId must be sent in all /register requests.

If the EFR is used for muliple POS systems the query parameter "rn" must be sent for all request (except /register). The rn consists of TaxId$TL_TT
e.g.: GET localhost:5618/cfg?rn=DE123456789$1_1

Register

This route is used to register transactions (e.g. sales, invoices, payment transactions,...) to the EFR journal. The Format for all business cases can be found at Business Cases.

POST /register

Body

Content-Type: text/xml or application/json

note

The strucure of the ESR format can be found at ESR format and the values for the payment group are descript at Payment groups.

First Sample Transaction

XML
JSON

<Tra>
    <ESR D="2024-06-01T08:30:15" TL="001" TT="1" TN="1" T="8.38">
        <PosA>
            <Pos PN="1" IN="1001" Dsc="Example Item" TaxG="A" Amt="3.98" />
            <Pos PN="2" IN="1020" Dsc="Example Item" TaxG="B" Amt="1.50" />
            <Pos PN="3" IN="1030" Dsc="Example Item" TaxG="A" Amt="2.90" />
        </PosA>
        <PayA>
            <Pay Dsc="Example Payment" PayG="cash" Amt="10.00" />
            <Pay Dsc="Example Change" PayG="change" Amt="-1.62" />
        </PayA>
        <TaxA>
            <Tax TaxG="A" Prc="19" Net="5.78" TAmt="1.10" Amt="6.88"/>
            <Tax TaxG="B" Prc="7" Net="1.40" TAmt="0.10" Amt="1.50"/>
        </TaxA>
    </ESR>
</Tra>

{
    "Tra":{
        "ESR":{ "D":"2024-06-01T08:30:15", "TL":"001", "TT":"1", "TN":"1", "T":"8.38",
            "PosA":[
                {"_":"Pos","PN":"1", "IN":"1001", "Dsc":"Example Item", "TaxG":"A", "Amt":"3.98"},
                {"_":"Pos","PN":"2", "IN":"1020", "Dsc":"Example Item", "TaxG":"B", "Amt":"1.50"},
                {"_":"Pos","PN":"3", "IN":"1030", "Dsc":"Example Item", "TaxG":"A", "Amt":"2.90"}
            ],
            "PayA":[
                {"_":"Pay", "Dsc":"Example Payment", "PayG":"cash", "Amt":"10.00"},
                {"_":"Pay", "Dsc":"Example Change", "PayG":"change", "Amt":"-1.62"}
            ],
            "TaxA":[
                {"_":"Tax", "TaxG":"A", "Prc":"19", "Net":"5.78", "TAmt":"1.10", "Amt":"6.88"},
                {"_":"Tax", "TaxG":"B", "Prc":"7", "Net":"1.40", "TAmt":"0.10", "Amt":"1.50"}
            ]
        }
    }
}

Response Example

The structure of the EFR response can be found at Response TraC

XML
JSON

<TraC SQ="1537030">
	<Result RC="OK"/>
	<ESR D="2024-08-01T10:50:30" FN="001/1/1"/>
	<Fis TID="3">
		<Code>V0;001/1;Kassenbeleg-V1;Beleg^6.88_1.50_0.00_0.00_0.00^8.38:Bar;3;7;2024-08-01T08:50:30.000Z;...</Code>
		<Tag Label="TrNr:" Value="3" Name="TID"/>
		<Tag Label="Beg.:" Value="2024-08-01 10:50:30" Name="StartD"/>
		<Tag Label="Ende:" Value="2024-08-01 10:50:30" Name="FinishD"/>
		<Tag Label="TSE :" Value="0123456789abcdef0..." Name="Serial"/>
		<Tag Label="SigZ:" Value="7" Name="SignCnt"/>
		<Tag Label="Sign:" Value="aT775OTya1SXEGceVO2raDlRHv..." Name="Sign"/>
	</Fis>
</TraC>

{
  "TraC": {
    "SQ": "1537030",
    "Result": { "RC": "OK" },
    "ESR": { "D": "2024-08-01T10:50:30", "FN": "001/1/1" },
    "Fis": {
      "TID": "3",
      "Code": "V0;001/1;Kassenbeleg-V1;Beleg^6.88_1.50_0.00_0.00_0.00^8.38:Bar;3;7;2024-08-01T08:50:30.000Z;..."
      "Tag": [
        { "Label": "TrNr:", "Value": "3", "Name": "TID" },
        { "Label": "Beg.:", "Value": "2024-08-01 10:50:30", "Name": "StartD" },
        { "Label": "Ende:", "Value": "2024-08-01 10:50:30", "Name": "FinishD" },
        { "Label": "TSE :", "Value": "0123456789abcdef0...", "Name": "Serial" },
        { "Label": "SigZ:", "Value": "7", "Name": "SignCnt" },
        { "Label": "Sign:", "Value": "aT775OTya1SXEGceVO2raDlRHv...", "Name": "Sign" }
      ]
    }
  }
}

Important

If the EFR return the value of Fis.Code, it must be printed on the receipt as QR-code / barcode. If the EFR return Fis.Tag elements, all elements must be printed on the receipt (Label + Value).

Cfg - Base data/company header data

Before sending the first transaction the company header sales data should be configured. This can be done manually, via request or certralized via efsta portal.

Good to know

For centralized administration configuration data can be set using the efsta portal, data is replicated to the EFR instances. If the central configuration is used, neither manual configuration nor programmatic configuration is necessary.

Manual configuration

Navigate to http://localhost:5618 in your browser and open “Basisdata” (base data). Enter the field values required, data is replicated to EFSTA cloud.

Programmatic configuration

This request should be issued once on startup of the frontend application to update receipt header fields like company name or location address. If values are unchanged, the request is without effect. It is mandatory to set this data before registering the first transaction. The strucure of the ESR format can be found at Cfg - Configuration

Get cfg data:

GET /cfg

Set cfg data:

POST /cfg

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

Body

JSON
XML

{
    "Cfg": {
        "Cmp": {
            "Nam": "My Company",
            "label": "MyComp",
            "Adr": "Street",
            "AdrNr": "3",
            "Zip": "1000",
            "City": "City",
            "Ctry": "XY",
            "TaxId": "XY99999999999",
            "TIN": "123456789",
            "Org": "",
            "VATonPayment": 0,    
            "FR_NAF": "47.11D",
            "FR_SRN": "732 829 32",
            "FR_RCS": "PARIS A",
            "FR_TYPE": "XXX",
            "FR_CAPITAL": "XXX",
            "FR_METIER": "XXX"
        },
        "Loc": {
            "TL": "001",
            "Nam": "My Location",
            "label": "MyLoc",
            "Adr": "123 Long Road",
            "Zip": "12345",
            "City": "Metropolis",
            "State": "XXX",
            "Ctry": "XY",
            "TaxId": "XY99999999999",
            "FR_SIR": "732 829 320 0007"
        },
        "Trm": {
            "TT": "1",
            "SW": "super-POS",
            "SWVersion": "3.4.5",
            "HW": "POS Brand",
            "HWModel": "POS model name",
            "Serial": "POS serial number"
        },
        "Dev": [
            {
                "Id": "1",
                "HW": "Dev Brand",
                "HWModel": "Dev Model",
                "SW": "My Dev Software",
                "SWVersion": "1.5.7",
                "Serial": "POS serial number"
            },
            {
                "Id": "2",
                "HW": "Dev Brand",
                "HWModel": "Dev Model",
                "SW": "My Dev Software",
                "SWVersion": "1.5.7",
                "Serial": "POS serial number 2"
            }
        ], 
        "DE_Agentur": [
            {
                "Id": "1",
                "Nam": "Test Company",
                "Adr": "177 Long Road",
                "Zip": "12345",
                "City": "Metropolis",
                "Ctry": "XY",
                "TaxId": "XY99999999999"
            },
            {
                "Id": "2",
                "Nam": "Test Company 2",
                "Adr": "256 Long Road",
                "Zip": "12345",
                "City": "Metropolis",
                "Ctry": "XY",
                "TaxId": "XY99999999998"
            }
        ],
        "Doc": {
            "ContactName": "John Doe",
            "ContactTelephone": "123456789",
            "ContactElectronicMail": "j.doe@efsta.eu",
            "PaymentTerms": "30 days net",
            "PaymentPeriod": 30,
            "AccountName": "my company",
            "AccountIBAN": "AT00000000000000000000",
            "AccountBIC": "ASPAKAT2LXXX"
        }
    }
}

<Cfg>
    <Cmp Nam="My Company" label="MyComp" Adr="Street 3" Zip="1000" City="City" Ctry="XY" TaxId="XY99999999999" DE_STNR="" FR_NAF="47.11D" FR_SRN="732 829 32" FR_RCS="PARIS A" FR_TYPE="XXX" FR_CAPITAL="XXX" FR_METIER="XXX" />
    <Loc TL="001" Nam="My Location" label="MyLoc" Adr="123 Long Road" Zip="12345" City="Metropolis" State="XXX" Ctry="XY" Org="" ApplicationID="" TaxId="XY99999999999" FR_SIR="732 829 320 0007" />
    <Trm TT="1" SW="super-POS" SWVersion="3.4.5" HW="POS Brand" HWModel="POS model name" Serial="POS serial number" />
    <Dev>
        <Dev Id="1" HW="Dev Brand" HWModel="Dev Model" SW="My Dev Software" SWVersion="1.5.7" Serial="POS serial number" />
        <Dev Id="2" HW="Dev Brand" HWModel="Dev Model" SW="My Dev Software" SWVersion="1.5.7" Serial="POS serial number 2" />
    </Dev>
    <DE_Agentur>
        <Agentur Id="1" Nam="Test Company" Adr="177 Long Road" Zip="12345" City="Metropolis" Ctry="XY" TaxId="XY99999999999" />
        <Agentur Id="2" Nam="Test Company 2" Adr="256 Long Road" Zip="12345" City="Metropolis" Ctry="XY" TaxId="XY99999999998" />
    </DE_Agentur>
    <Doc ContactName="John Doe" ContactTelephone="123456789" ContactElectronicMail="j.doe@efsta.eu" PaymentTerms="30 days net" PaymentPeriod="30" AccountName="my company" AccountIBAN="AT00000000000000000000" AccountBIC="ASPAKAT2LXXX"/>
</Cfg>

Good to know

Cfg field values also are used for bill.efsta.net Digital Receipt display, the "label" fields should contain abbreviations (10 char max.) to be used as denomination in lists.

EFR State

Get state information about running EFR installation.

GET /state

Request Header

Name	Value
Accept	`application/json` or `text/xml`

Response

JSON
XML

{
    "pid": 32756,
    "arch": "x64",
    "uptime": 12563,
    "name": "EFR",
    "version": "2.5.0",
    "manifest": "...",
    "Country": "XY",
    "Online": true,
    "Recorder": "online",
    "RN": "def",
    "RecSent": 0,
    "RecQueued": 0,
    "RetryQueued": 0,
    "TimeOffset": 0,
    "D": "2024-06-28T09:54:26+02:00",
    "DiskUsage": 0.038301,
    "DiskQuota": 1000,
    "Company": "XY123456789"
}

<State>
    <pid>32756</pid>
    <arch>x64</arch>
    <uptime>12563</uptime>
    <name>EFR</name>
    <version>2.5.0</version>
    <Country>XY</Country>
    <Online>true</Online>
    <Recorder>online</Recorder>
    <Badge>XY123456789</Badge>
    <EFR>0000000XXXX</EFR>
    <RN>def</RN>
    <RecSent>0</RecSent>
    <RecQueued>0</RecQueued>
    <RetryQueued>0</RetryQueued>
    <TimeOffset>0</TimeOffset>
    <D>2024-06-28T09:54:26+02:00</D>
    <DiskUsage>0.038301</DiskUsage>
    <DiskQuota>1000</DiskQuota>
    <Company>XY123456789</Company>
</State>

Name	Value	Example
pid	Process Id	`32756`

Export

_{From EFR V2.5}

GET /export

Query & Type

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`
type	Export type	`dsfinvk`
from	From date `YYYY-MM-DD`	`2024-01-15`
till	Till date `YYYY-MM-DD`	`2024-12-31`
target	Optional. Target folder-path to save export file to.	`C:/exports`
open	Optional. Include data of the currently not closed day. Only available for type `dsfinvk`	`on`

Type

Type	Description	Response	Countries
`jou`	EFR journal export	File `jou*.zip`	*
`dep`	Datenerfassungsprotokoll	File `dep-export.zip`	AT
`tse`	TSE export	File `export.tar`	DE
`gobd`	GoBD export	File `gobd.zip`	DE
`dsfinvk`	DSFinV-K export	File `export.zip`	DE
`saft`	SAF-T export	File `export.zip`	DK, NO, PT, SE
`nf525-export`	NF525 export to verify signature chain	File `export.xml`	FR
`nf525-total`	NF525 export to verify grand totals	File `total.xml`	FR
`nf525-jet`	NF525 Journal des Évènements Techniques	File `audit.csv`	FR
`nf525-jou`	EFR journal export including proof-script	File `jou.zip`	FR

Profile

This request can be used to set the Badge field in the EFR profile to connect the instance to the efsta Cloud. You can get the Badge value of your company by opening the company details in the efsta portal.

Query & Body

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

Body

JSON
XML

{
    "Badge": "XXX" ,
    "TaxId": "XXX"
}

<profile>
    <Badge>XXX</Badge>
    <TaxId>XXX</TaxId>
</profile>

Tax IDs for testing

In the following table are Tax IDs for testing for each country

Flag	Country	Test Tax Id
	Austria	ATU57780814
	Belgium	BE123456789
	Czech	CZ123456789
	Germany	DE123456789
	Denmark	DK99999993
	Spain	ES123456789
	France	FR123456789
	Croatia	HR123456789
	Hungary	HU123456789
	Italy	IT123456789
	Lithuania	LT123456789
	Norway	NO999999999
	Poland	PL9999999999
	Portugal	PT999999990
	Sweden	SE123456789
	Slovenia	SI123456789
	Slovakia	SK123456789

Journal

Find

This request can be used to find and retrieve transaction data of the EFR journal.

GET /find

Query & Request Header

Query Parameter

Name	Value	Example
rn	Optional Register Number, default: `def`. Alternatively, TaxId (optional), TL and TT can be specified as parameter	`1_1`
from	From date (optional)	`2024-11-06`
till	Till date (optional)	`2024-11-06`
limit	Optional limitation of volume and runtime in the format `XrowsYms` with: X = receipt count Y = max runtime in ms default: `1000rows5000ms`	`10rows10000ms`
sort	Sort order, default: `desc`	`asc`
continuation	Continuation string (optional)	`51856974`

Additional query parameters can be added for transaction search criteria.

Name	Value	Example
fn	Fiscal number (can be used instead of tl/tt/tn)	`001/1/10`
tn	Transaction number	`5`
d	Date	`2024-11-05`
sq	Sequence number	`10`
_	Record Type. Tra...Transaction, TraS...Start Transaction, Rep... Reports, Cfg... Configuration, log... Logs, etc.	`Tra`
t	Total	`8.38`
nfs	Non fiscal transactions (see Business Cases)	`Z`

Good to know

You can search for all properties that are in the ESR object (see journal files).

Request Header

Name	Value
Accept	`application/json` or `text/xml`

Get Last Transaction

Fetches the last data object registered (POST /register). To be used on system restart or for informational purposes.

GET /last

Query, Request Header & Response

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`
_	optional rec type filter	`Tra`, `TraS`, `Cfg`

Request Header

Name	Value
Accept	`application/json` or `text/xml`

Response

XML or JSON transaction data, utf-8

Render

Use to show last transaction on a (customer) display, or to fetch a formatted PDF file for saving/printing. Formatting in both cases is using fiscal.pug, which can be customized for the intended purpose.

Request	Response
`GET /render`	HTML rendering of the receipt
`GET /render/pdf`	PDF rendering of the receipt
`GET /render/text`	Plain text rendering of the receipt
`GET /render/escpos`	ESC/POS commands line by line for use with a receipt printer

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`
FN	Optional fiscal number, default: last receipt	`4711`

Peri

Available when a fiscal printer is connected to the EFR.

Direct Printing

Prints text directly on the connected printer without registering any transaction to the EFR journal.

POST /peri/print

Query & Body

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

Body

Content-Type: text/plain

sdfjk
dsjfkls
dsjfkl

Printer State

Get information about the printer and/or fiscal module.

GET /peri/print/state

Query, Request Header & Response

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

Request Header

Name	Value
Accept	`application/json` or `text/xml`

Response

JSON
XML

{
    "ModuleName": "[printer module name]",
    "ID": "[printer serial]",
    "ZI": 1,
    "SimpleState": {
        "DayOpen": true,
        "ZRequired": false,
        "NextZRequired": "2024-10-05T00:00:00",
        "DrawerOpen": false,
        "PaperNearEnd": false,
        "PaperEnd": false,
        "CoverOpen": false,
        "MemAlmostFull": false,
        "MemFull": false,
        "CertExpires": "2028-10-05T00:00:00"
    }
}

<PrintState>
    <ModuleName>[printer module name]</ModuleName>
    <ID>[printer serial]</ID>
    <ZI>1</ZI>
    <SimpleState>
        <DayOpen>true</DayOpen>
        <ZRequired>false</ZRequired>
        <NextZRequired>2024-10-05T00:00:00</NextZRequired>
        <DrawerOpen>false</DrawerOpen>
        <PaperNearEnd>false</PaperNearEnd>
        <PaperEnd>false</PaperEnd>
        <CoverOpen>false</CoverOpen>
        <MemAlmostFull>false</MemAlmostFull>
        <MemFull>false</MemFull>
        <CertExpires>2028-10-05T00:00:00</CertExpires>
    </SimpleState>
</PrintState>

Name	Value	Example
ModuleName	Printer module name	`"Epson_FP"`
ID	Printer serial number	`"99MEY022311"`
ZI	Current Z-Index	`1`
SimpleState.DayOpen	Nullable boolean, `null` if printer does not provide it
SimpleState.ZRequired	Nullable boolean, `null` if printer does not provide it
SimpleState.NextZRequired	Nullable string, `null` if printer does not provide it	`2024-10-05T00:00:00`
SimpleState.DrawerOpen	Nullable boolean, `null` if printer does not provide it
SimpleState.PaperNearEnd	Nullable boolean, `null` if printer does not provide it
SimpleState.PaperEnd	Nullable boolean, `null` if printer does not provide it
SimpleState.CoverOpen	Nullable boolean, `null` if printer does not provide it
SimpleState.MemAlmostFull	Nullable boolean, `null` if printer does not provide it
SimpleState.MemFull	Nullable boolean, `null` if printer does not provide it
SimpleState.CertExpires	Nullable string, `null` if printer does not provide it	`"2028-10-05T00:00:00"`

Line Display

Displays text directly on the connected line display of the printer. During position and payment entry the cash register application should send referring description and price/amount information immediately to the customer display.

POST /peri/display

Query & Body

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

Body

Content-Type: text/plain

Arrotondato 30,00 €
Totale      30,01 €

Open Drawer

Opens the cash drawer. By default the cash drawer should be managed by the cash register application.

POST /peri/drawer

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

Open Drawer and Wait

Opens the cash drawer and sends the response when the cash drawer is closed. As the drawer might be left open for a longer time, a HTTP status 102 Processing may be sent after 30 seconds.

POST /peri/drawer/wait

Query

Name	Value	Example
RN	Optional Register Number, default: 'def'	`1_1`

EFR API

Register​

Body​

Cfg - Base data/company header data​

Manual configuration​

Programmatic configuration​

Query​

EFR State​

Request Header​

Export​

Query

Type

Profile​

Query

Body

Tax IDs for testing​

Journal​

Find​

Query Parameter

Request Header

Get Last Transaction​

Query

Request Header

Response

Render​

Peri​

Direct Printing​

Query

Body

Printer State​

Query

Request Header

Response

Line Display​

Query

Body

Open Drawer​

Open Drawer and Wait​

Register

Body

Cfg - Base data/company header data

Manual configuration

Programmatic configuration

Query

EFR State

Request Header

Export

Profile

Tax IDs for testing

Journal

Find

Get Last Transaction

Render

Peri

Direct Printing

Printer State

Line Display

Open Drawer

Open Drawer and Wait