# efsta EFR API and guides
> All pages of the EFR API and EFR guides sections of https://docs.dev.efsta.eu, EFR API specification version 2026-09-16. Index: https://docs.dev.efsta.eu/llms.txt
---
source: https://docs.dev.efsta.eu/efr/api/additional-functions
---
# EFR Additional Functions
:::tip[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.
:::
## Transaction Requests
**POST /restart – Restart Transaction**
| | | |
|-------|-------|---------------------------|
| Query | RN | Optional RN, default: def |
| | TaxId | Optional TaxId |
Formal identically to `/register`, to be used on system restart/recovery.
Use it instead of `/register` when re-sending a transaction after a POS crash or
restart, because duplicate detection is deliberately broader here. On `/register`,
`#DUPLICATE` is only reported for an exact match of the transaction identity. On
`/restart` it is reported as well when:
* `ESR.TN` is missing, or
* `ESR.D` is missing or differs from the stored transaction.
That way a re-send is still recognised as the same transaction even if the POS could
not preserve the original transaction number or timestamp. An already-registered
transaction returns `Result.RC="OK"` with `ErrorCode="#DUPLICATE"` and is **not**
recorded a second time.
**POST /register/void – Void Transaction**
Supply the original transaction data in the request body. EFR will invert amount and quantity fields, add reference information and register as negative transaction.
:::warning
The original transaction is not deleted!
:::
Voiding the transaction of another EFR or client is basically permitted. TL, TT and TN contained in original data are used as reference (RTL, RTT, RTN), for the current post local TL and TT settings are used, also automatic TN.
If TN comes from the sender system, it has to be determined in "Sender ESR" (in addition to the original data):
```
` only). If required, an `ESR.Rsn` value can be specified with `?rsn=...`
**PUT /repo – Register Configuration Change into Audit trail**
| | | |
|-----------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Query | RN | Optional RN, default: def |
| | file | Mandatory, \[path\], filename
Upload configuration file, which is analysed for changes relative to a last version of that file, if applicable. Changes are calculated per line, entered into the audit trail \[FR\] , and returned. |
| Request Header | accept | xml (optional)
In this case a XML document is returned instead of a JSON object |
| Request Example | | http://localhost:5618/repo?file=test.dat |
| Request Body | | plain/txt, UTF-8 |
| Response Status | | 200 OK, 400 Bad Request=BAD, 406 Not Acceptable=NO |
| Response Body | | XML or JSON transaction, UTF-8 |
Response Example JSON:
```
{"AuditC":{
"SQ":8274,
"Result":{"RC":"OK"},
"TY":"Repo","Method":"PUT","File":"test.dat",
"Diff":\[
"+\[0\]: Aurea prima sata est aetas, quae vindice nullo,",
"+\[1\]: sponte sua, sine lege fidem rectumque colebat. ",
"+\[2\]: etc.etc."\],
"Fis":{"Payload":"141,300,Repo,20170905183326,,0014/0001,N,oeZrvtZkwQX…,
"Signature":"\_OodHQgZHeDHj51p…}}}
```
**GET /repo – Register Configuration Change into Audit trail**
| | | |
| --- | --- | --- |
| Query | RN | Optional RN, default: def |
| | file | Mandatory, filename
Retrieve current documented configuration state for a given filename. |
| Request Header | Accept | xml (optional) | In this case a XML document is returned instead of a JSON object |
| Response Status | | 200 OK, 404 No file of this name found |
| Response Body | | XML or JSON transaction, UTF8 |
## Informational Requests
**GET /cer – Certificate**
Get public certificate from file `/EFR/cer/{Serial}.pem`.
Example:
http://localhost:5618/cer/fa814462362ea68d1a0d
Content-Type:
application/x-pem-file
**GET /recorder/lastdh – Last Document Handle**
Use this request after /register to get the Document Handle to this transaction for download of the Digital Receipt from efsta cloud. If you show this URL as QR code on the POS customer display, the bill can be fetched onto a smartphone.
Try out http://localhost:5618/demo/register.html, see "Your Bill" after \[Register\]).
Here, it is implemented as HTML `
`.
To achieve a small QR code use
http://localhost:5618/recorder/lastdh/qr?small=true&ec_level=L
- With the "small" option, the 5 char Transaction Handle TH is omitted, what may cause longer loading time for bill.efsta.net/dh
- `ec_level=L` forces an QR code with low error correction
- Possible QR options:
`ec_level: L|M|Q|H`, `size: default 5`, `margin: default 4`, `fmt: png|pc437|bmp|svc|pdf|eps`
- Attention: when using `
` response.
**GET /log – Realtime Logging**
| | | |
|-----------------|-----|-------------------------------------------------------------------------------------------------------------------|
| Query | iid | Instance id (e.g. computer name), keep static for one client
used to respond with the latest log lines only |
| Request Example | | http://localhost:5618/log?iid=HUGO23 |
Response Example:
```
{
"Lines":\["16:14:37.083 Checkin {\\"log\\":{\\"TY\\":\\"START_EFR\\",…
```
Used for interactive log viewer.
## Journal
**POST /render – Show Transaction**
To render a specific transaction, JSON
`{"\_":"Tra"… or XML … data (fetched using /find or /tra before)`
can be posted.
**GET /retrieve – Retrieve Journal Records**
| | | |
|-----------------|--------|--------------------------------------------------------------------|
| Query | RN | Optional, journal to use, default: 'def' |
| | last | Required, SQ to start reading behind
last=0 from beginning |
| | endSQ | End point |
| | target | Folder to store retrieved #######.json |
| | | Further filter options see 5.4.4 GET /find – Find Journal Record |
| Request Example | | http://localhost:5618/retrieve?rn=210&_=Tra |
| Authentication | | Local operation only (localhost) or Profile.Password authorization |
| Response Body | | XML or JSON data stream |
This request is intended to do periodical retrieval of records for backup or closure/balance reporting. Retrieval is started with SQ _behind_ the last query parameter, for contiguous processing send the last SQ recently processed.
**POST|GET /jou/reprintcnt – Reprint Count (deprecated)**
:::warning[Deprecated]
`/jou/reprintcnt` is deprecated and is only documented for reference of existing integrations. Register the reprint as a non-fiscal transaction marked `NFS="DUP"` instead – see the business case [Reprints](/efr/api/business-cases#reprints).
:::
| | | |
|-----------------|-----------------|----------------------------------------------------------------------------------------------------|
| Query | RN | Journal to use, default: 'def'
do not specify if parameter RN_TT is set (see 6 Configuration) |
| | TL, TT, TN, ESR | Properties used as identification key |
| Request Example | | http://localhost:5618/jou/reprintcnt?tl=001&tt=1&tn=4711 |
| Authentication | | None |
| Response Body | | Text/plain containing counter only |
:::note
In some countries each transaction reprint has to be marked with a counter; use this function to GET or POST (=increment) this count. In \[FR\] a fiscal signature is delivered upon POST, for details see [EFR Guide FR (PDF)](https://public.efsta.net/efr/FR/EFR_Guide_[FR]_v1.50.pdf).
:::
:::tip[Good to know]
As with version 1.5.2 the counter data is stored locally, a common cloud enumeration will be implemented in a future version of EFR.
:::
## Maintenance
**POST /service/restart – Restart App**
:::note
Despite the name this only **shuts the application down**. It does not start it again
itself — coming back up depends on the surrounding service manager (Windows service,
systemd unit, container restart policy). If nothing is configured to restart the EFR,
it stays down.
:::
Request Example:
http://localhost:5618/service/restart?password=mypwd
Authentication:
local operation only (localhost) or Profile.Password authorization
Response:
http status code 200, empty body
**GET|POST /service/config – Service Configuration**
Browser URL:
http://localhost:5618/service/config
Web form to configure incremental backup storage path and retrieve last backup result.
**GET /backup – Download Backup .zip**
| | | |
|-----------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Query | RN | Optional, backup for RN, default: 'def' |
| | from | Optional date |
| | last | Optional, name of last backup file received
Used for incremental backup, default: full backup |
| Request Example | | http://localhost:5618/backup?rn=4711&last=0023 |
| Authentication | | Local operation only (localhost) or Profile.Password authorization |
| Response Header | Content-type | application/zip |
| | Content-disposition | attachment; filename=####.zip
The filename is derived from the latest .jou file used. Therefore identical filenames may be delivered for subsequent backup jobs, files may be replaced on target directory. |
| Response Body | | binary .zip file |
For retrieving EFR log files http://localhost:5618/backup/log or set flag `/backup?log`.
**GET /backup/incremental – Incremental Backup onto Storage Directory**
| | | |
|-----------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Query | RN | Optional, backup for RN, default: 'def' |
| | | Path specify path to backup storage root directory, where backup .zip files are stored under the corresponding RN subdirectory; example:
`path=D:/mybackup => D:/mybackup/def/0000.zip`
May be preset using /service/config API. |
| Request Example | | http://localhost:5618/backup/incremental?path=D:/mybackup |
| Authentication | | Local operation only (localhost) or Profile.Password authorization
| Response Header | Content-type | text/plain |
| Response Body | | Processing info
Processing time depends on data volume stored and storage access speed. |
**GET|POST /backup/restore – Restore onto new (unused) EFR Installation**
| | | |
|-------------|------|---------------------------------------|
| Query | RN | Name of RN to restore, default: 'def' |
| | path | Path to backup storage |
| Browser URL | | http://localhost:5618/backup/restore |
:::info
**ONLINE**
Restore may be used on offline systems (not connected to efsta cloud) only.
**IN_USE**
RN folders in use may not be overwritten.
:::
:::note
After hitting the \[RESTORE\] backup .zip files from path are restored.
Progress of restauration is displayed on screen or may be fetched using GET /backup/info.
:::
**GET /backup/log – Download Logging .zip**
| | | |
|-----------------|--------------|---------------------------------------------------------------------------------------------|
| Query | RN | Optional, backup for RN, default: def |
| | from | Optional, JSON date, deliver .log from date |
| | till | Optional, JSON date, deliver .log to date |
| Request Example | | http://localhost:5618/backup/log?rn=4711&last=0023 |
| Authentication | | No permission required, only .log processing information without business data is delivered |
| Response Header | Content-type | application/zip |
| Response Body | | binary .zip file |
:::note
This request may be used to fetch logs from an EFR for support purposes. In online configurations an uploadlog request may be triggered from cloud.
:::
**GET /disk – Storage Information**
Request Example:
http://localhost:5618/disk
Response Example:
```
{"Usage":5.215046,
"Path":{
"cer":{"dirs":3,"files":33,"size":2929363},
"gbl":{"dirs":1,"files":7,"size":11084},
"log":{"dirs":0,"files":59,"size":2039365},
"rn/def":{"dirs":4,"files":120,"size":235234}}}
```
Usage states the total storage used in MB.
**GET /disk/dir – Remote DIR Request**
Request Example:
http://localhost:5618/disk/dir
Delivers a directory list (text/plain) with last modification timestamp and size in bytes.
**POST /disk/clean – Clean Storage**
| | | |
|-----------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Query | quota | Disk quota allowed in MB
in case of overrun cleaning is done to 80% of this value
does not affect DiskQuota Profile setting |
| | keep | Date, from which files have to be kept
3 full months by default, i.e. on 2017-12-24 keep=2017-09-01 is used
a numeric value is interpreted as days, e.g. keep=90 |
| Request Example | | http://localhost:5618/disk/clean?quota=800 |
| Response Body | | XML or JSON
Storage Information according to GET /disk |
**POST /lic – Activate License**
| | | |
|-----------------|-----|----------------------------------------------------------|
| Query | rn | Target client (by default "def") |
| | key | License key retrieved from efsta Portal |
| Request Example | | http://localhost:5618/lic?key=%20demo.cde.e202005.mzk5iv |
## Utility
**GET /authorization – Authorization for Third Party Cloud Access**
| | | |
|-----------------|--------------|--------------------------------------------------------------|
| Request Example | | http://localhost:5618/authorization |
| Response | JWT | Signed using EFR communication certificate |
| | Content-type | text/plain |
| Authentication | local | Operation only (localhost) or Profile.Password authorization |
**GET /qr – QR Image**
| | | |
|-----------------|--------------|-------------------------------------|
| Query | text | QR source data (encodeURIComponent) |
| | type | png (default), bmp, svg, pc437 |
| | size | Module size in pixels |
| | margin | In modules, default: 1 |
| Request Example | | http://localhost:5618/qr?text=... |
| Response Header | Content-type | image/png for image types |
| | Content-type | text/plain for type=pc437 |
Windows PowerShell example:
```
PS C:\\> curl
Uri:
StatusCode : 200
StatusDescription : OK
Content : {137, 80, 78, 71...}
```
JavaScript example (simplified, text in URL):
```
C:\\> node
\> var http = require('http')
\> var req = http.request({ host:'localhost', port:5618, path:'/qr/'+encodeURI('hello world') }, res=>{
res.on('data', data=>{ console.log(data) }) // expected:
})
\> req.end()
```
PC437 can be used to print a QR within HTML or a text file. For this PC437 block characters ' ▀▄█' (unicode ` ▀▄█`) are used. For negative rendering (e.g. on screen) invert to \[219, 220, 223, 32\]. VB-Script example (querystring parameters):
```
Set Http = CreateObject("Msxml2.ServerXMLHTTP")
Http.open "GET", "" & Fis_Code, True
Http.send ""
Do While Http.readyState <> 4
Http.waitForResponse 10
Loop
If Http.Status = 200 Then
Printer.Font.Name = "Courier New"
Printer.Font.Size = 3
Printer.Font.Charset = 255 ' OEM_CHARSET PC437
Printer.Print Http.responseBody
End If
```
## Manage Custom Layout Files
Custom layout files (EJS or PUG templates) can be managed through the `/peri/layout` endpoint.
**GET /peri/layout – Retrieve Custom Layout(s)**
| | | |
|-----------------|--------|--------------------------------------------------------------------------------------------------|
| Query | name | Optional, name of a specific layout to retrieve (without file extension) |
| | RN | Optional RN, default: def |
| | type | Optional, filter by layout type: `pug` or `ejs` |
| | | If no query parameters are provided, all available layouts are returned |
| Request Example | | http://localhost:5618/peri/layout?name=TRAINING |
| Response Status | | 200 OK, 404 Not Found |
| Response Body | | XML or JSON layout information, UTF-8 |
**Response Fields:**
| Field | Description |
|--------------|----------------------------------------------------------------|
| RN | Register Number the layout belongs to |
| layouts | Array of matching layout entries |
| layouts.name | Layout name (without file extension) |
| layouts.filePath | File system path to the layout template file |
| layouts.layoutType | Template engine type: `EJS` or `PUG` |
**Response Examples:**
```xml
def
TRAINING
path/to/TRAINING.ejs
EJS
```
```json
{
"RN": "def",
"layouts": [
{
"name": "TRAINING",
"filePath": "path/to/TRAINING.ejs",
"layoutType": "EJS"
}
]
}
```
:::note
When no `name` or `type` filter is specified, all custom layouts across the given RN are returned. The `layouts` array will contain one entry per layout file found.
:::
**Error Response (404 Not Found):**
```xml
BAD
#FILE_NOT_FOUND
Layout file not found
```
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#FILE_NOT_FOUND",
"Message": "Layout file not found"
}
}
```
**POST /peri/layout – Upload Custom Layout File**
| | | |
|-----------------|--------------|----------------------------------------------------------------------------------------------|
| Query | RN | Optional RN, default: def |
| Request Example | | http://localhost:5618/peri/layout |
| Content-Type | | `multipart/form-data` |
| Request Body | file | Form-data file upload — the layout template file (`.pug` or `.ejs`)
The layout name and type are derived from the uploaded filename |
| Response Status | | 201 Created, 400 Bad Request, 409 Conflict |
| Response Body | | XML or JSON confirmation, UTF-8 |
Upload a custom layout template file using `multipart/form-data`. The file is stored under the RN configuration directory. The layout name and type are determined from the uploaded filename (e.g. `TRAINING.pug`).
**Success Response (201 Created):**
```xml
training
PUG
def
path/to/training.pug
```
```json
{
"name": "training",
"layoutType": "PUG",
"RN": "def",
"filePath": "path/to/training.pug"
}
```
**Error Responses:**
400 – Missing file upload:
```xml
BAD
#MISSING_FILE
Missing required file upload
```
400 – Template syntax error:
```xml
BAD
#PUG_SYNTAX_ERROR
Unexpected token (2:15)
```
409 – File already exists:
```xml
BAD
#FILE_EXISTS
File already exists.
```
400 – Missing file upload:
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#MISSING_FILE",
"Message": "Missing required file upload"
}
}
```
400 – Template syntax error:
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#PUG_SYNTAX_ERROR",
"Message": "Unexpected token (2:15)"
}
}
```
409 – File already exists:
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#FILE_EXISTS",
"Message": "File already exists."
}
}
```
:::tip[Good to know]
Use the PUG Editor (`/peri/pugedit`) for interactive editing and previewing of PUG layout templates directly in the browser.
:::
**PUT /peri/layout – Update Custom Layout File**
| | | |
|-----------------|--------------|----------------------------------------------------------------------------------------------|
| Query | RN | Optional RN, default: def |
| Request Example | | http://localhost:5618/peri/layout |
| Content-Type | | `multipart/form-data` |
| Request Body | file | Form-data file upload — the updated layout template file (`.pug` or `.ejs`)
The layout name and type are derived from the uploaded filename |
| Response Status | | 200 OK, 400 Bad Request, 404 Not Found |
| Response Body | | XML or JSON confirmation, UTF-8 |
Update an existing custom layout template file using `multipart/form-data`. The layout to update is identified by the uploaded filename (e.g. `training.pug`).
**Success Response (200 OK):**
```xml
training
PUG
def
path/to/training.pug
```
```json
{
"name": "training",
"layoutType": "PUG",
"RN": "def",
"filePath": "path/to/training.pug"
}
```
**Error Responses:**
400 – Missing file upload:
```xml
BAD
#MISSING_FILE
Missing required file upload
```
400 – Template syntax error:
```xml
BAD
#PUG_SYNTAX_ERROR
Unexpected token (2:15)
```
404 – Layout not found:
```xml
BAD
#FILE_NOT_FOUND
Layout file not found
```
400 – Missing file upload:
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#MISSING_FILE",
"Message": "Missing required file upload"
}
}
```
400 – Template syntax error:
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#PUG_SYNTAX_ERROR",
"Message": "Unexpected token (2:15)"
}
}
```
404 – Layout not found:
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#FILE_NOT_FOUND",
"Message": "Layout file not found"
}
}
```
**DELETE /peri/layout – Delete Custom Layout File**
| | | |
|-----------------|--------|--------------------------------------------------------------------------------------------------|
| Query | name | Required, name of the layout to delete (without file extension) |
| | RN | Optional RN, default: def |
| Request Example | | http://localhost:5618/peri/layout?name=training |
| Response Status | | 200 OK, 404 Not Found |
| Response Body | | XML or JSON, UTF-8 |
**Success Response (200 OK):**
```xml
training
PUG
def
true
```
```json
{
"name": "training",
"layoutType": "PUG",
"RN": "def",
"deleted": true
}
```
**Error Response (404 Not Found):**
```xml
BAD
#FILE_NOT_FOUND
Layout file not found
```
```json
{
"Result": {
"RC": "BAD",
"ErrorCode": "#FILE_NOT_FOUND",
"Message": "Layout file not found"
}
}
```
## File Interface
Instead of using a webservice, transactions can be registered using a file interface. In this case a request file is provided on the request directory, with the response being delivered as response file.
As first step, the communication directories have to be created. The FileWatch operation will only be started if the following exists on EFR startup:
`C:\\> mkdir C:\\ProgramData\\EFR\\req`
`C:\\> mkdir C:\\ProgramData\\EFR\\res`
:::note
Directory req serves as 'request' container, res is for response files.
:::
As soon as a file `req\1234.req` is created (XML or JSON formatted), the response is provided in `res\1234.res` and the .req is deleted. After processing, the .res file has to be removed by the foreground application. The files have to be uniquely named (e.g. corresponding to Transaction Number TN, UUID, time stamp), if multiple clients are handled in one EFR, also add client ID 'RN'.
Query parameters usually set in `/register` webrequest (RN, TaxId) can be set within request data, e.g.:
```
> Attributes p.), a file 1234.bmp is created in `\res`.
The proper function of FileWatch depends on the underlying file system. If this does not support native watching, the program will switch to directory polling (300ms interval). On some systems, files are not locked during writing and parser errors may occur. In this case, creating a temporary file 1234.tmp and renaming it to 1234.req is recommended.
## Attributes
In `profile.cfg` Attributes field flags can be set for transaction processing. Attributes is parsed as space delimited list according to HTML element definition, Attr names are case insensitive. Formally valid declarations:
```
myattr myattr=hello myattr="hello world" myattr='hello "world"'
```
Declaration without attribute value is interpreted as true.
:::tip[Good to know]
Attributes affecting general program behaviour may require EFR restart to get into action.
:::
**Table of Attributes**
| Attribute | Countries | Module | Remarks |
|---------------------------|:------------:|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| App_restartAt | | app | Perform automatically a daily restart at hh:mm:ss (default 3:00) |
| Device_Auth | | | Authorization with external devices with username and password e.g.: `Device_Auth=username:password` |
| eDoc_test | | Normalize | Deliver e-invoices to the country's test platform a plain 2-letter `ESR.DD` is extended by `-TEST`, e.g. `FR` becomes `FR-TEST` an explicit DD like `PL-DEMO` is left unchanged not the same as `Fiscal_Test` (training mode) see [E-Invoicing](/e_invoicing/api/general) |
| EFR_test | | Cloud | Handle EFR instance as test system reports are not forwarded to the Fiscal Authority (or marked as 'test' resp.) |
| FileWatch_path | | FileWatch | Network path to watched folder example: `FileWatch_path=\\share\EFR` |
| Fiscal_ApiKey |
[PT]
| Fiscal | Fiscal partner reference restart EFR for activation |
| Fiscal_BackupAt |
[DE]
| Fiscal | Time at which the daily TSE backup should be performed default: 04:00 |
| Fiscal_acceptUnauthorized |
[CZ]
| Messenger | Not to be used generally, workaround for Error: unable to verify the first certificate This occurs, if the Fiscal System does not supply the whole SSL certificate chain on startup of a TLS connection. |
| Fiscal_Log | | Fiscal, Messenger | Write `/rn/def/log/yyyymmdd_hhmmss.log` files (containing fiscal XML) for _all_ transactions, not only in case of error use this option to check the fiscal representation of special business cases |
| Fiscal_Rules |
[FR]
[SK]
| Fiscal | Fiscalization rules to follow, e.g. `Fiscal_Rules=LNE` |
| Fiscal_Test |
[AT]
| Fiscal | Interpret transactions as `NFS="Training"` transactions are processed as "Training" according to fiscal law |
| Fiscal_Test |
[CZ]
[DE]
[FR]
[HR]
[SI]
[SK]
| Fiscal | Report transaction to Fiscal Authority's playground system< set this attribute during test phase |
| Fiscal_Timeout |
[AT]
[CZ]
[DE]
[HR]
[IT]
[SI]
[SK]
| Fiscal, Messenger, TSE_\* | Timeout in ms for fiscal processing (request to fiscal system, local signature creation or remote sign request) timeout testing: `fiscal_timeout=1` |
| Fiscal_YearEnd |
[FR]
| Fiscal | Specify month, when audit code 60 "Clôture d’exercice" shall be reported (01-12, default: 12) |
| Fiscal_Z | | Launch | If set, a Z-Report / End of Day is inserted before registration of a transaction for the new date (ESR.D). In countries with a fiscal printer, a daily closing statement is printed as a receipt. |
| Fis_Certification |
[FR]
| Fiscal | Certification number printed in the `Code:` tag (issued by INFOCERT). Default: `B0000` (NF525) or `00000-0` (LNE). Set to `none` to omit the tag. |
| Fis_Sec |
[FR]
| Fiscal | Alias for `Fis_Certification`; takes precedence if both are set. |
| Fis_Code |
[CZ]
| Fiscal | Deliver PKP in `` |
| Fis_OCR |
[AT]
| Fiscal | Add OCR string to `` element in response (BASE32 coded) |
| Fis_QR |
[AT]
[DE]
[SI]
| Fiscal | Add QR image (base64) to `` element in response specify type and size according to `/control/qr` example: `fis_qr=type=png&size=2&ec_level=L` |
| Fis_Tot | | Checkout | Include fiscal grand totals in responses `` element |
| FN_series |
[PT]
| Fiscal | Series ("A"-"Z", excluding "M") to be used after replacement and initialization of a POS system to avoid duplicates with previously issued documents |
| HttpServer_Disable | | app | Do not start webserver, transaction registration may be done using the file interface directories `/req` and `/res` |
| HttpServer_IPv4 | | HttpServer | Use IPv4 addressing instead of IPv6 Windows XP: automatically set to true, reset with `httpserver_ipv4=6` |
| HttpServer_respond102 | | HttpServer | During request processing (e.g. completion of fiscal printout) respond intermediate HTTP-Status 102 (after ms specified, default 9000) |
| HttpServer_respond200 | | HttpServer | Respond HTTP-Status 200 also in case of BAD and NO some requestors can parse a success response only |
| HttpServer_AllowOrigin | | HttpServer | Set HTTP-Header Access-Control-Allow-Origin on all requests (CORS) example: `HttpServer_AllowOrigin=localhost` |
| HttpServer_AllowCredentials | | HttpServer | Set HTTP-Header Access-Control-Allow-Credentials on all requests (authenticated CORS) example: `HttpServer_AllowCredentials=true` |
| IO_debug | | IO | Request additional IO logging |
| IO_nosync | | IO | Do not sync onto hard disk setting this attribute on systems with UPS improves transaction throughput |
| IO_DeferTimeout | | IO | Defer .jou writing (in ms, default 1000) |
| Log_debug | | Log | Log without .log file size limits |
| Log_length | | Log | Length of log lines into `/EFR/log/\*.log` |
| Log_remove | | Log | RegExp to specify items to be removed from log lines example to remove amounts: `Log_remove=[=:]"?\d*\.\d+"?` |
| Normalize_D | | Normalize | Number of days for ESR.D date validation (default 7) example approx. 1 month: `Normalize_D=31` |
| Print_Log | | Print | Creates check file `/EFR/rn/def/print.log` (intermediate html) |
| Printer | | Deliver | Specify printer driver (in directory `/Peri/driver`) for transaction printing example: `Printer=Epson_TM` |
| Printer_Port | | Fiscal printer modules | Connection port assignment example: `COM1:9600 ETH:192.168.0.2` |
| Printer_Log | | fiscal printer modules | Printer communication is traced into `/EFR/log/yyyymmddp.log` |
| Recorder_init | | Recorder | Delay for initialization of cloud connection in ms (default 10000) adjust this parameter in case of specific system startup behaviour example: `recorder_init=60000` (1 minute) |
| Recorder_Log | | Recorder | Log online cloud communication into `/log/{date}r.log` |
| Recorder_staging | | Recorder | efsta internal: use cloud staging instance
restart EFR to take effect |
| Register_disable |
[AT]
| app | Not a registration EFR instance set on SignServer instances |
| SC_disable | | app | Do not use local smartcards |
| SC_ignore |
[AT]
| SC | Do not connect the smartcard reader specified, so it can be used by other applications – specify reader name (RegExp, cas insensitive) example: `SC_ignore=gemplus` |
| SC_Log |
[AT]
| SC | Smartcard APDU command tracing into `/log/{date}s.log` |
| Sign_debug |
[AT]
| A-Trust Prime-Sign | Additional web request logging |
| SignServer |
[AT]
[DE]
| SignServer TSE | EFR SignServer operation, other EFRs in the same LAN may use the smartcards or TSEs of this server |
| SoftwareProvider | | Cloud | Provider of POS software used in efsta cloud for hierarchial EFR management, if a company is served by different software providers |
| TEST_Verify_err |
[CZ]
[SI]
[SK]
| Messenger | For testing an invalid signed response from fiscal system |
| TEST_RC | | Normalize | For testing a BAD or NO response example: test_rc=NO |
| Tra_DH | | Checkout | Include Document Handle DH in /register `` response for bill.efsta.net access (EFR in Online mode required) |
| TSE_AdminPin |
[DE]
| TSE | Set the AdminPin for the TSE. See [EFR Guide DE](/efr/DE) |
| TSE_AdminPuk |
[DE]
| TSE | Set the AdminPuk for the TSE. See [EFR Guide DE](/efr/DE) |
| TSE_BackupAt |
[DE]
| TSE | Configure TSE backup time for local and remote TSE (default randomized between 03:10:00 and 04:10:00) set `TSE_BackupAt=NO` to disable automatic backup |
| TSE_BackupDelete |
[DE]
| TSE | Set this flag to enable TSE export backup for manufacturer TSE server drivers like Diebold-Nixdorf or Epson (local and network): export/backup and delete is performed after each Z Report (NFS=Z) |
| TSE_install |
[DE]
| TSE_DF, TSE_SBC | Set `TSE_install=NO` to block automatic driver installation from efsta cloud, the driver manually installed is used valid for Deutsche Fiskal cloud TSE |
| TSE_KeepAlive |
[DE]
| TSE_SB | Set device polling interval in sec (default 10), which may be required to block automatic USB power off by system’s energy management valid for Swissbit local TSE |
| TSE_MountPoint |
[DE]
| TSE | Set path to TSE mount points on Linux, e.g. `TSE_MountPoint=/mnt/` or specify devices to scan on Windows, e.g. `TSE_MountPoint=D:,E:` |
| TSE_PortScan |
[DE]
| TSE | Example: `TSE_PortScan=10.0.0.10-20:10001,10.0.0.255:20001` see “TSE Assignment” for details |
| TSE_SelfTestAt |
[DE]
| TSE_SB | Configure auto selfTest time (default 03:05:00) valid for Swissbit local TSE |
| TSE_TimePin |
[DE]
| TSE | Set the TimePin for the TSE. See [EFR Guide DE](/efr/DE) |
| TSE_TimePuk |
[DE]
| TSE | Set the TimePin for the TSE. See [EFR Guide DE](/efr/DE) |
| UdpServer_disable |
[AT]
| app | Block SignServer action (as server) and signature (as client) |
## EFR as HTTPS Server
### Server Identity
The EFR runs as an HTTPS server as soon as a server certificate is available. You can provide the certificate in one of the following ways – if more than one is present, the EFR uses the first match from the top of this list:
| Priority | How to provide the certificate |
|----------|--------------------------------|
| 1 | A certificate file at a path you set with the environment variable `EFSTA_EFR_SSL_CERT` |
| 2 | The certificate file `/EFR/cer/ssl.pfx` (uploaded via API or copied manually) |
If no certificate is available, the EFR runs as a plain HTTP server. If a certificate is found but cannot be used (for example because of an incorrect password), the EFR also falls back to HTTP instead of failing to start.
If HTTPS is enabled, it is effective also for web requests (e.g. https://localhost:5618/control). If (for inhouse communication only) a self signed certificate is used, this will cause a security alert from the browser:
1. in Google Chrome navigate here and click `[Enabled]`
(source: stackoverflow.com)
2. in Mozilla Firefox, upon security warning click on `[Extended]`, `[Add Exception]` and confirm the certificate.
#### Certificate file (ssl.pfx)
Place your certificate as the file `/EFR/cer/ssl.pfx`. Depending on how the client verifies the server, the file should also contain the intermediate certificates of the chain.
Password-protected certificates are supported. You can supply the password when [uploading the certificate via API](#uploading-certificates-via-api), or set it in the environment variable `EFSTA_EFR_SSL_PASSWORD`.
A password supplied with the upload is stored encrypted in the file `/EFR/cer/ssl.json` next to the certificate, so it does not have to be configured anywhere else. The EFR reads it on every start. Uploading a certificate without a password removes this file again.
If `EFSTA_EFR_SSL_PASSWORD` is set, it takes precedence over the stored password.
:::note
Earlier EFR versions required `ssl.pfx` to have an empty password. This is no longer the case – password-protected certificates can now be used.
:::
#### Certificate via environment variable
Set `EFSTA_EFR_SSL_CERT` to the full path of your certificate file. If the certificate is password-protected, set the password in `EFSTA_EFR_SSL_PASSWORD`:
```
EFSTA_EFR_SSL_CERT=C:\certs\myservercertificate.pfx
EFSTA_EFR_SSL_PASSWORD=secret
```
### Client Verification
Enablling HTTPS forces encrypted communication, but does not secure EFR against third party access. This can be achieved by TLS client certificate authentication. Here, the browser (e.g. https://.../control) and programmatic (e.g. https://.../register) requests need to be authenticated by a client certificate.
Client certificate authentication is enabled automatically as soon as the folder `/EFR/cer/client` exists. Requests without a trusted client certificate are then rejected.
#### Whitelist Method
Provide the respective public certificates in the folder `/EFR/cer/client` (as .pem, .crt, .cer or .der, PEM or DER format).
#### CA Certificate
More elegant client certificates can be derived from a common 'CA' certificate, which is declared as `/EFR/cer/client/ca\*.pem`. Client certificates are then verified to be issued by that CA certificate. The CA certificate can be placed in the folder manually or uploaded via `POST /cer/ca` (see [Uploading Certificates via API](#uploading-certificates-via-api)).
**Example**
Example of generating CA and client certificates using openssl (openssl.org"):
```
openssl req -x509 -newkey rsa:4096 -days 3650 –nodes -keyout ca.key -out ca.pem
-subj "/O=efsta/OU=EFR/CN=EFR SSL client CA"
openssl genrsa -out client.key 1024
openssl req -new -key client.key -out client.csr
-subj "/O=efsta/OU=EFR/CN=EFR SSL client"
openssl x509 -req -days 3650 -in client.csr -CA ca.pem -CAkey ca.key
-set_serial 01 -out client.pem
openssl verify -CAfile ca.pem client.pem
openssl pkcs12 -export -in client.pem -inkey client.key -password pass:
-out client.pfx
```
Setting it into action:
```
COPY myservercertificate.pfx C:\\ProgramData\\EFR\\cer\\ssl.pfx
MD C:\\ProgramData\\EFR\\cer\\client
COPY ca.pem C:\\ProgramData\\EFR\\cer\\client\\ca.pem
```
For requests (browser and program), client.pfx is used as client certificate.
#### Network Configuration
Of course, access restriction can be configured using the server's firewall.
### Uploading certificates via API
Instead of copying the certificate files manually, both the HTTPS server certificate and the client CA certificate can be uploaded to a running EFR. This works the same way signing certificates are provided and is convenient for a remote or automated setup.
**POST /cer/ssl – Upload HTTPS Server Certificate**
Uploads your server certificate (`.pfx`/`.p12`) and saves it as `/EFR/cer/ssl.pfx`. The EFR decodes the certificate before saving it, so an invalid file or a wrong password is rejected and the certificate already in use stays untouched. The new certificate becomes active after the next EFR restart.
| Part | Description |
|------------------|----------------------------------------------------------------------------------------------------------------------------|
| Query `password` | Optional, the password of a password-protected certificate (`passphrase` is accepted as well) |
| Request Body | The certificate file – as raw file, as base64 in the JSON field `sslCert`, or as the `ssl` field of a multipart form |
| Response Status | 200 OK, 400 if the certificate or the password is invalid |
The password can also be sent in the request body instead of the query string, as the field `password` of the JSON body or of the multipart form. A password in the body takes precedence over the query parameter. It is stored encrypted in `/EFR/cer/ssl.json` and applied automatically on the next start – uploading a certificate without a password deletes that file again.
```
curl -X POST "http://localhost:5618/cer/ssl?password=secret" \
-H "Content-Type: application/x-pkcs12" \
--data-binary "@myservercertificate.pfx"
```
A rejected upload answers with 400 and a short reason, for example `cannot decode SSL certificate, wrong password?` or `invalid SSL certificate file (expected a PKCS#12 .pfx)`.
**POST /cer/ca – Upload Client CA Certificate**
Uploads a client CA certificate and saves it as `/EFR/cer/client/ca.pem`. EFR then uses it to verify client certificates (see [Client Verification](#client-verification)).
| Part | Description |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
| Request Body | The CA certificate – sent as raw file (PEM or DER), or as base64/PEM in a JSON field `caCert`, or as the `caCert` field of a multipart form |
| Response Status | 200 OK, 400 if no certificate was provided |
```
curl -X POST "http://localhost:5618/cer/ca" \
-H "Content-Type: application/x-x509-ca-cert" \
--data-binary "@ca.pem"
```
## Browser Authentication
### Basic Authentication
Sensible parts of EFR configuration like http://localhost:5618/control can be protected by setting an EFR system password in profile form:
Upon browser access, username and password have to be entered, then only the password is verified. To have a password upon installation, you can provide an initial configuration file `/EFR/gbl/profile.cfg`.
:::warning
Please be aware, when accessing EFR over network using HTTP protocol, the entered password is transferred unencrypted – instead switch to HTTPS or use Digest Access Authentication.
:::
### Digest Access Authentication
For appropriate username/password configuration according to RFC 2617, a userlist file `/EFR/gbl/.htdigest` can be provided. This is a text file according to Apache WebServer specification, containing `${username}:${realm}:${hash}` per line.
**Example**
```
user1:EFR:2f72912bba017d9352a753df2fdf946d
user1:EFR.001_1:a498cdc760ca554cf44b85c846a1bef5
user2:EFR.001_2:73946a4756fdaff0c0d24e66c28357d3
```
The second field 'realm' is "EFR" by default, but for multi client operation a separate username/password combination can be set for each realm `"EFR.${RN}"`. In the example above, user1 could access RN 001_1 (line 2) and e.g. 001_3, as for this RN no specific user is assigned. 001_2 can be accessed by user2 only.
The third field 'hash' is defined as
`hash = md5(username+":"+realm+":"+password)`
For convenience, the Apache password manager htdigest may be used to create a .htdigest file on Linux.
```
$ htdigest .htdigest EFR user1
Adding user user1 in realm EFR
New password:
```
---
source: https://docs.dev.efsta.eu/efr/api/ai-agent-integration
---
# AI & Agent Integration
efsta provides an [MCP](https://modelcontextprotocol.io) server that lets AI coding
assistants answer EFR integration questions from efsta's own specification and
documentation instead of guessing. Your assistant can look up which fields a business
case needs in a given country, get a complete request example, and check a `/register`
payload before you send it to an EFR.
| | |
|---|---|
| Server URL | `https://mcp.docs.efsta.eu/mcp` |
| Transport | Streamable HTTP |
| Authentication | None. The server only serves public documentation. |
| Rate limit | 120 requests per minute per IP address |
## What the assistant can do
| Tool | Use it for |
|---|---|
| `get_register_case_requirements` | Which fields a business case (sale, refund, void, invoice, Z-report, …) needs, optionally for one country: fields required everywhere, fields mandatory only in that country, and fields that do not apply there |
| `get_case_example` | A complete, valid `/register` request for a business case, in JSON or XML |
| `validate_register_payload` | Checks a JSON request body against the specification. Errors name the business case whose rule failed; country-specific rules come back as warnings |
| `search_efsta_docs`, `fetch_doc` | Finds and reads the relevant documentation pages |
| `list_endpoints`, `get_endpoint_schema` | The published EFR endpoints and their request and response schemas |
The EFR has one API for all countries: every transaction goes through `POST /register`,
and the business case follows from the fields you send (see
[Business Cases](/efr/api/business-cases)). The answers come from the same model that
generates the [OpenAPI reference](/efr-api/), so they always match the published
specification.
## Connect your assistant
### Claude Code
```bash
claude mcp add --transport http efsta-docs https://mcp.docs.efsta.eu/mcp
```
To share the configuration with your team, add it to `.mcp.json` in your repository
instead:
```json
{
"mcpServers": {
"efsta-docs": { "type": "http", "url": "https://mcp.docs.efsta.eu/mcp" }
}
}
```
### Cursor
Add the server to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all
projects):
```json
{
"mcpServers": {
"efsta-docs": { "url": "https://mcp.docs.efsta.eu/mcp" }
}
}
```
### GitHub Copilot (VS Code)
Add the server to `.vscode/mcp.json` in your project, then start it from the file or
the MCP view and use Copilot Chat in agent mode:
```json
{
"servers": {
"efsta-docs": { "type": "http", "url": "https://mcp.docs.efsta.eu/mcp" }
}
}
```
## Example questions
- "Which fields does a refund need in Portugal?"
- "Show me a complete XML request for a void."
- "Validate this `/register` payload for a German EFR: …"
- "How do I re-send a transaction after the POS crashed?"
- "Which fields are mandatory for invoices?"
## Without MCP: llms.txt
For assistants that cannot connect to an MCP server, the documentation is also
available in plain Markdown, following the [llms.txt](https://llmstxt.org) convention:
| File | Content |
|---|---|
| [`/llms.txt`](pathname:///llms.txt) | Index of all pages with a short description, linking to Markdown copies |
| [`/llms-full.txt`](pathname:///llms-full.txt) | All EFR API and EFR guide pages in one file, with the request examples |
Point your assistant to one of these URLs or paste the file into the conversation.
Both are generated from the same sources as this site whenever it is deployed.
## Data and privacy
The server is read-only and has no access to customer, tenant or transaction data. It
answers from the public documentation only.
Payloads you validate are checked in memory and are not stored or logged. We record
which tool was called, the argument names and types, and the response time, never the
argument values, to learn which questions integrators ask. Still, use test data rather
than real customer data in payloads you validate.
---
source: https://docs.dev.efsta.eu/efr/api/api
---
# EFR API
:::tip[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](#register) and [CFG](#cfg---base-datacompany-header-data) are mandatory to use the EFR. In fiscal printer countries, [PERI](#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](rule-set#communication-workflow).
If you have any comments or questions to this document please contact us at: [ticket@efsta.eu](mailto:ticket@efsta.eu)
:::tip[Machine-readable reference]
The [EFR Unified API Reference](/efr-api/) provides an OpenAPI 3.1 specification
with endpoint descriptions, field definitions, country requirements, and JSON and
XML examples. You can import it into tools such as Postman or Insomnia.
The download filename includes the specification's version date. For a fixed URL
to the current version, use
efr-openapi.yaml.
For business-case requirements, see
[Business Cases](/efr/api/business-cases) and
[Country Specific Business Cases](/efr/api/country-specific).
:::
:::warning[Important]
If the EFR is used for multiple companies (see [EFR Architecture](/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](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](rule-set#esr--efsta-simple-receipt-format) and the values for the payment group are descript at [Payment groups](rule-set#payment-groups---paypayg).
:::
**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"}
],
"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](rule-set#response-trac-tra-completion)
```xml
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;...
```
```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;..."
"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" }
]
}
}
}
```
### E-Invoicing
To send an invoice as e-Invoice as well, you have to trigger the electronic delivery with the (Document Delivery) DD field (e.g., `DD="IT"`). \
The `DD` value determines the System through which the E-Invoice is transmitted. In the example above, setting DD="IT" triggers the E-Invoicing process for Italy. If you want to use the test system just append -TEST, f.e: `IT-TEST`.
If required, also provide the (Document Delivery To) `DDto` field. That defines the Country-specific recipient identifier for the E-Invoice. [More infos here](/e_invoicing/api/general)
**Example Request for Italy Testsystem**
```json
{"Tra":
{"ESR":
// highlight-next-line
{"DT": "INVOICE", "DD": "IT-TEST", "DDto": "WSRLPXY",
"Ctm":
{"TaxId": "IT02348690211", "Nam": "The Buyercompany S.p.A", "Adr": "Via Roma 1",
// highlight-next-line
"Zip": "12345", "City": "Milano (MI)"
},
"PosA": {
"Pos": { "PN": "1", "Dsc": "test", "TaxG": "B", "Amt": "1.00"}},
"PayA": {
"Pay": { "Dsc": "Contanti", "PayG": "cash", "Amt": "1.00"}}
}
}
}
```
```xml
// highlight-next-line
// highlight-next-line
```
:::warning[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.
:::tip[Good to know]
For centralized administration configuration data can be set using the [efsta portal](https://portal.efsta.net), 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](rule-set#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
{
"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"
}
}
}
```
```xml
```
:::tip[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
{
"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"
}
```
```xml
32756
x64
12563
EFR
2.5.0
XY
true
online
XY123456789
0000000XXXX
def
0
0
0
0
2024-06-28T09:54:26+02:00
0.038301
1000
XY123456789
```
| 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
**Query & Body**
Query
| Name | Value | Example |
|------|------------------------------------------|---------|
| RN | Optional Register Number, default: 'def' | `1_1` |
Body
```json
{
"Badge": "XXXXXXXXXX" ,
"TaxId": "XX123456789",
"RN_TT": false
}
```
```xml
XXXXXXXXXX
XX123456789
false
```
**ENV-based EFR Profile Configuration (Advanced)**
The EFR Profile settings can be configured through environment (ENV) variables.
These settings are applied during system startup and, once active, block changes to the same configuration via the UI or API in order to avoid conflicts.
#### Structure
- Environment variables must follow this format where `__DOT__` is used as a separator between the different properties of the setting object:
`EFSTA_EFR_PROFILE_CFG__DOT__{RN}__DOT__{setting_name}={value}`
- If the structure is not respected, the setting will not be applied
- The RN must be defined so the system knows which register to apply the setting to
- On single-RN systems, def can be used instead of a specific RN
- Since some RNs may contain the `$` symbol, which is not supported in ENV variable names, use `__DOLLAR__` instead. The EFR automatically converts it back to `$`
- Boolean values must be lowercase (true, false)
**Example (using PL specific settings)**
```bash
EFSTA_EFR_PROFILE_CFG__DOT__def__DOT__RN_TT=true
EFSTA_EFR_PROFILE_CFG__DOT__001_1__DOT__Sign_require="FP_T88FVA"
EFSTA_EFR_PROFILE_CFG__DOT__001_1__DOT__Sign_Cfg="COM7:115200"
EFSTA_EFR_PROFILE_CFG__DOT__001_2__DOT__Sign_require="FP_T88FVA"
EFSTA_EFR_PROFILE_CFG__DOT__001_2__DOT__Sign_Cfg="COM5:115200"
EFSTA_EFR_PROFILE_CFG__DOT____DOLLAR__001_456__DOT__Sign_Cfg="COM5:115200"
```
#### Blocking of Settings
If a configuration is applied through ENV variables, it cannot be modified via the UI or API.
The API will return the following message if a blocked setting is changed: `Setting of {setting_name} for {RN} is blocked`
##### To re-enable UI/API configuration
- Remove the corresponding ENV variable(s)
- Restart the EFR
#### Querying ENV Settings
The EFR provides a way to query which settings have been applied through ENV variables. Use the following endpoint to view them:
> GET `/state`
:::note
This does not list all Profile settings, only those from ENV.
:::
**Example response (EnvSettings section highlighted)**
```json
{
"uptime": 162815,
"name": "EFR",
"version": "2.6.1.1",
"Country": "ZZ AT BE CZ DE DK ES FR HR HU IT LT NO PL PT SE SI SK",
"Online": false,
"Recorder": "inactive",
"RN": "def $001_456 001_1 001_2",
...
"EnvSettings": {
"def": {
"RN_TT": true
},
"001_1": {
"Sign_require": "FP_T88FVA",
"Foo": "Bar",
"Sign_Cfg": "COM7:115200"
},
"001_2": {
"Sign_require": "FP_T88FVA",
"Sign_Cfg": "COM5:115200"
},
"$001_456": {
"Sign_Cfg": "COM5:115200"
}
}
}
```
#### System Restart Triggers
If the following settings are applied via ENV variables, the EFR will automatically restart:
- HttpServer_Port
- UdpServer_Port
- DiskQuota
- Proxy
### Badge
This request can be used to set the `Badge` field in the EFR profile to connect the instance to the efsta Cloud.
**Locating the badge in the Portal**
The Badge can be found in the portal by following these steps:
1. Navigate to “Companies” on the left side menu
2. Open the properties of your company
3. Locate and copy the badge number
#### EFR Modes
The EFR service can be operated in different modes and depending on this, a different badge must be entered.
For more details, see [Architecture EFR Modes](/efr/architecture#efr-modes).
##### Single POS
For "Single POS" mode, the **company badge** should be used.
You can also specify the Transaction Location (TL) and Transaction Terminal (TT) within the badge. This means the POS identification is already known during activation, and a configuration can be automatically downloaded from the cloud. Additionally, a fiscal unit can be automatically assigned.
e.g: `AAAAAAAAAA.001/1`
:::tip[Good to know]
You can also specify an organization's badge and additionally the company's TaxID with TL/TT. This way, you know the badge before the rollout. e.g: `AAAAAAAAAA.DE123456789$001/1`
:::
##### Multi POS
For "Multi POS" mode, the **company badge** should be used. The RN_TT option must also be set to true for "Multi POS" to be used on the EFR service and TL/TT must be included with every request.
##### Multi Company
For "Multi Company" mode, the **badge of an organisation** must be used. The RN_TT option must also be set to true for "Multi Company" mode to be used on the EFR service and TaxId with TL/TT must be included with every request.
:::tip
For setting up new registers (RNs) up front, before any configuration or transaction, see the [Register Creation](/efr/api/business-cases#register-creation) business case.
:::
### Tax IDs for testing
In the following table are Tax IDs for testing for each country
| Flag | Country | Test Tax Id |
|:---------:|-----------|----------------|
| | Austria | ATU57780814 |
| | Belgium | BE0123456749 |
| | Czechia | CZ123456789 |
| | Germany | DE123456789 |
| | Denmark | DK99999993 |
| | Spain | ES123456789 |
| | France | FRXX999999998 |
| | Croatia | HR123456789 |
| | Hungary | HU123456789 |
| | Italy | IT123456789 |
| | Lithuania | LT123456789 |
| | Norway | NO999999999 |
| | Poland | PL9999999999 |
| | Portugal | PT999999990 |
| | Sweden | SE999999999901 |
| | 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` |
:::tip[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
{
"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"
}
}
```
```xml
[printer module name]
[printer serial]
1
true
false
2024-10-05T00:00:00
false
false
false
false
false
false
2028-10-05T00:00:00
```
| 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` |
---
source: https://docs.dev.efsta.eu/efr/api/business-cases
---
# Business Cases
:::tip[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 business cases, comprises of all transactional business cases that need to be implemented and tested with the EFR to comply with fiscalization requirements throughout Europe. Some business cases may not apply to your business. The current applicable countries to the business case is visible via the country flag beneath the business case title. If no flags are beneath the business case title, then this applies to all countries. By implementing all of these business cases and their variants, your system will be fiscalization ready in all of the current and future country solutions from efsta. efsta recommends that all business cases, if applicable, be implemented and sent to the EFR for every country, so that your system is future-proof when some countries expand their fiscalization requirements. This will prevent your development team from having to expand or re-develop to the EFR in the future.
If your business has any additional business cases that are not included on this list or if you have any comments or questions, please contact us at: [ticket@efsta.eu](mailto:ticket@efsta.eu)
## Register Creation
In **Multi POS** and **Multi Company** mode a register (subregister) can be created up front, before any configuration or transaction is sent. For more information on how to set up Multi POS and Multi Company systems (via the `RN_TT` flag), see [EFR Modes](/efr/api#multi-pos).
The register is created by sending a non-fiscal transaction marked with `NF="CREATERN"`, containing only the `TL` and `TT` values (and `TaxId` in Multi Company mode). As a non-fiscal transaction it requires no positions, operator or signature.
:::note
In Multi POS mode the register is identified by `TL/TT`; in Multi Company mode by `TaxId$TL/TT`. In single-register mode the request is recorded under the default `def` register.
:::
**Example**
```xml
// highlight-next-line
```
```json
{
"Tra": {
"ESR": {
// highlight-next-line
"NF": "CREATERN",
"TL": "001",
"TT": "1"
}
}
}
```
---
## Sale of Items
The EFR service calculates the tax amounts automatically, if they are not sent. However, we recommend that the POS sends the tax groups with every fiscal receipt. For a detailed explanation of tax assignment, see [Tax Group Assignment](/efr/api/rule-set#tax-group-assignment---taxg). For simplicity, the taxes are only given in one example and omitted from all other business cases.
:::tip
We recommand to use the predefined tax groups from efsta. Otherwise, various 0% tax rates cannot be represented and the default 0% tax group is used instead.
:::
:::note
A sale can also be labelled as "simplified invoice".
These are typically used for smaller transactions or when the buyer's identity is not required to be fully detailed, since the simplified invoice contains less information than a full invoice.
:::
**Thresholds for simplified invoices per country**
| Country | Threshold
(EUR) | Threshold
(local currency) |
| --------- | -------------------: | -------------------------: |
| Austria | 400 | |
| Belgium | 100 | |
| Croatia | 92 | HRK 700 |
| Czechia | 370 | CZK 10.000 |
| Denmark | 400 | DKK 3.000 |
| France | 100 | |
| Germany | 250 | |
| Hungary | 100 | |
| Italy | 400 | |
| Lithuania | 100 | |
| Poland | 100 | PLN 450 |
| Portugal | 100 | |
| Slovakia | 100 | |
| Slovenia | 100 | |
| Spain | 400 | |
| Sweden | 380 | SEK 4.000 |
### With TaxA
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "1",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"SKU": "654854",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"SKU": "845868",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"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"
}
]
}
}
}
```
```xml
```
### Without TaxA
If the tax array is omitted, the EFR service calculates the tax amounts automatically.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "1",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-1.62"
}
]
}
}
}
```
```xml
```
#### Country Specific Properties
| Properties | Description | Countries | Mandatory |
|-------------------|--------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------:|--------------------------|
| Pos.SKU | Stock Keeping Unit/article number |
[DE]
| If available in POS data |
| Pos.Cat, Pos.CatN | Category, Category name |
[DE]
[BE]
[DK]
[NO]
[SE]
| If available in POS data |
| Pos.IN | Article specific id. Used to track changes to an article's registration. |
[SE]
[BE]
| Yes |
| Pos.Resume | When a receipt was parked before all positions which are resumed need to be marked with Resume=1 |
[SE]
| Yes |
| Pos.TS | Article registration timestamp |
[SE]
| Yes |
| ESR.OprN | Operator Name |
[DE]
[DK]
[NO]
[PL]
[PT]
[SE]
| If available in POS data |
| ESR.TP | Transaction point |
[DE]
| If the transactions can be assigned to different areas
(e.g. table number) |
| ESR.OprTIN | Operator Tax Number (8-10 digits, read more below) |
[HR]
[SI]
| Yes |
| ESR.OprSSN | Operator Social Security Number (11 digits) |
[BE]
| Yes |
| ESR.ResumeFN | If a receipt was previously parked ([Parking of Receipts](/efr/api/country-specific#parking-of-receipts)) this property must be included and set to the fiscal number (FN) of the previously parked receipt |
[SE]
| Yes
*If a parked receipt is continued |
| ESR.TID | TSE Transaction ID |
[DE]
| See [Start Transaction](/efr/api/country-specific#start-transaction) |
| Pay.InputMethod | Input Method of the payment amount: `manual` or `auto` |
[BE]
| Yes |
| Pay.UID | Unique payment identifier; Electronic payment or document reference |
[DK]
| Mandatory for specific [Payment Groups](/efr/api/rule-set#payment-groups---paypayg) |
In Croatia and Slovenia there is a strict length check of the TIN value and if discrepancies are detected, the request will be rejected. These are the necessary value lengths (prefix not included):
* Croatia: 10 characters
* Slovenia: 8 characters
When the OprSSN is not valid (correct length and checksum), the transaction is rejected.
---
## Sale of Services
A sale of a service is sent as a position and is marked with an attribute `PTY="Svc`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "2",
"T": "34.90",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PTY": "Svc",
"PN": "1",
"IN": "1030",
"Dsc": "Example Service",
"TaxG": "A",
"Amt": "34.90"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "40.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-5.10"
}
]
}
}
}
```
```xml
```
---
## Discount
* Discounts are sent as a modifier element `Mod` with a negative amount `Mod.Amt`.
* Discounts must indicate which position numbers `Mod.PN` they refer to. Position number `*` means that the discount refers to all previous positions.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "3",
"T": "6.88",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Mod",
"PN": "1",
"Dsc": "Example line discount",
"Amt": "-0.50"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
},
{
"_": "Mod",
"PN": "*",
"Dsc": "Example receipt discount",
"Amt": "-1.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-3.12"
}
]
}
}
}
```
```xml
```
---
## Surcharge
* Surcharge are sent as a Modifier element `Mod` with a positive amount `Mod.Amt`
* Surcharge must indicate which position numbers `Mod.PN` they refer to. Position number `*` means that the surcharge refers to all previous positions.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "4",
"T": "4.48",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Mod",
"PN": "1",
"Dsc": "Example line surcharge",
"Amt": "0.50"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-5.52"
}
]
}
}
}
```
```xml
```
---
## Refund / Return of Goods
* Returns are sent with negative quantities `Pos.Qty` and negative amounts `Pos.Amt`.
* Discounts/Surcharges must also be taken into account when returning items
* Returns must reference the original transaction by `ESR.RFN` or `ESR.RTL` & `ESR.RTT` & `ESR.RTN`, see [country-specific properties](#country-specific-properties-for-refundsreturns)
**Example**
```json
{
"Tra": {
"ESR": {
"RD": "2024-06-01T08:10:15",
"RTL": "003",
"RTT": "2",
"RTN": "2080",
"RFN": "NY/Y07900042/0110/00002",
"Rsn": "V1",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "5",
"T": "-3.48",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "-3.98",
"Qty": "-2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Mod",
"PN": "1",
"Dsc": "Example line discount",
"Amt": "0.50"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "-3.48"
}
]
}
}
}
```
```xml
```
In Hungary the customer data is required for returns/voids. See Ctm object in example [invoice](#invoices)
#### Country Specific Properties for Refunds/Returns
| Properties | Description | Countries |
|-------------|--------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| ESR.RFN | Reference fiscal number |
[DK]
[BE]
[ES]
[FR]
[HU]
[IT]
[NO]
[PT]
[SE]
[SK]
**[SE]**: Only mandatory if the return is linked to the original receipt. |
| ESR.RD | Reference date |
[ES]
[HU]
[PT]
|
| ESR.RTL | Reference transaction location |
[DE]
[DK]
|
| ESR.RTT | Reference transaction terminal |
[DE]
[DK]
|
| ESR.RTN | Reference transaction number |
[DE]
[DK]
|
### Refunds in VERI\*FACTU and IGIC
#### General rules
- Every refund must reference an existing transaction that has already been sent to the EFR
- The original transaction is identified by the `RFN`
- Only one transaction is handled per refund
- The total amount must always be less than 0, except for full refunds of legacy transactions, where the total amount may also be 0
- `RD` (reference date) is only needed for legacy transactions, otherwise this information is directly taken from the journal
- The referenced transaction must still be valid (i.e. not voided and not already fully refunded)
:::warning
- To issue a factura rectificativa, the refund operation must be carried out on the same POS terminal where the original transaction was processed.
- Multiple invoices cannot be handled in one rectificativa
:::
**Example: Original transaction**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"T": "8.38",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item 1",
"TaxG": "F",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"SKU": "654854",
"Dsc": "Example Item 2",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"SKU": "845868",
"Dsc": "Example Item 3",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "8.38"
}
]
}
}
}
```
```xml
```
#### Further information
**Types of refunds**
A refund transaction can be either full or partial.
Full refund
- All original items are refunded
- Amounts and quantities are sent as negative values
- Discounts or surcharges applied in the original transaction must be reflected accordingly
**Example: Full refund**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"RTL": "003",
"RTT": "2",
"RTN": "2080",
"RFN": "2026.1-001-1-23",
"Rsn": "Full refund of items",
"TL": "001",
"TT": "11345",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item 1",
"TaxG": "F",
"Amt": "-3.98",
"Qty": "-2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"SKU": "654854",
"Dsc": "Example Item 2",
"TaxG": "B",
"Amt": "-1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "-5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"SKU": "845868",
"Dsc": "Example Item 3",
"TaxG": "A",
"Amt": "-2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "-8.38"
}
]
}
}
}
```
```xml
```
Partial refund
- Only a subset of the original items is refunded
- Only the refunded positions must be included
- Payment amount must match the refunded total
**Example: Partial refund**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"RTL": "003",
"RTT": "2",
"RTN": "2080",
"RFN": "2026.1-001-1-23",
"Rsn": "Partial refund of items",
"TL": "001",
"TT": "11345",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item 1",
"TaxG": "F",
"Amt": "-3.98",
"Qty": "-2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "-3.98"
}
]
}
}
}
```
```xml
```
**Specific reasons for refunding invoices**
Refunds for invoices can have specific reasons which can be passed trough the `ESR.Rsn` value to the EFR.
Customer declared insolvency
Specifying the refund reason to reflect that the customer declared insolvency can be done by setting the `ESR.Rsn` to `INSOLVENCY`.
Customer's debt is uncollectible
Specifying the refund reason to reflect that the customers debt cannot be collected can be done by setting the `ESR.Rsn` to `UNCOLLECTIBLE`.
**Validation errors**
Mismatching positions
- If the refund contains Pos elements that do not match the original transaction, the EFR will reject the refund
- The error message specifies the first non-matching position
**Example: Mismatching positions**
```json
{
"TraC": {
"Result": {
"RC": "BAD",
"ErrorCode": "#PARSE",
"Warning": [
"e-#PARSE #FORMAT referenced Pos not found or already refunded: {\"_\":\"Pos\",\"PN\":\"1\",\"Dsc\":\"Example Item\",\"Amt\":\"-399.00\",\"TaxG\":\"A\",\"QtyU\":\"Pc.\",\"Cat\":\"10\",\"CatN\":\"Example Category 10\"}"
]
}
}
}
```
Refunding a voided transaction
- If the original transaction has been previously voided, any refund attempt will fail
**Example: Refunding a voided transaction**
```json
{
"TraC": {
"Result": {
"RC": "BAD",
"ErrorCode": "#INVALID",
"Warning": [
"e-#INVALID Transaction has been previously voided"
]
}
}
}
```
**Refunds on legacy transactions**
Refunds for transactions recorded before VERI\*FACTU was introduced are handled differently.
Reference format
- Use the following format for RFN: `PRE-${YEAR}.${SERIES}-${TL}-${TT}-${COUNTER}`
- Example: `PRE-2026.1-001-1-1`
Special behavior
- When using the PRE- prefix and providing a reference date (RD): All matching and existence validations are disabled
- This is required because the original transaction is not present in the EFR journal
- If negative values are sent, the transaction is treated as a **partial refund**
- **Legacy refunds only**: To book a **full refund** for a legacy transaction, amounts and quantities of the Pos elements must be set to **0**
**Example: Full refund of a legacy transaction**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"RTL": "003",
"RTT": "2",
"RTN": "2080",
"RFN": "PRE-2026.1-001-1-23",
"RD": "2025-01-01T10:30:30",
"Rsn": "Full refund of items",
"TL": "001",
"TT": "11345",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item 1",
"TaxG": "F",
"Amt": "0.00",
"Qty": "0",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "0.00"
}
]
}
}
}
```
```xml
```
**Example: Partial refund of a legacy transaction**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"RTL": "003",
"RTT": "2",
"RTN": "2080",
"RFN": "PRE-2026.1-001-1-23",
"RD": "2025-01-01T10:30:30",
"Rsn": "Full refund of items",
"TL": "001",
"TT": "11345",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item 1",
"TaxG": "F",
"Amt": "-3.98",
"Qty": "-2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "-3.98"
}
]
}
}
}
```
```xml
```
---
## Void
* Voided transaction are marked with an attribute `Void="1"`
* The signs of quantity and amount must be sent reversed (negative values).
* Voids must reference the original transaction by `ESR.RFN` or `ESR.RTL` & `ESR.RTT` & `ESR.RTN`, see [country-specific properties](#country-specific-properties-for-void)
**Example**
```json
{
"Tra": {
"ESR": {
"Void": "1",
"RD": "2024-06-01T08:10:15",
"RTL": "003",
"RTT": "2",
"RTN": "125",
"RFN": "NY/Y07900042/0110/00002",
"Rsn": "V1",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "6",
"T": "-3.48",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "-3.98",
"Qty": "-2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Mod",
"PN": "1",
"Dsc": "Example line discount",
"Amt": "0.50"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "-3.48"
}
]
}
}
}
```
```xml
```
In Hungary the customer data is required for refunds/voids. See Ctm object in example [invoice](#invoices)
#### Country Specific Properties for Void
| Properties | Description | Countries |
|------------|----------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| ESR.RFN | Reference fiscal number (response from fiscal authority) |
[DK]
[BE]
[ES]
[FR]
[HU]
[IT]
[NO]
[PT]
[SE]
[SK]
**[SE]**: Only mandatory if the refund is linked to the original receipt |
| ESR.RD | Reference date |
[ES]
[HU]
[PT]
|
| ESR.RTL | Reference transaction location |
[DE]
[DK]
|
| ESR.RTT | Reference transaction terminal |
[DE]
[DK]
|
| ESR.RTN | Reference transaction number (associated transaction) |
[DE]
[DK]
|
| ESR.Rsn | Reason for cancellation/return |
[FR]
[HU]
[NO]
[PT]
|
---
## Line Void
* A voided position is marked with an attribute `Void="1"`
* The signs of quantity and amount for this position must be sent reversed (negative).
* `Pos.RPN` (Reference Position Number) can optionally be set to the `PN` of the original position being voided. This creates an explicit link and ensures unambiguous matching.
* When `Pos.RPN` is omitted, the EFR uses fallback matching: it searches backward through the positions for a match using item identity (`IN`, `ID`, `SKU`) and properties (`TaxG`, `Amt`, `Qty`, `Cat`, `CatN`, etc.). This may be ambiguous when multiple positions share the same item number or tax group.
:::tip
efsta recommends always providing `Pos.RPN` on line void positions when the POS system tracks position numbers. Explicit references prevent ambiguity and significantly improve matching accuracy — especially on tickets with repeated items.
:::
**Example: Line void**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "7",
"T": "6.88",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "-1.50",
"Cat": "11",
"CatN": "Example Category 11",
"Void": "1"
},
{
"_": "Pos",
"PN": "4",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-3.12"
}
]
}
}
}
```
```xml
```
**Example: Line void with RPN (explicit matching)**
The `Pos.RPN` attribute on the void position (`PN="3"`) explicitly references position `PN="2"`, unambiguously identifying which position is being voided.
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "7",
"T": "6.88",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1020",
"RPN": "2",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "-1.50",
"Cat": "11",
"CatN": "Example Category 11",
"Void": "1"
},
{
"_": "Pos",
"PN": "4",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-3.12"
}
]
}
}
}
```
```xml
```
#### Country Specific Properties for Line Void
| Properties | Description | Countries |
|---|---|---|
| Pos.RPN | Reference Position Number — the `PN` of the original position being voided. In Sweden, this directly drives article registration tracking; without it, the EFR uses multi-stage property fallback. | All countries (optional, strongly recommended) |
| Pos.Rsn | Reason for the line correction (e.g. `"Correction"`). When omitted, `"Correction"` is used as the default reason in the fiscal export. |
[DK]
|
---
## Z-Report / End of Day
A Z-report is a daily closure report that sums totals of different payment methods, returns, voids, etc. At the end of the day, the cash register needs to generate a daily closure and send the EFR a signal that the daily closure has been made. In some countries, the EFR then automatically generates additional information for Z-reports that are needed for the country specific audit exports.
A Z-report is marked with an attribute `NFS="Z"`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "8",
"NFS": "Z",
"Opr": "101",
"OprN": "Mario Rossi"
}
}
}
```
```xml
```
### X-Report
* An X-report includes the same information as a daily closure, but just reports the current totals of the day up until the time the X-report was created, it does not close the day. For protocoll purposes, when an X-report is made on the cash register, it should send the EFR a signal that it has been made.
* An X-report is marked with an attribute `NFS="X"`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "9",
"NFS": "X",
"Opr": "101",
"OprN": "Mario Rossi"
}
}
}
```
```xml
```
---
## Training
When a test/training receipt has been made, this must be documented for audit purposes.
A training receipt is marked with an attribute `NFS="TRAINING"`
:::note
When using fiscal printers, instead of `NFS="TRAINING"` the printer can be set in training mode.
:::
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "TRAINING",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "10",
"T": "6.88",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-3.12"
}
]
}
}
}
```
```xml
```
| Properties | Description | Countries |
|----------------|---------------------------|:------------:|
| ESR.FR_Trainer | Oprator ID of the trainer |
[FR]
|
---
## Vouchers / Gift Certificates
* Voucher purchase and voucher payment has to be sent as a position with a position type attribute `PTY="Vou"`
* A distinction is made between single-purpose vouchers (purpose of the voucher is known) and multi-purpose vouchers (purpose of the voucher is not known).
In Hungary and Slovakia it is not possible to mix voucher sales positions with normal sales positions.
#### Country Specific Properties for Vouchers
| Properties | Description | Countries |
|------------|----------------|:-------------------------:|
| Pos.VouN | voucher number |
[DE]
[SK]
|
### Multi-Purpose Vouchers
Multi-purpose vouchers are vouchers for businesses that sell products with different tax groups. This is the most common type of voucher / gift certificate business case. In this case, the tax of the products that will be purchased with the voucher are unknown, therefore tax is 0% at the voucher sale. The real tax needs to be charged when using the multi-purpose voucher as a payment method.
#### Multi-Purpose Voucher Sale
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "11",
"T": "103.98",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Vou",
"VouN": "123456789",
"PN": "2",
"IN": "1030",
"Dsc": "Example Voucher",
"TaxG": "E",
"Amt": "100.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "110.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-6.02"
}
]
}
}
}
```
```xml
```
#### Multi-Purpose Voucher Payment
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "12",
"T": "19.9",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "119.90",
"Qty": "1",
"QtyU": "Pc.",
"Pri": "119.90",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Vou",
"VouN": "123456789",
"PN": "2",
"IN": "1030",
"Dsc": "Example Voucher",
"TaxG": "E",
"Amt": "-100.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "20.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-0.10"
}
]
}
}
}
```
```xml
```
### Single-Purpose Vouchers
* For single-purpose vouchers, the tax rate must be specified by the voucher sale.
* On a single-purpose voucher payment, the item that is paid for must be referenced by `Pos.RPN`
#### Single-Purpose Voucher Sale
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "13",
"T": "103.98",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Vou",
"VouN": "123456789",
"PN": "2",
"RPN": "1",
"IN": "1030",
"Dsc": "Example Voucher",
"TaxG": "B",
"Amt": "100.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "110.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-6.02"
}
]
}
}
}
```
```xml
```
#### Voucher Payment
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "14",
"T": "19.90",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "119.90",
"Qty": "1",
"QtyU": "Pc.",
"Pri": "119.90",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Vou",
"VouN": "123456789",
"PN": "2",
"RPN": "1",
"IN": "1030",
"Dsc": "Example Voucher",
"TaxG": "B",
"Amt": "-100.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "20.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-0.10"
}
]
}
}
}
```
```xml
```
---
## Advance Payments
* Advance payments and resolutions are sent as a position and are marked with an attribute `PTY="Adv"`
* It is not allowed to make a discount on an advance payment line
### Advance Payment
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "15",
"T": "300.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PTY": "Adv",
"PN": "1",
"Dsc": "Example advance payment",
"TaxG": "A",
"Amt": "300.00",
"RDsc": "Example Item",
"RPri": "900.00",
"RQty": "1"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "creditcard",
"Amt": "300.00"
}
]
}
}
}
```
```xml
```
#### Country Specific Properties for Advance Payment Settings
| Properties | Description | Countries |
|------------|----------------------------------------------------------------------------|:-------------------------:|
| Pos.RDsc | Reference description of the item for which the advance payment is made |
[FR]
[PL]
|
| Pos.RPri | Reference price per item of the item for which the advance payment is made |
[FR]
[PL]
|
| Pos.RQty | Reference quantity of the item for which the advance payment is made |
[FR]
[PL]
|
### Advance Payment Resolution
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "16",
"T": "600.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"RFN": "4711",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "900.00",
"Qty": "100",
"QtyU": "Pc.",
"Pri": "9.00",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Adv",
"PN": "2",
"RPN": "1",
"Dsc": "Example advance payment resolution",
"TaxG": "A",
"Amt": "-300.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "creditcard",
"Amt": "600.00"
}
]
}
}
}
```
```xml
```
#### Country Specific Properties for Advance Payment Resolution
| Properties | Description | Countries |
|------------|------------------------------------------------------------------------------|:------------:|
| ESR.RFN | Reference fiscal number of the original advance payment |
[PL]
|
| Adv.RPN | Reference position number of the item for which the advance payment was made |
[PL]
|
---
## Bottle/Container Deposit
Bottle or container deposit legislation is any law that requires the collection of a monetary deposit on beverage containers at the point of sale. In many countries in Europe, this is a very common business case. Deposit sales and deposit return are sent as position and are marked with an attribute `PTY="Dep"`
In Poland, deposits need to be sent to the EFR with a 0% TaxG. Reason for this is that returns and sales of bottle deposits do not fall under VAT regulations in Poland.
### Deposit Sale
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "17",
"T": "24.30",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example bottled item",
"TaxG": "A",
"Amt": "19.80",
"Qty": "20",
"QtyU": "Pc.",
"Pri": "0.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Dep",
"PN": "2",
"IN": "1030",
"Dsc": "Example bottle deposit",
"TaxG": "A",
"Amt": "3.00",
"Qty": "20",
"Pri": "0.15"
},
{
"_": "Pos",
"PTY": "Dep",
"PN": "3",
"IN": "1030",
"Dsc": "Example box deposit",
"TaxG": "A",
"Amt": "1.50",
"Qty": "1",
"Pri": "1.50"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "debitcard",
"Amt": "24.30"
}
]
}
}
}
```
```xml
```
### Deposit Return
When the bottle is returned to the point of sale, then the entire sum is refunded.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "18",
"T": "-4.50",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PTY": "Dep",
"PN": "1",
"IN": "1030",
"Dsc": "Example bottle deposit",
"TaxG": "A",
"Amt": "-3.00",
"Qty": "-20",
"Pri": "0.15"
},
{
"_": "Pos",
"PTY": "Dep",
"PN": "2",
"IN": "1030",
"Dsc": "Example box deposit",
"TaxG": "A",
"Amt": "-1.50",
"Qty": "-1",
"Pri": "1.50"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "-4.50"
}
]
}
}
}
```
```xml
```
:::warning
Please check which tax group to use for bottle deposit in your country, some may require deposits to have 0% taxes
:::
In Hungary and Sweden, it is not possible to mix deposit return position with normal sales positions.
---
## Tip
Tips need to be reported in some countries and future legislation will require tips to be reported in most countries. Implementing the tips business case now will keep your point of sale future-proof.
* Tip is sent as position and is marked with an attribute `PTY="Tip"`
* Usually tip is considered 0% tax. Please consult with your tax advisor for your specific country and use case.
### Registering Tip Included in the Sale
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "18",
"T": "17.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "15.70",
"Qty": "1",
"QtyU": "Pc.",
"Pri": "15.70",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PTY": "Tip",
"PN": "2",
"Dsc": "Example Tip text",
"TaxG": "E",
"Amt": "1.30"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "20.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-3.00"
}
]
}
}
}
```
```xml
```
### Registering Tip after Finished Sale
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "20",
"T": "1.30",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"RFN": "001/1/20",
"PosA": [
{
"_": "Pos",
"PTY": "Tip",
"PN": "1",
"Dsc": "Example Tip text",
"TaxG": "E",
"Amt": "1.30"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "1.30"
}
]
}
}
}
```
```xml
```
#### Country Specific Properties for Tip after Sale
| Properties | Description | Countries |
|------------|------------------------------------------------------------------|:------------:|
| ESR.RFN | Reference fiscal number of the receipt for which the tip is paid |
[HR]
|
---
## Invoices
### Direct Invoice
A direct invoice:
* is issued when no receipt has been created beforehand
* serves as the sole fiscal document for the transaction
* is marked with `DT="INVOICE"`
* must contain customer data using `ESR.Ctm`
In Spain, **all data** concerning Ctm (like NIF/TaxID, Name, Postal Code, Address aso.) has to be included, otherwise there will be warnings.
In Belgium, direct invoices are only accepted in the form of E-Invoices. Any direct invoice not issued as an E-Invoice will be rejected.
**Example**
```json
{
"Tra": {
"ESR": {
"DT": "INVOICE",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "21",
"T": "399.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"Ctm": {
"CN": "12",
"Nam": "Example Name",
"Adr": "Example street 1",
"Zip": "10115",
"City": "Berlin",
"Ctry": "DE",
"TaxId": "DE123456789"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example Item",
"Amt": "399.00",
"TaxG": "A",
"Qty": "1",
"QtyU": "Pc.",
"Pri": "399.00",
"Cat": "10",
"CatN": "Example Category 10"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "creditcard",
"Amt": "399.00"
}
]
}
}
}
```
```xml
```
### Supplementary Invoice
A supplementary invoice:
* is issued in addition to a fiscal receipt that was already created for the same transaction
* does not count towards the Grand Total a second time
* is marked with `NFS="INVOICE"`
* must contain customer data using `ESR.Ctm`
In Spain, RFN and RD are mandatory for NFS invoices.
- In Belgium, ESR.DN and ESR.RFN are mandatory.
- Multiple previously issued VAT receipts can be referenced and combined into a single supplementary invoice. To do so, the individual FN values of the referenced VAT receipts must be joined using the pipe character `|`.
e.g.: `...`
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "INVOICE",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "22",
"T": "399.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"Ctm": {
"CN": "12",
"Nam": "Example Name",
"Adr": "Example street 1",
"Zip": "10115",
"City": "Berlin",
"Ctry": "DE",
"TaxId": "DE123456789"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example Item",
"Amt": "399.00",
"TaxG": "A",
"Qty": "1",
"QtyU": "Pc.",
"Pri": "399.00",
"Cat": "10",
"CatN": "Example Category 10"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "creditcard",
"Amt": "399.00"
}
]
}
}
}
```
```xml
```
### Invoice with Open Balance
If the invoice has not been paid, the paygroup must be set to "open" `PayG="open"`.
**Example**
```json
{
"Tra": {
"ESR": {
"DT": "INVOICE",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "23",
"T": "399.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"Ctm": {
"CN": "12",
"Nam": "Example Name",
"Adr": "Example street 1",
"Zip": "10115",
"City": "Berlin",
"Ctry": "DE",
"TaxId": "DE123456789"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example Item",
"Amt": "399.00",
"TaxG": "A",
"Qty": "1",
"QtyU": "Pc.",
"Pri": "399.00",
"Cat": "10",
"CatN": "Example Category 10"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "open",
"Amt": "399.00"
}
]
}
}
}
```
```xml
```
### Payment of the Open Balance on POS
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "PAY",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "24",
"T": "0.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "creditcard",
"Amt": "399.00"
},
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "open",
"Amt": "-399.00"
}
]
}
}
}
```
```xml
```
---
## Abort
The abort of a receipt before it is finished is marked with the attibute `NFS="ABORT"`
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "ABORT",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "25",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
]
}
}
}
```
```xml
```
---
## Order
An order is marked with the attibute `NFS="ORDER"`
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "ORDER",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "26",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
]
}
}
}
```
```xml
```
In Germany the Date/Time of the first order has to be printed on the fiscal receipt as D0.
e.g.: `...`
In Belgium, ESR.SvcPoint is mandatory. For more information, see [Country Specific Business Cases](/efr/api/country-specific#service-points)
---
## Payment Transactions
In Hungary it is mandatory to send a reason for payment transactions. This reason must be send as attribute ESR.Rsn e.g.: "Rsn="01". The reasons are descript in the country guide.
In Sweden, all of the Payment Transactions are mandatory!
### Opening Balance
The opening balance is marked with the attibute `NFS="INI"`.
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "INI",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "27",
"T": "500.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example opening balance",
"TaxG": "E",
"Amt": "500.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "cash",
"Amt": "500.00"
}
]
}
}
}
```
```xml
```
In Hungary, the opening balance starts the day. If no opening balance is sent, all subsequent transactions will be rejected.
### Deposit of Change
A deposit of change is marked with the attibute `NFS="TRANSFER"` and a positive amount.
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "TRANSFER",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "28",
"T": "500.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example transfer",
"TaxG": "E",
"Amt": "500.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "cash",
"Amt": "500.00"
}
]
}
}
}
```
```xml
```
### Daily Closure Cash Out
A daily closure cash out is marked with the attibute `NFS="TRANSFER"` and a negative amount.
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "TRANSFER",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "29",
"T": "-500.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example transfer",
"TaxG": "E",
"Amt": "-500.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "cash",
"Amt": "-500.00"
}
]
}
}
}
```
```xml
```
### Pay In
A pay in is marked with the attibute `NFS="PAY"` and a positive amount.
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "PAY",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "30",
"T": "500.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example pay in",
"TaxG": "E",
"Amt": "500.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "cash",
"Amt": "500.00"
}
]
}
}
}
```
```xml
```
### Pay Out
A pay out is marked with the attibute `NFS="PAY"` and a negative amount.
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "PAY",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "31",
"T": "-500.00",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Example pay out",
"TaxG": "E",
"Amt": "-500.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example payment",
"PayG": "cash",
"Amt": "-500.00"
}
]
}
}
}
```
```xml
```
---
## Reprints
[BE]
[DK]
[FR]
[NO]
[SE]
Only **one single copy** of a cash receipt is allowed!
* A reprint is marked with the attibute `NFS="DUP"` and a reference to the original receipt's `FN` as `RFN=[original-FN]` and `D` as `RD=[original date]`.
**Example**
```json
{
"Tra": {
"ESR": {
"NFS": "DUP",
"RD": "2024-06-01T08:10:15",
"RFiscal": "GMDTPAHXUWJ4DP77FGOFE3NUXPWO6ZG7;6TTZM3BYMSKOKVHF5VM6BZAUAA",
"RFN": "001/1/10",
"Rsn": "printing error",
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "32",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-1.62"
}
]
}
}
}
```
```xml
```
#### Country Specific Properties for Reprint
| Properties | Description | Countries |
|-------------|-------------------------------------------------|:----------------------------------------------------------------:|
| ESR.RFN | Reference fiscal number of the original receipt |
[DK]
[BE]
[FR]
[NO]
[SE]
|
| ESR.RD | Reference fiscal date of the original receipt |
[DK]
[SE]
|
| ESR.Rsn | Reason for cancellation/return |
[FR]
|
| ESR.RFiscal | Reference control code (Kontrollkod) |
[SE]
|
---
## Rounding
[BE]
[CZ]
[HU]
[IT]
[NO]
[SE]
[SK]
* Rounding on cash payments is sent as a payment with payment group "rounding" `PayG="rounding"`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "33",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Rounding",
"PayG": "rounding",
"Amt": "-0.02"
},
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-1.60"
}
]
}
}
}
```
```xml
```
---
## Paying with Foreign Currency
For payment in foreign currency, the currency code `CC`, the amount of the foreign currency `FAmt` and the amount in the country currency `Amt` must also be specified
In addition to the fields mentioned above, a third field `ConvR` (conversion rate) is required in Poland.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "34",
"T": "34.90",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1030",
"Dsc": "Example item",
"TaxG": "A",
"Amt": "34.90"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"FAmt": "40.00",
"CC": "USD",
"Amt": "37.40"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-2.50"
}
]
}
}
}
```
```xml
```
---
## Cashier Log In
A cashier log in is marked with the attibute `NFS="LOGIN"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "35",
"NFS": "LOGIN",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678"
}
}
}
```
```xml
```
---
## Cashier Log Out
A cashier log out is marked with the attibute `NFS="LOGOUT"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "36",
"NFS": "LOGOUT",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678"
}
}
}
```
```xml
```
---
## Proforma Invoice
A proforma invoice is marked with the attibute `NFS="PROFORMA"`.
:::note[Sweden]
In
[SE]
a proforma parks the transaction: it can be sent for a previously parked transaction and keeps it open under its own fiscal number - see [Parking of Receipts](/efr/api/country-specific#parking-of-receipts).
:::
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "37",
"T": "34.90",
"NFS": "PROFORMA",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1030",
"Dsc": "Example item",
"TaxG": "A",
"Amt": "34.90"
}
]
}
}
}
```
```xml
```
---
## Export/Audit Events
[BE]
[DK]
[FR]
[NO]
[SE]
In these countries, it is also mandatory to log events from the cash register via fiscalization.
The following events are covered by the business cases above:
* Cashier log in
* Cashier log out
* Reprints
* Z-report / daily closure
* X-report
Further events must be sent to the EFR service using audit records.
Export events are converted into audit codes internally, and vice versa.
**Example**
```json
{
"Audit": {
"Code": "DRAWER_OPEN",
"Dsc": "Drawer open",
"TL": "001",
"TT": "1",
"Opr": "1",
"OprN": "Operator name"
}
}
```
```xml
```
### List of Export / Audit Events
The following events must be sent to the EFR service using audit records:
| Code | Description | Country |
|-----------------|----------------------------------------------------------------------------------|:------------------------------------------------------------:|
| DRAWER_OPEN | Event to open the cash register outside of a sale |
[BE]
[DK]
[HU]
[LT]
[NO]
[PL]
[SE]
[SK]
|
| DRAWER_CLOSE | Event to close the cash register after it’s been opened |
[DK]
[NO]
[LT]
[HU]
[PL]
[SK]
|
| SUSPEND_RECEIPT | Event to put the sale on hold without conclusion (parking receipt) |
[DK]
[NO]
|
| RESUME_RECEIPT | Resuming a parked receipt to continue the sale |
[DK]
[NO]
|
| REPORT | Generation (creation) of a report other than an X- or Z-day report |
[DK]
[NO]
[SE]
|
| PRICE_CHANGE | Log time when prices are changed |
[DK]
[NO]
|
| PRICE_LOOKUP | Event for asking the register for a price query (e.g., scanning an item to get its price without registering it) |
[DK]
[NO]
[SE]
|
| TRAINING_ON | Event to report the start of a cashier training. This is just a report and does NOT change how the EFR treats the transactions following |
[DK]
[NO]
[SE]
|
| TRAINING_OFF | Event to report the register back to normal mode after being reported in training mode |
[DK]
[NO]
[SE]
|
| CLOCK_RESET | Event for setting or correcting the time on the register system |
[SE]
|
| MEM_FULL | Memory full (cash register) |
[DK]
[NO]
|
| EMERGENCY_ON | Report that the system has entered emergency operation due to a critical error, for example with the cash drawer or printer |
[DK]
[NO]
|
| EMERGENCY_OFF | Report that the system has exited emergency operation after the critical error has been resolved |
[DK]
[NO]
|
| ABORT | Cancellation of an unfinished receipt | |
| OTHER | Other event | |
---
## Non-fiscal Transaction without Printing
[FR]
[HU]
[IT]
[NO]
[PL]
[SE]
[SK]
A non-fiscal transaction that is registered in the EFR without triggering printing is marked with the `NF` or `NFS` field and the `DO="noprint"` attribute.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"NF": "DOC",
"DO": "noprint",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"SKU": "654854",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"SKU": "845868",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-1.62"
}
]
}
}
}
```
```xml
```
---
source: https://docs.dev.efsta.eu/efr/api/country-specific
---
# Country specific Business Cases
:::tip[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.
:::
These additional country specific business cases are rare, but if applicable to your business, need to be implemented and tested. The applicable country to the business case is visible via the country flag beneath the business case title.
If your business has any additional business cases that are not included on this list or if you have any comments or questions, please contact us at: [ticket@efsta.eu](mailto:ticket@efsta.eu)
## Start Transaction
Every business case must be started by sending a request with a `` Tag, as soon as the first article has been recorded. The response contains the fiscal TSE signature, the transaction ID (TID), and the timestamp of the process start.
At the completion of a transaction the whole transaction data has to be sent to the EFR within a `` Tag per /register request with the TID from the start request.
* A transaction will be startetd with `TraS` request. The TID from the response must be stored in the POS.
* The transaction will be finished with a `Tra` request and the TID has to be sent in the request.
**Example: Start request**
```json
{
"TraS": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1"
}
}
}
```
```xml
```
**Example: Response of start transaction**
```xml
```
```json
{
"TraSC": {
"SQ": "360",
"Result": {
"RC": "OK"
},
"Fis": {
// highlight-next-line
"TID": "292",
"StartD": "2024-06-01T08:30:02"
}
}
}
```
**Example: Transaction with TID**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "100",
"T": "34.90",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"TID": "292",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1030",
"Dsc": "Example Service",
"TaxG": "A",
"Amt": "34.90"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "40.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-5.10"
}
]
}
}
}
```
```xml
```
---
## Use of input devices (handheld device)
If a POS is used by input devices (handheld device), the input device ID must also be specified with the transaction.
The input device data can be maintained via the basis data in the portal.
The Device Id must be sent as an attribute `Pos.Dev`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "101",
"T": "34.90",
"Opr": "101",
"OprN": "Mario Rossi",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1030",
"Dsc": "Item 1",
"TaxG": "A",
"Amt": "34.90",
"Dev": "101"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "40.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-5.10"
}
]
}
}
}
```
```xml
```
---
## Invoices in the name of third parties
If amounts are recorded "on behalf of third parties", the third party is responsible for the correct recording of sales tax (e.g. shop-in-shop).
To do this, you can set the agency ID (DE_AGENTUR_ID) in the position. The agency data can be maintained in the basis data via the portal.
The agency ID Id has to be sent as an attribute `DE_AGENTUR_ID`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "102",
"T": "34.90",
"Opr": "101",
"OprN": "Mario Rossi",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1030",
"Dsc": "Item 1",
"TaxG": "A",
"Amt": "34.90",
"DE_AGENTUR_ID": "5"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "40.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-5.10"
}
]
}
}
}
```
```xml
```
---
## Private payment
### Private pay in
The business transaction type "private pay in" documents the pay in of cash from the
businessperson's private accounts into the cash register.
A private payment is marked with an attribute `NFS="CAPITAL"` and a positive amount.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "103",
"T": "200.00",
"Opr": "101",
"OprN": "Mario Rossi",
"NFS": "CAPITAL",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Private pay in",
"Amt": "200.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Cash",
"PayG": "0",
"Amt": "200.00"
}
]
}
}
}
```
```xml
```
### Private pay out
The business transaction type "private pay out" documents the taking of cash from the cash
register by the business owner for private purposes.
A private payment is marked with an attribute `NFS="CAPITAL"` and a negative amount.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "104",
"T": "-400.00",
"Opr": "101",
"OprN": "Mario Rossi",
"NFS": "CAPITAL",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Private removal",
"Amt": "-400.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Cash",
"PayG": "0",
"Amt": "-400.00"
}
]
}
}
}
```
```xml
```
---
## Variance analysis / difference
During the cash closure money count, the determination of the target/actual
difference takes place. Any difference must be sent to the EFR.
A variance analysis is marked with an attribute `NFS="DIFF"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "105",
"T": "-87.00",
"Opr": "101",
"OprN": "Mario Rossi",
"NFS": "DIFF",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "difference",
"Amt": "-87.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Cash",
"PayG": "0",
"Amt": "-87.00"
}
]
}
}
}
```
```xml
```
---
## Wage payment
[DE]
[HU]
A "wage payment" represents a (partial) payment of the wage from
the POS (e.g. wage advance) by the employer to the employee.
A wage payment is marked with an attribute `NFS="WAGE"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "106",
"T": "-1000.00",
"Opr": "101",
"OprN": "Mario Rossi",
"NFS": "WAGE",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "wage",
"Amt": "-1000.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Cash",
"PayG": "0",
"Amt": "-1000.00"
}
]
}
}
}
```
```xml
```
---
## Gastronomy consumption inhouse vs. take away
[DE]
[HU]
If food is not consumed in the restaurant but taken away, a lower tax rate applies. Therefore, this must be indicated for each position.
* The default value, if nothing is specified, is `InH="1"`
* If the food is taken away the position is marked with an attribute `InH="0"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "107",
"T": "9.90",
"Opr": "101",
"OprN": "Mario Rossi",
"TP": "Bar",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1030",
"Dsc": "Example item",
"TaxG": "B",
"Amt": "9.90",
"InH": "0"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-0.10"
}
]
}
}
}
```
```xml
```
---
## Delivery
[DE]
[DK]
[NO]
[SE]
### Delivery with an invoice afterwards
In this case the sales tax becomes due immediately upon delivery. The delivery note thus has an effect on sales.
A delivery with an invoice afterwards is marked with an attribute `DT="DELIVERY"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "108",
"T": "399.00",
"DT": "DELIVERY",
"Opr": "101",
"OprN": "Mario Rossi",
"TP": "Bar",
"Ctm": {
"CN": "12",
"Nam": "Musterfirma GmbH",
"Adr": "Musterstraße 1",
"Zip": "10115",
"City": "Berlin",
"Ctry": "DE",
"TaxId": "DE123456789"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Printer",
"TaxG": "A",
"Amt": "399.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Open",
"PayG": "8",
"Amt": "399.00"
}
]
}
}
}
```
```xml
```
The invoice afterwards is non fiscal and marked with an attribute `NFS="INVOICE"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "109",
"T": "399.00",
"NFS": "INVOICE",
"Opr": "101",
"OprN": "Mario Rossi",
"TP": "Bar",
"Ctm": {
"CN": "12",
"Nam": "Musterfirma GmbH",
"Adr": "Musterstraße 1",
"Zip": "10115",
"City": "Berlin",
"Ctry": "DE",
"TaxId": "DE123456789"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Drucker",
"TaxG": "A",
"Amt": "399.00"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Offen",
"PayG": "8",
"Amt": "399.00"
}
]
}
}
}
```
```xml
```
### Delivery note is generated on the POS and passed along to an external system (accounting)
In this case, the delivery note is only a non-fiscal (signed) transaction. The sales tax accrues in the external system.
In this case the delivery is marked with an attribute `NFS="DELIVERY"`.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "110",
"T": "399.00",
"NFS": "DELIVERY",
"Opr": "101",
"OprN": "Mario Rossi",
"TP": "Bar",
"Ctm": {
"CN": "12",
"Nam": "Musterfirma GmbH",
"Adr": "Musterstraße 1",
"Zip": "10115",
"City": "Berlin",
"Ctry": "DE",
"TaxId": "DE123456789"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Printer",
"TaxG": "A",
"Amt": "399.00"
}
]
}
}
}
```
```xml
```
---
## Tax of old parts (Altteilsteuer)
In the german fiscal law there is a special tax for old/used parts in the vehicle sector. The tax arises, if a
customer replace parts of a vehicle, the basis is the value of the new part. This tax is paid by the shop
or merchant and is listed separate on the bon for the customer.
The tax corresponds to the current full sales tax on the assessment basis, which is to be determined
according to § 10 Abs. 2 Satz 2 UStG. The assessment basis is an average value which is defined as
10% of the list price of the equivalent new part (without discounts and without sales tax).
This tax can be sent to the EFR-service with a position type PTY="TaxPos".
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "111",
"T": "1176.00",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "motor exchange",
"Amt": "1160.00",
"TaxG": "A"
},
{
"_": "Pos",
"PTY": "TaxPos",
"PN": "2",
"RPN": "1",
"Dsc": "tax for old parts",
"Amt": "16.00",
"TaxG": "A"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Cash",
"Amt": "1176.00",
"PayG": "Cash"
}
],
"TaxA": [
{
"_": "Tax",
"TaxG": "A",
"Prc": "16",
"Net": "1000.00",
"TAmt": "176.00",
"Amt": "1176.00"
}
]
}
}
}
```
```xml
```
---
## Difference tax rate (Differenzbesteuerung)
[AT]
[DE]
If a merchant bought used objects and sells them to his customers, a difference tax rate can be used
instead of the regular tax rate.
E.g.:
A merchant buys a used item at a price of €900. He then sells it to a private person for €1150. The tax
is calculated from the difference (sales price – purchase price), in this case €1150 - €900 = €250. The
tax amount would be €39.92 with a tax rate of 19%.
Since the tax is not printed directly on the receipt, this article is sent to the EFR as a 0% tax rate and a correction receipt has to be created afterwards.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "112",
"T": "1150.00",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Sell of used item",
"Amt": "1150.00",
"TaxG": "G"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Cash",
"Amt": "1150.00",
"PayG": "Cash"
}
],
"TaxA": [
{
"_": "Tax",
"TaxG": "G",
"Prc": "0",
"Net": "1150.00",
"TAmt": "0.00",
"Amt": "1150.00"
}
]
}
}
}
```
```xml
```
:::warning[Attention]
It must be written on the bon, that the tax rate of the article is differential tax rate
according to §25a UstG.
::::
A correction bon must be created afterwards, which includes the differential tax rate. This can also be
created in the accounting department and does not necessarily have to be sent to the EFR service.
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "113",
"T": "0.00",
"Opr": "101",
"OprN": "Mario Rossi",
"PosA": [
{
"_": "Pos",
"PN": "1",
"Dsc": "Korrektur",
"Amt": "-250.00",
"TaxG": "G"
},
{
"_": "Pos",
"PN": "2",
"Dsc": "Differenzbesteuerung",
"Amt": "250.00",
"TaxG": "A"
}
],
"TaxA": [
{
"_": "Tax",
"TaxG": "G",
"Prc": "0",
"Net": "-250.00",
"TAmt": "0.00",
"Amt": "-250.00"
},
{
"_": "Tax",
"TaxG": "A",
"Prc": "19",
"Net": "210.08",
"TAmt": "39.92",
"Amt": "250.00"
}
]
}
}
}
```
```xml
```
Alternatively, the correction of the tax can be made e.g. monthly in the accounting department via
internal receipt. Please coordinate this procedure with your tax advisor
---
## Consumption Tax
The Croatian consumption tax can be sent by specifying both the VAT group (A, B, ...) and the consumption group (V1) delimited with space in `Pos.TaxG="A V1"`. Additionally the `Tax`-line in the tax array is specified with:
* `Tax.TTY="CT"` TaxType is consumption tax
* `Tax.Base` is set with the tax base amount (net)
* `Tax.Net` and `Tax.TAmt` is not set
* `Tax.Amt` is set with the consumption tax amount instead of the gross amount
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"TN": "1",
"T": "8.38",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "12345678",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"SKU": "456487",
"Dsc": "Example Item",
"TaxG": "A V1",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"SKU": "654854",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"SKU": "845868",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "10.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-1.62"
}
],
"TaxA": [
{
"_": "Tax",
"TaxG": "A",
"Prc": "25",
"Net": "5.43",
"TAmt": "1.36",
"Amt": "6.79"
},
{
"_": "Tax",
"TaxG": "B",
"Prc": "13",
"Net": "1.33",
"TAmt": "0.17",
"Amt": "1.50"
},
{
"_": "Tax",
"TTY": "CT",
"TaxG": "V1",
"Prc": "3",
"Base": "3.11",
"Amt": "0.09"
}
]
}
}
}
```
```xml
```
## Article Registration & Changes
The export requires us to track detailed information about article registrations:
- Registration of an article
- Change to that registration:
- addition, subtraction or deletion
- Parking of a receipt (NFS="SUSPEND")
- Moving a parked article to another terminal
- Resuming a receipt, even if it is parked again
- update recipt and park again (addition, substraction or deletion)
- closing the parked recipt (sell or abort(NFS="ABORT"))
- Discounts are considered changes to the registered items
The EFR reconstructs this history from the position list of the transaction, and additionally reports the resulting articles sold per receipt.
**Example**
```xml
```
```json
{
"Tra": {
"ESR": {
"D": "2025-04-24T08:30:15",
"TL": "001",
"TT": "1",
"T": "3.46",
"Opr": "101",
"OprN": "Sofia Eriksson",
"OprTaxId": "xxx",
"PosA": [
// Cashier registers article with Qty of 2.
{
"_": "Pos",
"PN": "1",
"TS": "2025-04-24T08:30:15",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.98",
"Qty": "2",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category"
},
// Cashier registers a new article.
{
"_": "Pos",
"PN": "2",
"TS": "2025-04-24T08:30:22",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "9.95",
"Qty": "5",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2"
},
// Cashier changes the Qty of Product A with IN="1007", from 2 to 3.
{
"_": "Pos",
"PN": "3",
"TS": "2025-04-24T08:30:47",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.49",
"Qty": "1",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category"
},
// Cashier changes the Qty of Product B from 5 to 1 using a Line Void to remove 4.
{
"_": "Pos",
"PN": "4",
"TS": "2025-04-24T08:30:55",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "-7.96",
"Qty": "-4",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2",
"Void": "1"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "5.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-1.54"
}
]
}
}
}
```
## Parking of Receipts
Parking means a transaction is temporarily paused and not yet finalized. The parked transaction is picked up again later (possibly on another terminal) and is then either finalized as a receipt, parked once more, or aborted.
### Parking events change the state of the parking
A parking has a life cycle, and each step of it is a **state transition**: afterwards the register has something different open. The journal export records these transitions as events.
Closing is a **one-shot** transition: a parking can be closed once. After the closing receipt (or an abort) the parking is gone and its fiscal number can no longer be used as `ESR.ResumeFN`.
A parking is resumed with these properties:
| Property | Description | Mandatory |
| ------------ | ------------------- | ---------------------------------------- |
| ESR.ResumeFN | Fiscal number (FN) of the parked transaction that is picked up | Mandatory if a parked transaction is resumed |
| Pos.Resume | Already sent positions must be marked with Resume="1" | Mandatory if a position is resumed |
### The parking chain
Every step of a parking is a transaction of its own and gets its own fiscal number, taken from the number series of its transaction type (see [Fiscal Number (FN)](/efr/SE/fiscal#fiscal-number-fn)). All fiscal numbers of one chain share the same registration identifier (the leading `RegId` segment) so park, resume, re-park, proforma and the closing transaction stay linked as one parking in the journal export:
| Step | Request | Fiscal number returned |
| ---- | ------- | ---------------------- |
| Park | `NFS="SUSPEND"` | `CZ2AveV90Ip:PK:001/1/1-1` |
| Resume and park again | `NFS="SUSPEND"` with `ResumeFN="CZ2AveV90Ip:PK:001/1/1-1"` | `CZ2AveV90Ip:PK:001/1/1-2` |
| Proforma of the parked articles | `NFS="PROFORMA"` with `ResumeFN="CZ2AveV90Ip:PK:001/1/1-2"` | `CZ2AveV90Ip:PF:001/1/1-7` |
| Resume and finalize | `ResumeFN="CZ2AveV90Ip:PF:001/1/1-7"` | `CZ2AveV90Ip:SI:001/1/1-43` |
Every parking returns a **new** fiscal number. Always send back the FN of the **most recent** response of the chain as `ResumeFN` – not the FN of the first parking.
:::note[Resuming on another terminal]
A parked transaction may be resumed on a different terminal. Send the `TL`/`TT` of the terminal that picks it up together with the unchanged `ResumeFN`. The EFR detects the change and reports the parked articles as moved to the new terminal.
:::
### Examples
The examples below follow one chain: two articles are parked, the transaction is resumed and parked a second time with a third article added, and is finally resumed and paid.
**Example: Parking a transaction**
```xml
```
```json
// Parking a transaction
{
"Tra": {
"ESR": {
"NFS": "SUSPEND",
"D": "2025-04-24T08:30:15",
"TL": "001",
"TT": "1",
"T": "10.93",
"Opr": "101",
"OprN": "Sofia Eriksson",
"PosA": [
{
"_": "Pos",
"PN": "1",
"TS": "2025-04-24T08:30:15",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.98",
"Qty": "2",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category"
},
{
"_": "Pos",
"PN": "2",
"TS": "2025-04-24T08:30:22",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "9.95",
"Qty": "5",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2"
}
]
}
}
}
// Response: a parking is not signed - no Fis element is returned
{
"TraC": {
"SQ": 118,
"Result": {
"RC": "OK"
},
"ESR": {
"TN": "78",
"FN": "CZ2AveV90Ip:PK:001/1/1-1"
}
}
}
```
**Example: Resuming a parked transaction and parking it again**
```xml
```
```json
// Resuming the parked transaction and parking it a second time
{
"Tra": {
"ESR": {
"NFS": "SUSPEND",
// ResumeFN = FN found in the previous response.
"ResumeFN": "CZ2AveV90Ip:PK:001/1/1-1",
"D": "2025-04-24T08:33:27",
"TL": "001",
"TT": "1",
"T": "12.18",
"Opr": "101",
"OprN": "Sofia Eriksson",
"PosA": [
{
"_": "Pos",
"PN": "1",
"TS": "2025-04-24T08:30:15",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.98",
"Qty": "2",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category",
// Already parked articles are marked with Resume="1"
"Resume": "1"
},
{
"_": "Pos",
"PN": "2",
"TS": "2025-04-24T08:30:22",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "9.95",
"Qty": "5",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2",
"Resume": "1"
},
// A new article gets registered before the transaction is parked again
{
"_": "Pos",
"PN": "3",
"TS": "2025-04-24T08:33:27",
"IN": "5112",
"Dsc": "Product C",
"TaxG": "B",
"Amt": "1.25",
"Qty": "1",
"Pri": "1.25",
"Cat": "20",
"CatN": "Example Category 2"
}
]
}
}
}
// Response: a new FN of the PK series, with the RegId of the chain (again unsigned)
{
"TraC": {
"SQ": 126,
"Result": {
"RC": "OK"
},
"ESR": {
"TN": "79",
"FN": "CZ2AveV90Ip:PK:001/1/1-2"
}
}
}
```
**Example: Proforma of the parked articles**
A proforma is sent for the articles parked so far. Nothing is added or changed, so all positions are carried with `Resume="1"` and the transaction stays parked - now under the fiscal number of the proforma.
```xml
```
```json
// Proforma of the parked transaction
{
"Tra": {
"ESR": {
// highlight-next-line
"NFS": "PROFORMA",
// ResumeFN = FN found in the response of the LAST parking.
"ResumeFN": "CZ2AveV90Ip:PK:001/1/1-2",
"D": "2025-04-24T08:34:45",
"TL": "001",
"TT": "1",
"T": "12.18",
"Opr": "101",
"OprN": "Sofia Eriksson",
"PosA": [
// The parked articles are carried unchanged and marked with Resume="1"
{
"_": "Pos",
"PN": "1",
"TS": "2025-04-24T08:30:15",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.98",
"Qty": "2",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category",
"Resume": "1"
},
{
"_": "Pos",
"PN": "2",
"TS": "2025-04-24T08:30:22",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "9.95",
"Qty": "5",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2",
"Resume": "1"
},
{
"_": "Pos",
"PN": "3",
"TS": "2025-04-24T08:33:27",
"IN": "5112",
"Dsc": "Product C",
"TaxG": "B",
"Amt": "1.25",
"Qty": "1",
"Pri": "1.25",
"Cat": "20",
"CatN": "Example Category 2",
"Resume": "1"
}
]
}
}
}
// Response: a proforma IS signed - a new FN of the PF series and the Fis element are returned
{
"TraC": {
"SQ": 129,
"Result": {
"RC": "OK"
},
"ESR": {
"D": "2025-04-24T08:34:49",
"TN": "80",
// highlight-next-line
"FN": "CZ2AveV90Ip:PF:001/1/1-7"
},
"Fis": {
"Tags": [
{
"Label": "Kvittonr",
"Value": "7",
"Name": "FN"
},
{
"Label": "Kontrollsystemet tillverkningsnummer",
"Value": "ISTCSKSVERIFIKATI",
"Name": "SignDevId"
},
{
"Label": "Org. nr",
"Value": "373737-3737",
"Name": "OrgNr"
},
{
"Label": "Kassa",
"Value": "EF15KJTK11033101",
"Name": "RegisterId"
},
// highlight-next-line
{
"Label": "",
"Value": "Ej kvitto",
"Name": ""
}
]
}
}
}
```
**Example: Resuming a parked transaction and finalizing it**
```xml
```
```json
// Resuming and finishing the transaction
{
"Tra": {
"ESR": {
// ResumeFN = FN found in the response of the LAST step of the chain - here the proforma.
"ResumeFN": "CZ2AveV90Ip:PF:001/1/1-7",
"D": "2025-04-24T08:36:04",
"TL": "001",
"TT": "1",
"T": "11.69",
"Opr": "101",
"OprN": "Sofia Eriksson",
"OprTaxId": "xxx",
"PosA": [
{
"_": "Pos",
"PN": "1",
"TS": "2025-04-24T08:30:15",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.98",
"Qty": "2",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category",
// Already registered articles are marked with Resume="1"
"Resume": "1"
},
{
"_": "Pos",
"PN": "2",
"TS": "2025-04-24T08:30:22",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "9.95",
"Qty": "5",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2",
"Resume": "1"
},
{
"_": "Pos",
"PN": "3",
"TS": "2025-04-24T08:33:27",
"IN": "5112",
"Dsc": "Product C",
"TaxG": "B",
"Amt": "1.25",
"Qty": "1",
"Pri": "1.25",
"Cat": "20",
"CatN": "Example Category 2",
"Resume": "1"
},
// Qty of Product A is reduced to 1
{
"_": "Pos",
"PN": "4",
"TS": "2025-04-24T08:36:04",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "-0.49",
"Qty": "-1",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category",
"Void": "1"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"PayG": "cash",
"Amt": "20.00"
},
{
"_": "Pay",
"Dsc": "Example Change",
"PayG": "change",
"Amt": "-8.31"
}
]
}
}
}
// Response: the closing receipt keeps the RegId of the chain, its number comes from the SI series
{
"TraC": {
"SQ": 131,
"Result": {
"RC": "OK"
},
"ESR": {
"TN": "81",
"FN": "CZ2AveV90Ip:SI:001/1/1-43"
}
}
}
```
**Example: Aborting a parked transaction**
Instead of being finalized, a parked transaction can be discarded with `NFS="ABORT"`. All articles carried over from the parking are reported as deleted.
```xml
```
```json
{
"Tra": {
"ESR": {
"NFS": "ABORT",
"ResumeFN": "CZ2AveV90Ip:SI:001/1/1-43",
// highlight-next-line
"TL": "001",
"TT": "1",
"T": "12.18",
"Opr": "101",
"OprN": "Sofia Eriksson",
"PosA": [
{
"_": "Pos",
"PN": "1",
"TS": "2025-04-24T08:30:15",
"IN": "1007",
"Dsc": "Product A",
"TaxG": "A",
"Amt": "0.98",
"Qty": "2",
"Pri": "0.49",
"Cat": "10",
"CatN": "Example Category",
// highlight-next-line
"Resume": "1"
},
{
"_": "Pos",
"PN": "2",
"TS": "2025-04-24T08:30:22",
"IN": "3278",
"Dsc": "Product B",
"TaxG": "B",
"Amt": "9.95",
"Qty": "5",
"Pri": "1.99",
"Cat": "20",
"CatN": "Example Category 2",
// highlight-next-line
"Resume": "1"
},
{
"_": "Pos",
"PN": "3",
"TS": "2025-04-24T08:33:27",
"IN": "5112",
"Dsc": "Product C",
"TaxG": "B",
"Amt": "1.25",
"Qty": "1",
"Pri": "1.25",
"Cat": "20",
"CatN": "Example Category 2",
// highlight-next-line
"Resume": "1"
}
]
}
}
}
```
## Printing Periodic Reports
[LT]
[PL]
The **FP-T88FVA and FP-T88FVA Online printers** support generating periodic reports. Two types are available:
`PERIODIC_REPORT` — A fiscal periodic report aggregated from daily reports
`PERIODIC_SUM_REPORT` — A total summary periodic report
### Request Format
Reports are generated using this endpoint:
> POST `/register`
**Example: Periodic Fiscal Report**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"NFS": "PERIODIC_REPORT",
"Opr": "101",
"OprN": "Mario Rossi",
"FromD": "2025-08-04",
"TillD": "2025-08-05"
}
}
}
```
```xml
```
**Example: Periodic Summary Report**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"NFS": "PERIODIC_SUM_REPORT",
"Opr": "101",
"OprN": "Mario Rossi",
"FromD": "2025-08-04",
"TillD": "2025-08-05"
}
}
}
```
```xml
```
| Parameter | Description | Country |
|-----------|----------------------------------------------------|:-------------------------:|
| `NFS` | Specifies the report type |
[LT]
[PL]
|
| `FromD` | Defines the start of the date range for the report |
[LT]
[PL]
|
| `TillD` | Defines the end of the date range for the report |
[LT]
[PL]
|
#### Filtering by Z-Indexes
Both report types also support filtering based on Z-index ranges using `FromZI` and `ToZI`
**Example**
```json
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TL": "001",
"TT": "1",
"NFS": "PERIODIC_SUM_REPORT",
"Opr": "101",
"OprN": "Mario Rossi",
"FromZI": "1",
"ToZI": "2"
}
}
}
```
```xml
```
## Service Points
[BE]
Service points are used to specify where a service is booked to. They represent the location or context in which a service is provided, such as a table, room, or other point of service.
### SvcPoint, RSvcPoint
A Service Point defines the booking and accounting location.
For usage examples please check the business cases ORDER, SVC_POINT_TRANSFER, SVC_POINT_SPLIT further below.
| Property | Description | Note |
| ---------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id | Id of the Service Point | Examples: `T1`, `Table 1` |
| Type | Service Point Type | Possible Values:
`TABLE`
`CHAIR` \*
`ROOM`
`CUSTOMER`
`ON_HOLD`
`KIOSK`
`PLATFORM`
`WEBSHOP`
`OTHER`
\* Requires a [ParentSvcPoint](#svcpoint-parentsvcpoint) of Type `TABLE` |
| OperationId | Session of the Service Point | Groups all connected transactions. Sent to the FDM as cost center reference. Available from **EFR version 2.15.0**.
Example: `T2_601` |
| [ParentSvcPoint](#svcpoint-parentsvcpoint) | Parent Service Point | Mandatory when SvcPoint.Type `CHAIR` is used |
- PLATFORM should be used when orders are received from a linked third party online platform in the case where a signSale is not immediately created.
- WEBSHOP should be used when orders are received from an own linked webshop in the case where a signSale is not immediately created.
- OTHER should be used for any other way the POS uses to put orders aside. The OperationId can be filled with the value the POS uses internally to search for the orders or to bundle them.
#### (SvcPoint.) ParentSvcPoint
[Return to SvcPoint table](#parentsvcpoint)
| Property | Description | Note |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Id | Id of the parent Service Point | |
| Type | Type of the parent Service Point | `TABLE` |
| OperationId | Session of the parent Service Point | Groups all connected transactions. Sent to the FDM as cost center reference. Available from **EFR version 2.15.0**.
Example: `20240903_001` |
#### Examples
**Order booked on Table 1:**
```xml
```
```json
{
"SvcPoint": {
"Id": "Table 1",
"Type": "TABLE",
"OperationId": "20240903_001"
}
}
```
**Order booked on Chair 1 of Table 1:**
```xml
```
```json
{
"SvcPoint": {
"Id": "Chair 1",
"Type": "CHAIR",
"OperationId": "20240903_001_1",
"ParentSvcPoint": {
"Id": "Table 1",
"Type": "TABLE",
"OperationId": "20240903_001"
}
}
}
```
:::note
When SvcPoint.Type `CHAIR` is used it can only be done in combination with ParentSvcPoint.Type `TABLE`.
:::
### NFS="ORDER"
Supplying a SvcPoint is mandatory for the Order case.
All transactions resulting from a previous Order must include the same Service Point and OperationId.
**Example: Order to Table 1**
```xml
```
```json
{
"Tra": {
"ESR": {
"NFS": "ORDER",
"TL": "001",
"TT": "1",
"T": "8.40",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"SvcPoint": {
"Id": "Table 1",
"Type": "TABLE",
"OperationId": "20240903_001"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "4.00",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "2.00",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
]
}
}
}
```
**Example: Sale afterwards**
```xml
```
```json
{
"Tra": {
"ESR": {
"TL": "001",
"TT": "1",
"T": "8.40",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"SvcPoint": {
"Id": "Table 1",
"Type": "TABLE",
"OperationId": "20240903_001"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "4.00",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "2.00",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "2.90",
"Cat": "12",
"CatN": "Example Category 12"
}
],
"PayA": [
{
"_": "Pay",
"Dsc": "Example Payment",
"InputMethod": "manual",
"PayG": "cash",
"Amt": "8.40"
}
]
}
}
}
```
### NFS="SVC_POINT_TRANSFER"
For moving or merging positions from one or more service points to one target service point.
**Example: Moving Table 1 to Table 5**
```xml
```
```json
{
"Tra": {
"ESR": {
"NFS": "SVC_POINT_TRANSFER",
"TL": "001",
"TT": "1",
"T": "5.48",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"RSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
},
"SvcPoint": {
"Id": "T5",
"Type": "TABLE",
"OperationId": "20240903_005"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Test"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
}
]
}
}
}
```
**Example: Merging Table 1 and Table 35 to Table 5**
```xml
```
```json
{
"Tra": {
"ESR": {
"NFS": "SVC_POINT_TRANSFER",
"TL": "001",
"TT": "1",
"T": "5.48",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"SvcPoint": {
"Id": "T5",
"Type": "TABLE",
"OperationId": "20240903_005"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Test",
"RSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
}
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11",
"RSvcPoint": {
"Id": "T35",
"Type": "TABLE",
"OperationId": "20240903_035"
}
}
]
}
}
}
```
### NFS="SVC_POINT_SPLIT"
Splitting positions from one service point, onto one or more target service points.
**Example: Splitting of Table 1 to Table 5 and Table 35.**
```xml
```
```json
{
"Tra": {
"ESR": {
"NFS": "SVC_POINT_SPLIT",
"TL": "001",
"TT": "1",
"T": "5.48",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"RSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Test",
"SvcPoint": {
"Id": "T5",
"Type": "TABLE",
"OperationId": "20240903_005"
}
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11",
"SvcPoint": {
"Id": "T35",
"Type": "TABLE",
"OperationId": "20240903_035"
}
}
]
}
}
}
```
**Example: Splitting so each customer gets their own receipt**
#### Split table to Chair 1 and Chair 2
```xml
```
```json
{
"Tra": {
"ESR": {
"NFS": "SVC_POINT_SPLIT",
"TL": "001",
"TT": "1",
"T": "5.48",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"RSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Test",
"SvcPoint": {
"Id": "C1",
"Type": "CHAIR",
"OperationId": "20240903_001_1",
"ParentSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
}
}
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item",
"TaxG": "B",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11",
"SvcPoint": {
"Id": "C2",
"Type": "CHAIR",
"OperationId": "20240903_001_2",
"ParentSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
}
}
}
]
}
}
}
```
#### Receipt for Customer on Chair 1
```xml
```
```json
{
"Tra": {
"ESR": {
"TL": "001",
"TT": "1",
"T": "3.98",
"OprSSN": "00000000097",
"OprN": "Mario Rossi",
"SvcPoint": {
"Id": "C1",
"Type": "CHAIR",
"OperationId": "20240903_001_1",
"ParentSvcPoint": {
"Id": "T1",
"Type": "TABLE",
"OperationId": "20240903_001"
}
},
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item",
"TaxG": "A",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Test"
}
],
"PayA": [
{
"_": "Pay",
"PayG": "CreditCard",
"Dsc": "creditcard",
"InputMethod": "auto",
"Amt": "3.98"
}
]
}
}
}
```
---
source: https://docs.dev.efsta.eu/efr/api/rule-set
---
# EFR Rule Set
:::tip[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 ``. 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](/efr/api/rule-set#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](/efr/api/rule-set#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](/efr/api/additional-functions#attributes)):
`HttpServer_respond102=9000`
The value represents the interim response interval in ms.
:::tip[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:
```
#DUPLICATE
…
```
## 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.
Request is descript in EFR API [Cfg](/efr/api/#cfg---base-datacompany-header-data).
### Cmp - Company
| Name | Description | Mandatory | Example |
|--------------|-------------------------------------------------------------------------------------------------------------------|:-----------------:|-----------------|
| Nam | Company name | Yes | "My Company" |
| label | Company short name for digital receipt | Yes | "MyComp" |
| Adr | Company address | Yes | "Street" |
| AdrNr | Street number | Yes | "3" |
| Zip | Postcode | Yes | "1000" |
| City | City | Yes | "City" |
| Ctry | Country ISO-3166 | Yes | "XY" |
| TaxId | Intra community VAT identifier. Please configure the tax id in the profile | Yes | "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" |
| VatRegime | Issuer's own VAT regime. Allowed values: `GENERAL`, `SIMPLE`, `REDE`. Not available for IGIC (Canary Islands) - details see [Special VAT Regimes](/efr/ES/vat-regimes.md) |
[ES]
| "REDE" |
| 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 | Mandatory | Example |
|-------------|-------------------------------------------------------------|:-----------------:|--------------------|
| TL | Transaction Location code / store number | Yes | "001" |
| Nam | Location name | Yes | "My Location" |
| label | Location name Location short name for bill.efsta | Yes | "MyLoc" |
| Adr | Store address | Yes | "Long Road" |
| AdrNr | Street number | Yes | "123" |
| Zip | Postcode | Yes | "12345" |
| City | City | Yes | "Metropolis" |
| State | State/Region | | "XXX" |
| Ctry | Country ISO-3166 | Yes | "XY" |
| TaxId | Intra community VAT identifier |
[DE]
| "XY99999999999" |
| FR_SIR | SIRET / Geographic Identification of a French Establishment |
[FR]
| "732 829 320 0007" |
| LegalId | Establishment Unit Number |
[BE]
[CZ]
| "2000000042" |
### Trm - Terminal
| Name | Description | Mandatory | Example |
|---------------|------------------------------------------------------------------------------------------------------|:---------------------------------------------------:|----------------------------------|
| TT | Transaction Terminal code / number of cash register | Yes | "1" |
| SW | POS software name | Yes | "My POS Software" |
| SWVersion | Cash Register Software Version |
[BE]
[DE]
[FR]
[SE]
| "3.2.7"
"CFOD0031234568" |
| HW | Hardware brand | Yes | "POS Brand" |
| HWModel | Hardware model |
[DE]
[SE]
| "POS Model" |
| Serial | Cash Register Serial Number | Yes | "POS serial number" |
| Lang | The language of the Pos system, which has to match the receipt/cash register. (default: EN) |
[BE]
| 'en', 'de', 'fr', 'nl' |
| OprSSN | Fallback social security number of the POS operator when no number was supplied with the transaction | | |
### 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
Typically, input devices are handheld devices which serve as input for cash registers. This does not refer to explicit cash registers.
:::info
You can find more information on input devices in Germany in the [Use of Input Devices (Handheld Device)](/efr/api/country-specific#use-of-input-devices-handheld-device) section.
:::
| 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]
| "Device serial number" |
### DE_Agentur - Agency
:::info
These are third-party providers in whose name sales can be made on the POS system.
You can find more information on third-party invoices in Germany in the [Invoices in the Name of Third Parties](/efr/api/country-specific#invoices-in-the-name-of-third-parties) section.
:::
| 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.
Each group is used according to its structural purpose:
- [ESR](#esr-elements) → foundational
- [Ctm](#esr-ctm) → document-level context
- [Pos](#esrposa-pos) / [Mod](#esrposa-mod) / [Lin](#esrposa-lin) → product/line-item data
- [Pay](#esr-pay) → how the transaction is settled
- [Tax](#esr--tracfisz-tax) → fiscal tax calculation details
They are combined to form a complete, compliant fiscal dataset, with ESR elements defining the mandatory structure and Other elements allowing extensions where needed.
#### ESR Elements
ESR elements describe the core, standardized data fields that every EFR must produce according to the fiscalization specification. These elements are mandatory, strictly defined, and ensure legal compliance and interoperability across all environments.
| Attribute | Name | Description | Datatype | Mandatory |
|------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------|:-----------------------------------------------------------------:|
| ESR | efsta Simple Receipt | Receipt Body | | Mandatory |
| D | 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 / First order
*Example: "2016-08-01T13:28:22"* | DateTime |
[DE]
Default:
transaction
start time |
| TaxId | VAT Number | Important for centralized multi company multi client EFR installations with `RN_TT=true`
*Example: "DE123456789"* | Text | Optional |
| TL | Transaction Location | int. Branch ID / Business Premise / Store ID
Has to be unique within a company. Must be the same as the int. Branch ID of a location in the portal. 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]
*(Others: Recommended)* |
| OprN | Operator Name | Operator-Name | Text | |
| OprTIN | Operator Tax Identification | Operator Tax Identification
*Example: "79100590097"* | Text |
[HR]
[SI]
|
| 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]
*(Others: Recommended)* |
| DN | Document number | Sequential number;
Number range is of a specific document type DT, e.g. invoice number; additional to TN
*Example: "A23"* | Text | Mandatory |
| DD | Document Delivery | Sets the delivery method for this transaction. (see [E-Invoicing](/e_invoicing/api/general))
*Examples: "DE", "IT", "IT-FatturaPA"* | Text | Mandatory for E-Invocing |
| DDto | Document Delivery to | Unique Recipient of the E-Invoice. (see [E-Invoicing](/e_invoicing/api/general))
*Examples: "j.doe@efsta.eu", "VSRLPXY", "TMBLRT66T19A944Z"* | Text | Mandatory for E-Invocing |
| NF | Nonfiscal Transaction Type | This attribute denominates nonfiscal transaction. 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: an additional receipt listing only ATM transaction details* | Text | |
| NFS | Nonfiscal Signed | Equal to NF, but a fiscal signature is applied if required by law
*Examples: "Z", "TRAINING", "PAY", "LOGIN"/"LOGOUT", "PAYIN"/"PAYOUT"* | Text | Mandatory for non fiscal transactions |
| ResumeFN | | Reference FN to resume a parked transaction. Set it to the FN returned by the most recent parking of that receipt - re-parking a resumed receipt issues a new FN. See [Parking of Receipts](/efr/api/country-specific#parking-of-receipts) | |
[SE]
|
| DO | Document Output | This field controls document output for non-fiscal documents/transactions
*Example: "noprint"* | Text |
[BE]
[FR]
[HU]
[IT]
[NO]
[PL]
[SE]
[SK]
|
| 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 | Mandatory for void |
| Test | Test / Training Transaction | Training transactions are sent to the fiscal system marked as "test".
The Response `` element then contains a "\*\*\* TEST \*\*\*" info tag.
*Example: "1"* | Boolean
0/1 | Mandatory for test transactions |
| RD | Reference Date | Needed in some countries in case of return or void as reference to original sale | Text |
[ES]
[HU]
[PT]
[SE]
[SK]
|
| RTL | Reference Transaction Location | Needed in some countries in case of return or void as reference to original sale | Text |
[DE]
[DK]
|
| RTT | Reference Transaction Terminal | Needed in some countries in case of return or void as reference to original sale | Text |
[DE]
[DK]
|
| RTN | Reference Transaction Number | Needed in some countries in case of return or void as reference to original sale | Text |
[DE]
[DK]
|
| RFiscal | | Reference Fiscal Code | |
[SE]
|
| RFN | Reference Fiscal Number | Needed in some countries in case of return, void or invoice payment as reference to the original document | Text | Mandatory for Business Cases "return" and "void"
[CZ]
for `NFS="PAY"` |
| TP | Transaction Point | Point of transaction (e.g. table number, department)
*Example: "Tisch 5"* | Text | |
| Rsn | Reason | Reason text for exceptional transaction, position or modifier, e.g. reason for return of goods, reprint
*Example: "Erreur d'imprimante"* | Text |
[FR]
[HU]
[NO]
[PT]
Recommended for E-Invoicing:
[PL]
|
| OprSSN | Operator Social Security Number | Example Values: Technician: 00000000097; Robot-User (Kiosk, Online-Orders, ...): 00000000029 | Text |
[BE]
|
| Dev | Device ID | ID of the input device
(f.e.: Mac address) - Used if the input device is not the POS itself. | Text |
[BE]
[DE]
|
| DueDate | Due Date | Due date of payment. Only to be specified if it differs from terms of payment. Example: "2024-08-15" | DateTime |
[BE]
[DE]
[FR]
[IT]
|
| PaymentTerms | Payment Terms | Terms of the payment. Only to be specified if it differs from the terms of payment in the configuration. Example: "30 days net" | Text |
[BE]
[DE]
|
| [Delivery](#esr-delivery) | Delivery | Array of delivery elements | |
[BE]
[DE]
|
| OrderReference | Order Reference | The buyer's purchase order number (BT-13). Example: "PO-4711" | Text |
[BE]
[DE]
[FR]
|
| SellerOrderReference | Seller Order Reference | The seller's own order number for the same deal (BT-14), e.g. a hotel's reservation confirmation number. Not a substitute for OrderReference or Ctm.BuyerReference. Example: "CONF-123456" | Text |
[BE]
[DE]
[FR]
|
| ContractDocumentReference | Contract Reference | The contract the invoice refers to (BT-12). Example: "CT-2026-17" | Text |
[BE]
[DE]
[FR]
|
| ProjectReference | Project Reference | The project the invoice refers to (BT-11). Example: "PRJ-2026-01" | Text |
[BE]
[DE]
[FR]
|
| 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_SpecNamj | Additional Invoice Information | | Text |
[HR]
|
| VatRegime | Merchant VAT Regime | Issuer's own VAT regime for this transaction; overrides the company configuration. Allowed values: `GENERAL`, `SIMPLE`, `REDE`
details see [Special VAT Regimes](/efr/ES/vat-regimes.md) | Text |
[ES]
|
| SK_ParagonNumber | Paragon Number | Number of Paragon | Text |
[SK]
|
| [Ctm](#esr-ctm) | Customer | Customer data
Mandatory for invoices | | For invoices |
| [Head](#esr-head) | Header | Running text head for printing/digital receipt. | | |
| [PosA](#esrposa-pos) | Position
Array | Array of position lines ([Pos](#esrposa-pos), [Mod](#esrposa-mod), [Lin](#esrposa-lin)) | | Mandatory |
| [PayA](#esr-pay) | Payment Array | Array payment elements | | Mandatory |
| [TaxA](#esr--tracfisz-tax) | Tax Array | Array tax elements
Auto-generated if `ESR.PosA` is available | | Mandatory |
| Foot | Footer | Running text footer for printing/digital receipt. | | |
#### (ESR.) Delivery
[Return to ESR table](#delivery)
| Attribute | Description | Mandatory |
|-----------|----------------------------------------------------------------------------------------|:--------------------------------------:|
| D | The date on which the supply of goods or services was delivered. Example: "2024-07-08" |
[BE]
[DE]
[PL]
|
| Adr | The address where the delivery was made. |
[BE]
[DE]
|
| Adr2 | The address extension where the delivery was made. |
[BE]
[DE]
|
| City | The city where the delivery was made. |
[BE]
[DE]
|
| Zip | The postcode where the delivery was made. |
[BE]
[DE]
|
| Ctry | The country code where the delivery was made. |
[BE]
[DE]
|
#### (ESR.) Ctm
[Return to ESR table](#ctm)
Ctm elements describe transaction-level metadata (timestamps, identifiers, operation type) and define the overall context of the fiscal document.
| Attribute | Name | Description | Datatype | Mandatory |
|-------------------|-----------------|------------------------------------------------------------------|----------|:-------------------------------------------:|
| Nam | Name | Customer or company name | Text | All countries |
| Nam2 | Name 2 | Customer or company name extension | Text | |
| Adr | Address | Customer or company address within city | Text | All countries |
| Adr2 | Address 2 | Address extension | Text | |
| AdrNr | Address Number | Street number | Text | |
| Zip | Postal Code | Zip according to national rules without country prefix | Text | All countries |
| City | City | City name | Text | All countries |
| Ctry | Country | Country ISO 3166 ALPHA-2 (e.g. "DE") | Text | |
| TaxId | VAT Number | Customer or company VAT number including eventual country prefix | Text | For B2B |
| BuyerReference | Buyer Reference | An identifier assigned by the buyer used for internal routing purposes. An invoice must have buyer reference or purchase order reference (BT-13). | |
[BE]
[DE]
[FR]
|
| AccountingReference | Accounting Reference | The buyer's accounting reference for e-invoices (BT-19), e.g. a cost centre. Example: "KST-4711" | Text |
[BE]
[DE]
[FR]
|
| CN | Customer Number | Number of the customer | Text |
[DE]
|
| Cat | Category | Category of the customer/type of recipient (e.g. "employee") | 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]
|
#### (ESR.) Head
[Return to ESR table](#head)
| Attribute | Name | Description | Datatype |
|-------------------|-----------------|------------------------------------------------------------------|----------|
| Txt | Text | Text block for printing/digital receipt. | Text |
#### (ESR.PosA) Pos
[Return to PosA](#pos)
Pos elements define point-of-sale–related information such as workstation, cashier, or store references.
| Attribute| Name | Description | Datatype | Mandatory |
|-----------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------------------|:-----------------------------------------------:|
| PTY | Position Type | If not "Pos", e.g. "Mod"
accepted methods to set:
```"PosA":["\_":"Mod",…`
`"PosA":["PTY":"Mod",...`
*Examples: "Mod", "Dep", "Vou", "Adv", "Tip", "FoC"* | Text | Mandatory for some business cases |
| PN | Position
Number | Modifier positions `PTY="Mod"` may refer to multiple positions, e.g. `PN="*"`
*Examples:* `PN="1"`, `PN="*"` | Text | Mandatory |
| IN | Item
Number | Public article number
(GTIN, EAN, UPC) | Text |
[SE]
[BE]
*(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 | |
| PosG | Position Group | Position Group
Category of position as required in some countries - details see [PosG](#position-groups---posposg) | Text |
[LT]
|
| Note | Position Note | Individual position text
Replaces deprecated field `Pos.Info` | Text | |
| Void | Position Void / Line Void | Void of position within same receipt | Boolean
0/1 | Mandatory for line void |
| VouN | Voucher Number | Unique number of voucher | Text | |
| Dev | Device | ID of the input device. Details of the input device can be specified in the [configuration data](/efr/api/rule-set#dev---input-devices). | Text |
[DE]
if applicable |
| InH | inhouse | Inhouse consumption flag.
Default: "1" | Boolean
0/1 | |
| DE_AGENTUR_ID | Agency ID | ID of the agency. Only for third-party-invoices (shop-in-shop). Details of the agency can be specified in the [configuration data](/efr/api/rule-set#de_agentur---agency).
*Example: "123"* | Integer |
[DE]
if applicable |
| Cat | Category ID | ID of the Category | Text |
[DE]
[BE]
[DK]
[NO]
[SE]
if applicable |
| CatN | Category name | Name / description of the Category | Text |
[DE]
[BE]
[DK]
[NO]
[SE]
if applicable |
| RFN | Reference Fiscal Number | Needed in some countries in case of return or void as reference to original sale | Text |
[IT]
[SK]
|
| 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. | | |
| OrderLineReference | Order Line Reference | | |
[BE]
[DE]
|
| Rsn | Reason | Return reason for SAF-T export | Text |
[PT]
|
| Resume | | Parked positions which are resumed must be marked with Resume="1" | |
[SE]
|
| TS | | Timestamp of the article registration | |
[SE]
|
| SvcStartD | Service Period Start Date | Invoice line period start date: The date when the Invoice period for this Invoice line starts. Format ="YYYY-MM-DD"
*Example in E-Invoicing: if(pos\.SvcStartD \|\| pos\.SvcEndD) rv\.cac$InvoicePeriod = \{cbc$StartDate:\_Date(pos\.SvcStartD), cbc$EndDate:\_Date(pos\.SvcEndD)\}* | DateTime | For E-Invoicing |
| SvcEndD | Service Period End Date | Invoice line period end date: The date when the Invoice period for this Invoice line ends. Format ="YYYY-MM-DD"
*Example in E-Invoicing: if(pos\.SvcStartD \|\| pos\.SvcEndD) rv\.cac$InvoicePeriod = \{cbc$StartDate:\_Date(pos\.SvcStartD), cbc$EndDate:\_Date(pos\.SvcEndD)\}* | DateTime | For E-Invoicing |
| 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]
|
| VatRegime | Merchant VAT Regime | Issuer's own VAT regime for this position; overrides the transaction and company level. Allowed values: `GENERAL`, `SIMPLE`, `REDE`
details see [Special VAT Regimes](/efr/ES/vat-regimes.md) | Text |
[ES]
|
| 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]
|
*\*Reference attributes only for void/reversal or return-of-good positions (usually in combination with negative Qty)*
#### (ESR.PosA.) Mod
[Return to PosA](#pos)
Mod elements represent document-level modifications (e.g., corrections, references, voids).
| Attribute | Name | Description | Datatype | Mandatory |
|-----------|-----------------------|---------------------------------------------------------------------------------------------|----------|:----------------------------------------------------:|
| 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 | Mandatory
Default:
previous position |
| Dsc | Description | Description to be printed | Text |
[DE]
*(Others: Recommended)* |
| Prc | Percent | Rebate percentage for printing
*Example: "10", "10%"* | Text | |
| Cat | Category | Discount code
To be used in reports
*Example: "DISC002"* | Text | |
| Amt | Modifier
Amount | Amount
Negative: rebate or discount
Positive: markup
*Example: "\-50.00"* | Currency | Mandatory |
#### (ESR.PosA.) Lin
[Return to PosA](#pos)
Lin elements describe individual receipt line items, including quantities, prices, product details, and line-level attributes.
In Poland, Lin elements are only supported on non-fiscal elements, but not on fiscal printouts.
| Attribute | Name | Description | Datatype |
|-----------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| 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 |
#### (ESR.) Pay
[Return to ESR table](#pay)
Pay elements cover all payment-related information such as payment types, amounts, references, and mixed-payment scenarios.
| Attribute | Name | Description | Datatype | Mandatory |
|-------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------|
| Dsc | Description | Denomination of payment method
*Example: "Cash"* | Text | Yes |
| Amt | Payment
Amount | Amount paid
*Example: "735.00"* | Currency | Yes |
| UID | Unique
Identifier | Unique payment identifier
Electronic payment or document reference | Text |
[DK]
|
| 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](/efr/api/rule-set#payment-groups---paypayg)) | Text | Yes |
| 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 | |
| ConvR | Conversion Rate | Conversion rate from foreign currency to local currency used for foreign currency payments
*Example: "0.9350"*
| Decimal |
[PL]
|
| InputMethod | Payment Input Method | Manual or automatic input of the payment amount `manual` or `auto` | |
[BE]
|
#### (ESR.) / (TraC.Fis.Z) Tax
[Return to ESR table](#tax)
:::note
This ESR.Tax and the [TraC.Fis.Z.ZTax](#tracfisz--esr-ztax) elements are identical, however the [TraC.Z.ZTax](#tracz-ztax) element has a few distinctions.
:::
Tax elements define the tax breakdown and the mapping of the transaction’s tax logic to fiscalized output.
| Attribute | Name | Description | Datatype | Mandatory |
|-----------|---------------|---------------------------------------------------|----------|-----------|
| 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 |
| TTY | Tax Type | Marks a non-VAT tax element. For these, `Base` and `Amt` are set instead of `Net`/`TAmt`, and `Amt` carries the tax amount.
`"CT"` consumption tax ([HR](/efr/api/country-specific#consumption-tax))
`"SVAT"` equivalence surcharge ([ES](/efr/ES/vat-regimes.md)) | Text |
[HR]
[ES]
|
| Base | Tax Base | Base amount the tax is calculated on; only with `TTY`
*Example: "3.96"* | Currency |
[HR]
[ES]
|
:::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](#trac-result) | Registration Result | Result of a registration | | | |
| [Fis](#trac-fis) | Fiscal Data | Fiscal Signature | | | |
| [Z](#trac-z) | Z Data | End of day data of fiscal device | |
[IT]
[PL]
| |
#### (TraC.) Result
[Return to TraC table](#res)
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| 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[] | | |
:::note
- Main program flow is controlled by ResultCode RC
- `` may contain additional information
- `` 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.
:::
#### (TraC.) Fis
[Return to TraC table](#fis)
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| D | Date Time | Date and time of fiscal device | DateTime |
[IT]
[PL]
[SK]
| |
| FN | Fiscal Number | Fiscal number created by fiscal device | Text |
[ES]
[IT]
[PL]
[SK]
| |
| DN | Document Number | Receipt number created by fiscal device | Integer |
[IT]
[SK]
| |
| [Z](#tracfis-z) | Z Data | End of day data of fiscal device | |
[BE]
| |
| 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]
[ES]
| |
| Link | Link | efsta link for printing instead of QR code | Text |
[AT]
| |
| Payload | | Signature Payload | Text |
[FR]
| |
| Signature | | Signature | Text |
[FR]
| |
| ES_TBAI_Code | Identificador TBAI | TicketBAI system Id for that specific transaction | String |
[ES]
| "`TBAI-46886417C-310725-2ESuO3BEl0l1U-222`" |
| [Tag](#tracfis-tag) | Fiscal Tag | Fiscal text
To be printed on the sales slip according to fiscal regulation | | | |
#### (TraC.Fis.) Tag
[Return to Fis table](#tag)
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| 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" |
#### (TraC.Fis.) Z
[Return to Fis table](#fisz)
:::note
This section is about TraC.Fis.Z - for information on TraC.Z, go to [TraC.Z](#trac-z).
:::
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| ZI | Z Index | Report Number | Integer |
[BE]
| |
| T | Z total | Total amount for normal sales transactions | Currency |
[BE]
| |
| DrawerOpenCnt | Drawer Open Count | Total count of drawer openings outside of a sale | Integer |
[BE]
| |
| CreditAmt | Credit Amount | Total amount of returns and voids | Currency |
[BE]
| |
| CreditCnt | Credit Count | Total count of returns and voids | Integer |
[BE]
| |
| DiscountCnt | Discount Count | Total discount count | Integer |
[BE]
| |
| DiscountAmt | Discount Amount | Total discount amount | Currency |
[BE]
| |
| SurchargeCnt | Surcharge Count | Total surcharge count | Integer |
[BE]
| |
| SurchargeAmt | Surcharge Amount | Total surcharge amount | Currency |
[BE]
| |
| ZPeriod | Z Period | Booking date of the report | Date |
[BE]
| |
| TSDayOpen | Timestamp Day Open | Timestamp of the days opening | Datetime |
[BE]
| |
| TSDayClose | Timestamp Day Close | Timestamp of the days closing | Datetime |
[BE]
| |
| [ZFisUnitA](#tracfisz-zfisunit) | Z Fis Unit Array | Array of FDM devices used in the reporting period | *ZFisUnit* |
[BE]
| |
| [ZFisTraA](#tracfisz-zfistra) | Z Fis Transaction Array | Array of totals per transaction type (Label) | *ZFisTra* |
[BE]
| |
| [ZCatA](#tracfisz-zcat) | Z Category Array | Array of totals per category | *ZCat* |
[BE]
| |
| [ZPayA](#tracfisz-zpay) | Z Payment Array | Array of totals amounts per payment method | *ZPay* |
[BE]
| |
| [ZCreditRsnA](#tracfisz-zcreditrsn) | Z Credit Reason Array | Array of totals per negative quantity reason | *ZCreditRsn* |
[BE]
| |
| ZTaxA | Z Tax Array | Tax totals per tax group. | *ZTax* |
[BE]
| |
| [ZOprA](#tracfisz-zopr) | Z Operator Array | Array of Operator statistics for the reporting period | *ZOpr* |
[BE]
| |
#### (TraC.Fis.Z.) ZFisUnit
[Return to Fis.Z table](#unit)
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| ID | Identification | FDM ID | Text |
[BE]
| "FDM12345678" |
| TSFirst | Timestamp First | Timestamp of the first registered event | Datetime |
[BE]
| |
| TSLast | Timestamp Last | Timestamp of the last registered event | Datetime |
[BE]
| |
| FirstNum | First Number | Total counter snapshot at the first registered event | Integer |
[BE]
| |
| LastNum | Last Number | Total counter snapshot at the last registered event | Integer |
[BE]
| |
#### (TraC.Fis.Z.) ZFisTra
[Return to Fis.Z table](#tra)
| Element | Name | Description | Datatype | Countries |
|-------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|
| Dsc | Description | Transaction Label (Example: 'N' for normal) | Text |
[BE]
|
| Cnt | Count | Transaction count | Integer |
[BE]
|
| Amt | Amount | Total amount for this transaction type | Currency |
[BE]
|
#### (TraC.Fis.Z.) ZCat
[Return to Fis.Z table](#cat)
| Element | Name | Description | Datatype | Countries |
|-------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|
| Cat | Category Number | ID of the Category | Text |
[BE]
|
| CatN | Category Name | Name / description of the Category | Text |
[BE]
|
| Net | Net Amount | Total Net Amount (excl. Tax) | Currency |
[BE]
|
| TAmt | Tax Amount | Total tax amount | Currency |
[BE]
|
| Amt | Amount | Total amount | Currency |
[BE]
|
#### (TraC.Fis.Z.) ZPay
[Return to Fis.Z table](#zpay)
| Element | Name | Description | Datatype | Countries |
|-------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|
| Dsc | Description | Payment type | Text |
[BE]
|
| Amt | Amount | Total for amount | Currency |
[BE]
|
#### (TraC.Fis.Z.) ZCreditRsn
[Return to Fis.Z table](#cdtrsn)
| Element | Name | Description | Datatype | Countries |
|-------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|
| Amt | Amount | Total amount | Currency |
[BE]
|
| Cnt | Count | | Integer |
[BE]
|
| Rsn | Reason | | Text |
[BE]
|
| TraCnt | Transaction Count | | Text |
[BE]
|
#### (TraC.Fis.Z) / (ESR.) ZTax
[Return to Fis.Z table](#fisz-tax)
:::note
This TraC.Fis.Z.ZTax and the ESR.Tax elements are identical, however the [TraC.Z.ZTax](#tracz-ztax) element has a few distinctions.
For more information on this, go to [(ESR.) Tax](#esr--tracfisz-tax).
:::
#### (TraC.Fis.Z.) ZOpr
[Return to Fis.Z table](#opr)
| Element | Name | Description | Datatype | Countries |
|---------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|
| Amt | Amount | Total amount for transactions of type normal | Currency |
[BE]
|
| OprSSN | Operator Social Security Number | Example Values: Technician: 00000000097; Robot-User (Kiosk, Online-Orders, ...): 00000000029 | Text |
[BE]
|
| TSFirst | Timestmp First | Timestamp of the first transaction | Datetime |
[BE]
|
| TSLast | Timestamp Last | Timestamp of the last transaction | Datetime |
[BE]
|
| [ZAuditA](#tracfiszzopr-zaudit) | Z Audit Array | Array of clockin and clockout events for this cashier | *ZAudit* |
[BE]
|
#### (TraC.Fis.Z.ZOpr) ZAudit
[Return to ZOpr table](#tracfisz-zopr)
| Element | Name | Description | Datatype | Countries |
|-------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|
| Code | Event Code | CLOCKIN or CLOCKOUT | Text |
[BE]
|
| TS | Timestamp | Timestamp of the event | Datetime |
[BE]
|
#### (TraC.) Z
[Return to TraC table](#z)
:::note
This section is about TraC.Z - for information on TraC.Fis.Z, go to [TraC.Fis.Z](#tracfis-z).
:::
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| 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](#tracz-ztax) | Z Tax Data | End of Day Tax Data of fiscal device | |
[IT]
[PL]
| |
#### (TraC.Z.) ZTax
[Return to Z table](#ztax)
:::note
This section is about TraC.Z.ZTax - for information on ESR.Tax / TraC.Fis.Z.ZTax, go to [ESR.Tax / TraC.Fis.Z.ZTax](#esr--tracfisz-tax).
:::
| Element | Name | Description | Datatype | Countries | Example |
|-------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------|:-------------------------:|---------------------------------------------|
| 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]
| |
## 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
\- unique transfer ID Pay.UID | |
| 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 | |
| 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.
:::tip
We recommand to use the method 1 or method 3 with the predefined tax groups from efsta. Otherwise, various 0% tax rates cannot be represented and the default 0% tax group is used instead.
:::
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:
```
```
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:
```
```
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:
```
```
## Position Groups - Pos.PosG
In some countries, certain groups/categories of positions have to be specified per position line for the fiscal printer or subsequent export. You can use the following efsta constants for all countries, which then are translated accordingly:
| efsta PosG | Description | Countries |
|------------|----------------------------|--------------|
| alcohol | Alcoholic items |
[LT]
|
| gasoline | Gasoline |
[LT]
|
## 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:
```xml
```
Response
```xml
...
```
## 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, so the format of the field varies. It is the main denominator / fiscal ID which it is handled by the EFR to ensure gapless and constant chaining of receipts. FN has to be printed on the document and stored on POS side with each transaction, although it is not possible to be sent from the POS system directly.
:::tip[Good to know]
In some countries, TL/TT/TN is used as unique transaction identifier, no separate FN exists (e.g. in [AT]).
For the format used in Sweden see [Fiscal Number (FN)](/efr/SE/fiscal#fiscal-number-fn).
:::
#### 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`
:::
:::tip[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 |
| /rn/def/report |
[BE]
X and Z Report files |
## 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
:::tip[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 version 2.3.4*
Means major: 2, minor: 3, hotfix: 4
| Part | e.g. | Description |
|-------------------------|------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| Major | 2 | - A new major version may introduce changes to the program API. Although broad interface compatibility is intended, new functions or legal requirements may result in minor changes. Refer to the [country-specific changelogs](https://public.efsta.net/efr/) for details.
**- Testing on software partner's side is required.** |
| Minor | 3 | - A new sprint contains bugfixes and new features.
**- General testing is recommended.** |
| Hotfix
(optional) | 4 | - Like a minor version, a hotfix contains bugfixes and may also include legally required new features. It is released on demand for one or more countries.
**- General testing is recommended.** |
| Appendix
(optional) | B | - Used for preview versions. |
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 ).
---
source: https://docs.dev.efsta.eu/efr
---
# efsta System
The efsta system serves as middleware to fulfill country specific fiscal requirements for POS systems using a unified interface. The cash register application submits standardized transaction data to the EFR (Electronic Fiscal Register), which handles the data according to the country specific fiscal regulations.
## Two ways to deploy
## Key Features
- Automated reporting/communication with fiscal authorities
- Fiscal signature/response
- Offline fiscal buffering and archiving
- Encrypting and chaining transaction data to prevent manipulation (audit-proof)
- Controlling and communicating with different cloud and hardware based fiscal devices
- Gateway to the efsta Cloud for archiving and exports
- Maintenance, updates and administration via the efsta Portal for managing your efsta system and fiscal compliance
## Add-on Features
- Digital Receipt (efsta Simple and Smart Bill)
- E-invoicing compliance (B2B and/or B2G): currently in Italy and Germany
- 3rd party integrations: DATEV (DE)
## Available Countries
| | | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **AT** | **BE** | **CZ** | **DE** | **DK** | **ES** | **FR** | **HR** | **HU** |
| **Austria** | **Belgium** | **Czechia** | **Germany** | **Denmark** | **Spain** | **France** | **Croatia** | **Hungary** |
| | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **IT** | **LT** | **NO** | **PL** | **PT** | **SE** | **SI** | **SK** |
| **Italy** | **Lithuania** | **Norway** | **Poland** | **Portugal** | **Sweden** | **Slovenia** | **Slovakia** |
---
source: https://docs.dev.efsta.eu/efr/architecture
---
# EFR Architecture
## Introduction
The efsta middleware electronic fiscal register (EFR) is a software to fulfill the country specific requirements for fiscalization.
The software receives (transaction) data via REST interface from any upstreaming system (POS, ERP, PMS).
As those upstreaming systems have various architectures, EFR can be adjusted to the customer-specific architecture.
After receiving a transaction, it gets forwarded to a fiscal device – in those countries where it is required – or processed internally.
efsta also provides a cloud archive – called efsta Cloud – where the fiscalized data gets stored encrypted after the fiscalization process is done.
## Architecture Types
There are four general types of installations:
- **Local EFR** runs directly on a POS with tight hardware coupling
- **Local Server EFR** centralizes fiscalization for multiple POS systems within a store
- **Provider Cloud EFR** scales this model to many customers in a partner-managed cloud
- **efsta Cloud EFR** removes all operational effort by offering a fully efsta-managed, cloud-native fiscalization service
| Type | Hosted by | Offline capable | Fiscal hardware | Installation guide |
|---------------------|-----------|-----------------|-----------------|--------------------|
| Local EFR
Local Server EFR | Customer | ✅ Yes | ✅ Yes | Local: [Getting started](/efr/getting-started) |
| Provider Cloud EFR | Partner | ⚠️ Depends | ❌ No | Local: [Getting started](/efr/getting-started) |
| **efsta Cloud EFR** | **efsta** | ❌ No | ❌ No | [Cloud EFR guide](/efr/cloud) |
**Local installation**
> localhost:5618/register
For “classical” local installations EFR can be installed locally. By using this EFR architecture there is a 1:1 communication between
upstreaming software and EFR. EFR creates a main client which stores all data to provide it for the exports. In case of an outage,
it will affect both systems at the same time (for example hard disc crashes,…).
This architecture is recommended for countries with fiscal hardware devices like fiscal printers, hardware signature sources.
To use this architecture, connect EFR with the efsta cloud by using the Badge
(unique identifier of a company establish cloud communication to the efsta cloud for using the monitoring and the archive) of the company level,
provided in the efsta portal.
**Local Server Installation**
> ***[local IP]***:5618/register
In case of stores that have many upstreaming systems within one store and want to centralize fiscalization on a centralized server,
EFR can be installed on a store server. One EFR then handles all transactions from that legal entity (tax payer).
As each upstreaming system identifies with its own IDs (Location ID and Terminal ID) data will be stored and generated in the right export/journal.
This will be shown in the EFR, as sub clients will be created for each new combination of the mentioned IDs.
The partner is responsible to enable (network) communication between the systems and to protect the system(s).
Recommended signature sources are cloud signature devices or other servers for signing the fiscal data.
Fiscal hardware devices are not recommended for such an architecture.
**Provider Cloud Installation**
> ***[public IP]***:5618/register
Cloud upstreaming systems can use EFR hosted in the cloud. This can be any cloud for example Microsoft Azure, AWS Cloud or any other cloud.
As the cloud is provided/hosted by the partner the security –, updating –, Network –, Firewall–,… -topics in the partner’s responsibility.
As cloud systems are centralized systems that handle different taxpayers on one installation,
each transaction has an additional identifier which is the tax ID/VAT ID or Steuernummer or GLN.
Each upstreaming system then gets a new client within EFR to provide the client-specific exports.
The clients will then be identified with the combination of TaxId, TL and TT (Vat ID, location ID and till ID).
Each client needs to have the adequate signature source in countries where it is mandatory.
**efsta Cloud Installation**
efsta provides a product where EFR is hosted on a cloud maintained by efsta. The functionality is comparable with the “provider Cloud Installation”,
the only difference is that efsta hosts the EFR. The partner will then send data to specific endpoints by identifying with API key and API secret to get the OAuth token.
This product is exclusively available for upstreaming systems that are fully in the cloud and no fiscal hardware is needed
(for example fiscal printers, hardware signature devices,…).
There is no user interface for the customers to configure as efsta will provide all settings.
Exports can be downloaded from the efsta Portal or by sending HTTP requests to the cloud EFR.
:::info
Product only available on request.
:::
For full setup and authentication details, see the [**Cloud EFR guide**](/efr/cloud)
## EFR Modes
Furthermore, there are three different modes the EFR can be run in, compatible with all previously mentioned architecture types:
### Single POS
Single POS is the standard mode for a **single cash register**. It is suitable for individual POS systems without the need to manage multiple registers or companies.
### Multi POS
With multi POS, one installed EFR manages **multiple cash registers** from the **same company**. It is typically used in a back-office server setup to handle up to 100 POS installations per company.
:::note
If more than 100 POS installations are needed, additional EFRs can be created.
:::
### Multi Company
Using Multi Company, one installed EFR manages **multiple companies, locations, and cash registers**, which is only possible when cloud-hosting the EFR. To use this mode, please request consultation with a partner manager for setup.
:::note
Multi Company mode is not available for certain features like digital receipt management, which is currently only for Single POS and Multi POS.
:::
---
source: https://docs.dev.efsta.eu/efr/cloud
---
# Cloud EFR
**Cloud EFR** is a fully efsta-managed fiscalisation service where EFR runs in efsta's cloud infrastructure.
There is no software to install or maintain on your side — efsta handles all configuration, updates, scaling, and operations.
:::info
Product only available on request. To get access, contact your efsta partner manager or write to [ticket@efsta.eu](mailto:ticket@efsta.eu).
:::
## What is Cloud EFR?
- EFR hosted and operated entirely by efsta
- Accessible via HTTPS API using OAuth Bearer token authentication
- Same transaction request format as a locally installed EFR
- No local web UI at `localhost:5618`
- No fiscal hardware (printers, hardware signature devices) required or supported
- efsta handles the initial connection of the EFR to the company or organisation via badge; all other settings must be configured by the customer either through the API or the efsta Portal
## When to use it
:::warning
Cloud EFR is **exclusively** for POS systems that are fully cloud-based and have **no offline capability**. If your POS system needs to work without an internet connection, use [Local EFR (Getting Started)](/efr/getting-started) instead.
:::
## Ordering
Cloud EFRs are created by efsta. To order one:
1. Contact your efsta partner manager, or email [ticket@efsta.eu](mailto:ticket@efsta.eu)
2. efsta creates the Cloud EFR and provides your **API Key** and **API Secret**
3. You can find them in your company's properties in the efsta Portal
## Authentication
Cloud EFR uses OAuth 2.0 client credentials. Implement the following flow in your cloud POS:
1. Authorize with ApiKey and ApiSecret to get access token and refresh token.
2. Access- and refresh tokens should be temporarily stored on the cloud POS system.
3. With the access token, requests can be sent to the cloud EFR.
4. If the access token has expired (HTTP 401 `{ "error": "invalid_token", "error_description": "Invalid token: access token is invalid" }`), the cloud POS can use its refresh token to request new access- and refresh tokens, which are temporarily saved once more. You can also check before each request whether the token has already expired.
5. If the refresh token has expired as well (same HTTP 401 response), access- and refresh tokens must be re-requested with ApiKey and ApiSecret.
:::info
- Token Validity
- Access token: 1 hour
- Refresh token: 7 days
- These expiry dates may still be up to change.
:::
**Getting tokens**
Access tokens are scoped to the `TaxId`, `TL`, and `TT` used during issuance.
```http
POST /auth/token
[Headers]
Authorization: Basic base64(ApiKey:ApiSecret)
Content-Type: application/x-www-form-urlencoded
[Body]
grant_type=client_credentials
TaxId=...
TL=...
TT=...
```
```http
POST /auth/token
[Headers]
Content-Type: application/x-www-form-urlencoded
[Body]
grant_type=client_credentials
client_id=ApiKey
client_secret=ApiSecret
TaxId=...
TL=...
TT=...
```
The authentication mechanism for multi-company Cloud EFRs uses credentials at the organizational level. This means one credential set grants fiscalization access for all companies managed within that instance.
:::warning
These tokens should be treated as **secrets** and kept **secured**!
:::
We strongly recommend that the partner implements the following measures in their integrated solution:
- **Restrict End-User Permissions:**
The ability for a POS end-user to modify the Tax ID within the POS application should be disabled. This prevents unauthorized or accidental fiscalization of receipts for an incorrect company.
- **Secure Credential Storage:**
API credentials must be stored securely. The recommended best practice is to manage them in a secure backend environment. If credentials must be stored on the client-side POS terminal, they must be robustly encrypted both at rest and during transport.
**Refreshing tokens**
Refresh tokens are scoped to the same `TaxId`, `TL`, and `TT` as the access tokens issued with them.
```http
POST /auth/token
[Headers]
Content-Type: application/x-www-form-urlencoded
[Body]
client_id=ApiKey
grant_type=refresh_token
refresh_token=tGz...
TaxId=...
TL=...
TT=...
```
**Token response format**
The response format is identical whether you're requesting tokens via Basic Auth, body credentials, or using a refresh token.
```json
{
"access_token": "eyJ0...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "eyJ0...",
"access_token_expires": 1753865826,
"access_token_expires_at": 1753865826,
"refresh_token_expires": 1755071826,
"refresh_token_expires_at": 1755071826,
"api_key": "1124_Test..."
}
```
| Field | Type | Description |
|----------------------------|----------|---|
| `access_token` | `string` | Bearer token used for authenticating API requests. |
| `token_type` | `string` | Token type (always `"Bearer"`). |
| `expires_in` | `number` | Time in seconds until the access token expires. |
| `refresh_token` | `string` | Token that can be used to obtain a new access token. |
| `access_token_expires` | `number` | Expiry timestamp of the access token (Unix time). |
| `access_token_expires_at` | `number` | Same as above, included for compatibility. |
| `refresh_token_expires` | `number` | Expiry timestamp of the refresh token. |
| `refresh_token_expires_at` | `number` | Same as above. |
| `api_key` | `string` | Echo of the `ApiKey` used. |
## Making requests
Send all EFR requests with the access token in the `Authorization` header.
**Request Header:**
| Name | Value |
|---|---|
| `Authorization` | `Bearer [ACCESS_TOKEN]` |
The request body is identical to a locally installed EFR. See the [API reference](/efr/api) for full documentation.
**Example: `/state` endpoint**
API Reference: [EFR State](/efr/api#efr-state)
```http
GET /state
[Headers]
Authorization: Bearer [ACCESS_TOKEN]
```
**Example: `/register` endpoint**
API Reference: [Cashier Log In](/efr/api/business-cases#cashier-log-in)
```http
POST /register
[Headers]
Authorization: Bearer [ACCESS_TOKEN]
[Body]
{
"Tra": {
"ESR": {
"D": "2024-06-01T08:30:15",
"TaxId": "DE123456789"
"TL": "001",
"TT": "1",
"TN": "35",
"NFS": "LOGIN",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "xxx"
}
}
}
```
## Capacity & modes
- For more than 100 POS installations, your partner manager can create additional Cloud EFRs
- These share the same API credentials
- POS installations are distributed evenly
- MultiCompany mode requires setup consultation with a partner manager
- Digital receipt management is not available in MultiCompany mode
| Mode | POS limit per EFR | Use case |
|---|---|---|
| MultiPOS (default) | Up to 100 | One company, multiple cloud POS instances |
| MultiCompany | Up to 100 | One EFR handles multiple companies and locations |
## Exports
Fiscalised data can be accessed two ways:
- **efsta Portal** — download audit files, journals, and reports from the Portal UI
- **HTTP requests** — send authenticated requests to the Cloud EFR endpoint using the same `/export` endpoints as local EFR
## Country-specific guides
Steps 1 (API integration) and 2 (Portal setup) of each country's Quick Start apply unchanged. Country-specific fiscal steps apply where they do not require hardware devices.
Continue with your country guide after completing setup above:
| | | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **AT** | **BE** | **CZ** | **DE** | **DK** | **ES** | **FR** | **HR** | **HU** |
| **Austria** | **Belgium** | **Czechia** | **Germany** | **Denmark** | **Spain** | **France** | **Croatia** | **Hungary** |
| | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **IT** | **LT** | **NO** | **PL** | **PT** | **SE** | **SI** | **SK** |
| **Italy** | **Lithuania** | **Norway** | **Poland** | **Portugal** | **Sweden** | **Slovenia** | **Slovakia** |
---
source: https://docs.dev.efsta.eu/efr/container
---
# Container Usage
:::warning[Compatibility Notice]
Our docker images are designed only for **standalone** Docker usage. The EFR's data storage is not designed for multi-process use and cannot be used by multiple replicas at the same time. It is NOT supported in distributed environments like Kubernetes, Docker Swarm, or Nomad unless a deployment strategy is used that guarantees only one instance is running at a time.
:::
## How to use a docker image
```
$ docker run -itd -v /home/efsta/efrDATA:/usr/src/EFR/DATA -p 20011:5618 --restart always --device=/dev/bus/usb/001/002 --privileged efsta/efr-[country-code]:latest efr
```
:::info
Please note that this is only an example and must be adjusted to fulfill security and environment needs. **efsta is not responsible** for any kind of data loss or other damages.
:::
## Attributes and parameters
### Mapping the network port
The EFR exposes port `5618`, which needs to be published to access its API
```
-p 8090:5618
```
### Persisting storage
The container path `/usr/src/EFR/DATA` needs to be mapped to a volume to persist the EFR's internal storage
```
-v :/usr/src/EFR/DATA
```
### Recommended attributes
We recommend to always restart the container to ensure the EFR is responsive to the POS in case of a crash or system outage.
```
--restart always
```
## Country-Specific Options
### Connecting smart cards (Austria)
To connect smart cards in Austria (in case of using hardware fiscalization), the USB device needs to be made accessible to the container. Additionally, depending on the host environment, the `--privileged` parameter may be needed to allow the Docker runtime to access the port.
```
--device=/dev/ --privileged
```
Connected smartcards can be listed and stored in a variable in the right format with the following command on the host system:
```
# idevices=$(lsusb | grep -i 'gemalto|ACR39U' | awk '{print "--device=/dev/bus/usb/" $2 "/" $4}' | awk '{gsub (":","",$1); printf "%s ",$1}')
When using online signatures, this can be skipped.
```
### Connecting to hardware TSEs (Germany)
When using a hardware TSE, the USB ports need to be made accessible to the container. Additionally, depending on the host environment, the --privileged parameter may be needed to allow the Docker runtime to access USB.
```
-v /dev/usb:/dev/usb --privileged
```
This can be skipped when using cloud TSEs.
### Connecting printers (Hungary, Poland)
[HU]
[PL]
To connect fiscal printers in Hungary or Poland, the serial port needs to be made accessible to the container. Additionally, depending on the host environment, the `--privileged` parameter may be needed to allow the Docker runtime to access the port.
```
--device=/dev/ --privileged
```
Connected serial ports can be listed with the following command on the host system:
```
# dmesg | grep tty
```
---
source: https://docs.dev.efsta.eu/efr/countries
---
# Available Countries
| | | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **AT** | **BE** | **CZ** | **DE** | **DK** | **ES** | **FR** | **HR** | **HU** |
| **Austria** | **Belgium** | **Czechia** | **Germany** | **Denmark** | **Spain** | **France** | **Croatia** | **Hungary** |
| | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **IT** | **LT** | **NO** | **PL** | **PT** | **SE** | **SI** | **SK** |
| **Italy** | **Lithuania** | **Norway** | **Poland** | **Portugal** | **Sweden** | **Slovenia** | **Slovakia** |
---
source: https://docs.dev.efsta.eu/efr/getting-started
---
## Step 1 - EFR API Integration
This onboarding guide was written to assist efsta customer’s with the efsta Portal and EFR setup after the POS has been integrated to the EFR API.
For EFR API Documentation, please refer to [API](/efr/api/)
## Step 2 - efsta Portal
Set up the efsta Portal.
#### Creating Organizations, Companies & Locations
First you will receive an invitation to our efsta Portal. If you still require an invite, please get in touch with our team at [ticket@efsta.eu](mailto:ticket@efsta.eu).
For each of the following sections, you have the option between an active or inactive setup (for testing). Please make sure to follow the steps appropriate to your demands.
:::warning
For testing/sandbox purposes, please create a test-organization with test-companies and test-EFRs.
If you test with an active/live EFR, an **invoice** will automatically be issued (unless deactivated within the same day).
:::
**Testing Organizations**
organizations are used for structuring in the efsta portal. We recommend creating a separate organization for each country (e.g. Customer AT, Customer FR)
---
1. On the main page of the efsta portal, click on “organizations” in the left side menu
2. Click on „Add“
3. In the pop up window, select your organization from the drop-down menu
4. Enter the name of the test-organization you want to create
(f.e. *“efsta IT Services Gmbh Test Organization”*)
5. Tick the "tag as test" checkbox
6. Click on the save button
**Testing Companies**
1. Go to the page „Companies“
2. Click on the „Add“ button
3. In the pop-up window, select the test-organization that was just created
4. Select the correct country
5. Click on the save button
**Testing Locations**
Test-companies are automatically created with two location sites for testing purposes.
**Active Organizations**
Organizations are used for structuring in the efsta portal. We recommend creating a separate organization for each country (e.g. Customer AT, Customer FR)
---
1. On the main page of the efsta portal, click on “organizations” in the left side menu
2. Click on „Add“
3. In the pop up window, select your organization from the drop-down menu
4. Enter the name of the organization you want to create
(f.e. *“efsta IT Services Gmbh Organization”*)
5. Click on the save button
**Active Companies**
1. Go to the page „Companies“
2. Click on the „ADD“ button
3. In the pop-up window, select the organization that was just created
4. Select the correct country
5. Enter the company data. At identification type, choose „EUROPE VAT-id“, country specific tax number, or GLN number if applicable
6. Click on the save button
For German companies you can add the WIdNr (Wirtschafts-Identifikationsnummer) – this is currently optional but will be **mandatory from 01.01.2027 onwards** as requirement for the german reporting obligation.
**Active Locations**
1. Go to „Locations“ in the left side menu
2. Click on „Add“
3. In the pop-up window, select the company you just created
4. Enter the location information
5. The internal branch ID should match with the TL which you send in the transactions
#### Inviting Users & Permissions
After you have finished your organization structure, you can invite users to manage the correlating organization, depending on where they should have access.
**User Invitations & Permission Setting**
1. Go back to “Organizations” page and the find your top organization
2. On the right side (next to the organization, company, or location) click on the "add user" symbol:
3. In the pop-up window, enter the mail address of the person you want to invite to the Portal and select the permissions you want to assign to them:
* Editor: can edit data, create companies and deactivate EFR
* Viewer: Read-only access with optional data sharing permissions
4. Click on the button „send invitation“ so the invited person will receive an email with a registration token
:::note
The invitation is valid for 10 days.
:::
5. * The user to whom the invitation was sent has to sign up with their mail address and a custom password
* Alternatively, they can also sign up with a Google or Microsoft account
7. After the registration was completed, they can log in
## Step 3 - Installation
At this point, there are two different paths you can take with your setup: Local Installation or Cloud Installation. Please continue with only one of the following two steps:
If your POS runs locally (Windows, Linux, Android), continue with Step 3 below.
If your POS is fully cloud-based and requires no local installation, use Cloud EFR instead of Step 3.
**System Requirements**
# System Requirements
* Operating System
* Windows 7 or higher
* Linux
* Android 8 or higher
* Typically 1 GB hard disk space reserved
* Minimum 100 MB per POS
* Administration rights during installation
* Internet access for cloud services
:::tip[Good to know]
- EFR should run locally for fail-safety reasons.
- **Cloud EFR** can only be used for fully cloud-based POS systems. [See Cloud EFR](/efr/cloud)
- We recommend whitelisting the email address **noreply@efsta.net** when using a spam filter to ensure notifications from our efsta portal are delivered.
:::
Firewall Settings
| Partner | Host | Used for |
|----------------|---------------------------------------------------------------------------------------|---------------------------------------|
| efsta cloud | https://\*.efsta.net:443
https://fr.efsta.net:443
https://de-fr.efsta.net:443 | EFR in Online mode for archiving data |
#### Remote Signature
| | Partner | Used for | Host |
|:------------------:|-----------------|---------------------------:|-------------------------------------------------------------------------------------------------------------------|
|
[AT]
| A-Trust | **External HSM signature** | https://hs-abnahme.a-trust.at:443
https://rksv.a-trust.at/ |
|  | Prime-Sign | **External HSM signature** | https://rs-1f9e614c.ps.prime-sign.com:443
https://rs-2759ffb9.ps.prime-sign.com
*(please see note below)* |
|
[BE]
| zwartedoos.be | **Remote Test FDM** | https://sdk.zwartedoos.be:443 |
|
[DE]
| Deutsche Fiskal | **Remote TSE** | https://fiskal.cloud:443 |
|  | Fiskaly | **Remote TSE** | https://kassensichv.io:443
https://\*.fiskaly.com:443 |
|  | Swissbit Cloud | **Remote TSE**
Test | https://web-tse.de:443
https://dev.web-tse.de:443 |
|
[SE]
| Infrasec | **Productive**
Test | https://ccu.infrasec.se:8449
https://ccu-verify.infrasec.se:8449 |
:::info
Please note that Prime-Sign has not just one HSM Server, but a cluster. If certificates are ordered using the efsta Cloud Portal, you'll see the host address in the portal. However, should the certificate be ordered through different channels, it is possible that it resides on a different server, using a different IP.
:::
#### Fiscal Authority
| | Partner | Used for | Host |
|:---------------------------:|------------|--------------------------:|----------------------------------------------------------------------------------|
|
[CZ]
| EET 2.0 | **Productive**
Test | https://\*.trzbyeet.gov.cz:443
https://pg.trzbyeet.gov.cz:443 |
|
[ES]
| VERI*FACTU | **Productive**
Test | https://www1.agenciatributaria.gob.es
https://prewww1.aeat.es |
|  Araba | | **Productive**
Test | https://ticketbai.araba.eus
https://pruebas-ticketbai.araba.eus |
|  Bizkaia | | **Productive**
Test | https://sarrerak.bizkaia.eus
https://pruesarrerak.bizkaia.eus |
|  Gipuzkoa | | **Productive**
Test | https://tbai-z.egoitza.gipuzkoa.eus
https://tbai-z.prep.gipuzkoa.eus |
|
[HR]
| FINA | **Productive**
Test | https://cis.porezna-uprava.hr:8449
https://cistest.apis-it.hr:8449 |
|
[PT]
| | **Productive** | https://servicos.portaldasfinancas.gov.pt:422/SeriesWSService |
|
[SI]
| FURS | **Productive**
Test | https://blagajne.fu.gov.si:9003
https://blagajne-test.fu.gov.si:9002 |
#### Fiscal Devices
| | Partner | Used for | Host |
|:------------:|---------------|-------------------------:|-------------------|
|
[BE]
| zwartedoos.be | **Productive**
NTP | *:443
*:123 |
#### Fiscal Printer
| | Partner | Used for | Host |
|:------------------:|---------|----------------:|-------------------------------------------------------------------------------------------|
|
[HU]
| BBOX | **Productive** | 193.91.88.26:4791 |
|
[SK]
| BBOX | **Productive** | 193.91.88.26:4791 |
|
[IT]
| Epson | **Productive** | - |
|  | Custom | **Productive** | - |
|
[PL]
| | **Productive**
**Productive**
Test
Test | https://esb.mf.gov.pl:5062
https://e-kasy.mf.gov.pl
https://esb-te.mf.gov.pl:5062
https://test-e-kasy.mf.gov.pl |
|  | Exorigo | **Productive**
**Productive**
Test
Firmware Update
NTP
NTP | crr-eh01-prd.servicebus.windows.net:443
crr-eh02-prd.servicebus.windows.net:443
crr-eh-we-tst.servicebus.windows.net:443
upfirm.exorigo-upos.pl:4433
tempus1.gum.gov.pl:123
tempus2.gum.gov.pl:123 |
* Go to public.efsta.net and select the appropriate country
* Download the correct installers for your system
* Install the software
* Once finished, open a browser and enter “localhost:5618” in the address line
* The EFR user-interface will open
Windows
* Windows 7 or higher
* .msi from [public.efsta.net](https://public.efsta.net/EFR)
* Runs as Windows service
Linux
* .zip from [public.efsta.net](https://public.efsta.net/EFR)
* Run file install.sh
* Run automation recommended, e.g. with systemd
* Setup run automation with install.sh: `install.sh --service --service-user=USER`
:::note[Required Packages]
Required packages for USB/Serial devices:
`libudev-dev`
Required packages for smartcard use:
`libpcsclite1 libpcsclite-dev pcscd build-essential libudev-dev`
:::
In order for the TSEs to properly work on arm64, the `libffi` library is needed on the system.
Most Linux distributions should come with this pre installed but it’s presence on the system can be checked with the following command:
`dpkg -l | grep libffi`
Which should produce an output similar to this:
```
ii libffi8:arm64 3.4.4-1 arm64 Foreign Function Interface library runtime
```
[AT]
[BE]
[DE]
[DK]
[FR]
[HR]
[IT]
[NO]
[PL]
[PT]
[SI]
Android
* Android 8 or higher
* .apk from [public.efsta.net](https://public.efsta.net/EFR)
* Execute and install apk on the device
* Disable battery optimization on first start (even if device is always plugged in / has no battery)
* On the first start the app will ask whether to disable battery optimization. Disabling it is required to ensure the app can run in the background and will not be suspended by the OS. Please make sure to test if the app can run interruption-free on your specific device and android version.
:::info[Uninstallation]
Please make sure to keep the app's data or perform a backup/export of all data you want to keep BEFORE uninstalling. Default data deletion behavior can vary between different android device manufacturers.
:::
**Connecting the EFR** see also [API Profile](/efr/api#profile)
In order to connect the EFR with the efsta Portal (recorder: online), follow these steps:
1. In the portal, navigate to “Companies” on the left side menu
2. Open the properties of your company
3. Locate and copy the badge number
:::warning[MultiCompany]
If you are using a MultiCompany installation, the badge of an organization must be selected.
:::
4. In the EFR, go to "Profile" and paste the badge
(Optional) For MultiPOS & MultiCompany, tick the checkbox “RN/TT” at "Client Assignment" on
:::warning[Attention]
Please double check that the Badge is correct **before** saving since it cannot be changed after activation
:::
:::note
**MultiPOS** is ONE installed EFR, managing multiple cash registers from the same company (usually a back-office server)
**MultiCompany** is ONE installed EFR, managing multiple companies, locations, and cash registers (only possible when cloud-hosting our EFR)
If you are interested in any of these two modes, please contact your partner manager for a consulting appointment!
:::
5. Save the profile, so the communication to the efsta Portal is activated.
The EFR status will change to “Online”.
:::warning[Attention]
Please allow communication to the efsta Portal through your firewall. If not, it will cause connection issues.
:::
:::info[Preconfiguration via ENV Variables (optional)]
For automated / scripted deployments, EFR Profile settings can also be configured via environment variables. See: [ENV-based EFR Profile Configuration (Advanced)](/efr/api#profile)
:::
## Step 4 and up - Country Specific Setup & Implementation Checklist
For the next steps, please continue reading the setup guide for the country you would like to implement:
| | | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **AT** | **BE** | **CZ** | **DE** | **DK** | **ES** | **FR** | **HR** | **HU** |
| **Austria** | **Belgium** | **Czechia** | **Germany** | **Denmark** | **Spain** | **France** | **Croatia** | **Hungary** |
| | | | | | | | |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| **IT** | **LT** | **NO** | **PL** | **PT** | **SE** | **SI** | **SK** |
| **Italy** | **Lithuania** | **Norway** | **Poland** | **Portugal** | **Sweden** | **Slovenia** | **Slovakia** |
---
source: https://docs.dev.efsta.eu/efr/system-requirements
---
# System Requirements
* Operating System
* Windows 7 or higher
* Linux
* Android 8 or higher
* Typically 1 GB hard disk space reserved
* Minimum 100 MB per POS
* Administration rights during installation
* Internet access for cloud services
:::tip[Good to know]
- EFR should run locally for fail-safety reasons.
- **Cloud EFR** can only be used for fully cloud-based POS systems. [See Cloud EFR](/efr/cloud)
- We recommend whitelisting the email address **noreply@efsta.net** when using a spam filter to ensure notifications from our efsta portal are delivered.
:::
Firewall Settings
| Partner | Host | Used for |
|----------------|---------------------------------------------------------------------------------------|---------------------------------------|
| efsta cloud | https://\*.efsta.net:443
https://fr.efsta.net:443
https://de-fr.efsta.net:443 | EFR in Online mode for archiving data |
#### Remote Signature
| | Partner | Used for | Host |
|:------------------:|-----------------|---------------------------:|-------------------------------------------------------------------------------------------------------------------|
|
[AT]
| A-Trust | **External HSM signature** | https://hs-abnahme.a-trust.at:443
https://rksv.a-trust.at/ |
|  | Prime-Sign | **External HSM signature** | https://rs-1f9e614c.ps.prime-sign.com:443
https://rs-2759ffb9.ps.prime-sign.com
*(please see note below)* |
|
[BE]
| zwartedoos.be | **Remote Test FDM** | https://sdk.zwartedoos.be:443 |
|
[DE]
| Deutsche Fiskal | **Remote TSE** | https://fiskal.cloud:443 |
|  | Fiskaly | **Remote TSE** | https://kassensichv.io:443
https://\*.fiskaly.com:443 |
|  | Swissbit Cloud | **Remote TSE**
Test | https://web-tse.de:443
https://dev.web-tse.de:443 |
|
[SE]
| Infrasec | **Productive**
Test | https://ccu.infrasec.se:8449
https://ccu-verify.infrasec.se:8449 |
:::info
Please note that Prime-Sign has not just one HSM Server, but a cluster. If certificates are ordered using the efsta Cloud Portal, you'll see the host address in the portal. However, should the certificate be ordered through different channels, it is possible that it resides on a different server, using a different IP.
:::
#### Fiscal Authority
| | Partner | Used for | Host |
|:---------------------------:|------------|--------------------------:|----------------------------------------------------------------------------------|
|
[CZ]
| EET 2.0 | **Productive**
Test | https://\*.trzbyeet.gov.cz:443
https://pg.trzbyeet.gov.cz:443 |
|
[ES]
| VERI*FACTU | **Productive**
Test | https://www1.agenciatributaria.gob.es
https://prewww1.aeat.es |
|  Araba | | **Productive**
Test | https://ticketbai.araba.eus
https://pruebas-ticketbai.araba.eus |
|  Bizkaia | | **Productive**
Test | https://sarrerak.bizkaia.eus
https://pruesarrerak.bizkaia.eus |
|  Gipuzkoa | | **Productive**
Test | https://tbai-z.egoitza.gipuzkoa.eus
https://tbai-z.prep.gipuzkoa.eus |
|
[HR]
| FINA | **Productive**
Test | https://cis.porezna-uprava.hr:8449
https://cistest.apis-it.hr:8449 |
|
[PT]
| | **Productive** | https://servicos.portaldasfinancas.gov.pt:422/SeriesWSService |
|
[SI]
| FURS | **Productive**
Test | https://blagajne.fu.gov.si:9003
https://blagajne-test.fu.gov.si:9002 |
#### Fiscal Devices
| | Partner | Used for | Host |
|:------------:|---------------|-------------------------:|-------------------|
|
[BE]
| zwartedoos.be | **Productive**
NTP | *:443
*:123 |
#### Fiscal Printer
| | Partner | Used for | Host |
|:------------------:|---------|----------------:|-------------------------------------------------------------------------------------------|
|
[HU]
| BBOX | **Productive** | 193.91.88.26:4791 |
|
[SK]
| BBOX | **Productive** | 193.91.88.26:4791 |
|
[IT]
| Epson | **Productive** | - |
|  | Custom | **Productive** | - |
|
[PL]
| | **Productive**
**Productive**
Test
Test | https://esb.mf.gov.pl:5062
https://e-kasy.mf.gov.pl
https://esb-te.mf.gov.pl:5062
https://test-e-kasy.mf.gov.pl |
|  | Exorigo | **Productive**
**Productive**
Test
Firmware Update
NTP
NTP | crr-eh01-prd.servicebus.windows.net:443
crr-eh02-prd.servicebus.windows.net:443
crr-eh-we-tst.servicebus.windows.net:443
upfirm.exorigo-upos.pl:4433
tempus1.gum.gov.pl:123
tempus2.gum.gov.pl:123 |