Skip to main content
API docs by Redocly

EFR Unified API (2026-09-16)

Download OpenAPI specification:Download

efsta Consulting Team: consulting@efsta.eu URL: https://efsta.eu

Introduction

The EFR (Electronic Fiscal Register) is a middleware for fiscalization, e-invoicing and receipt archiving. It can run on-site with the POS, in a partner's or customer's datacenter, or in the efsta cloud. On-site deployments can also control fiscal printers or other local signing devices where required. The EFR processes transactions according to the configured country's fiscal requirements.

The API uses a common request format across all supported countries. Send transactions, including sales, refunds, voids, invoices, vouchers, closures and reports, to POST /register. The EFR identifies the business case from the request content. Required fields depend on the business case and country.

This reference covers:

  • receipt fields (ESR), with descriptions and examples;
  • JSON and XML request examples for each documented business case;
  • administrative endpoints for configuration, status, journal access, receipt rendering and printer control.

How to read this reference

Many fields are optional in the schema because their requirements depend on the country or business case. Field descriptions use the following labels:

  • Mandatory in: countries where the field is required.
  • Only used in: countries where the field applies.
  • Mandatory for: business cases that require the field. For example, a void requires a reference to the original receipt, and an invoice requires customer data.

The mandatory labels define the minimum required data. We recommend also sending optional fields whenever the POS already holds the corresponding information. Provide as complete a transaction record as possible to prepare the integration for additional countries and their requirements.

The /register examples show the required fields for each documented case. See the Rule Set for field definitions, Business Cases and Country Specific Business Cases for transaction requirements, and the EFR documentation for country guides.

Request and response formats

The API supports application/json and text/xml. Both formats represent the same data. In JSON, objects in the line arrays (PosA, PayA, TaxA) use the _ key to identify their type (Pos, Mod, Lin, Pay, Tax). In XML, the element name identifies the type.

Transaction responses contain a Result with the result code RC: OK (registered), NO (not registered, a later retry may succeed) or BAD (not registered, terminate the transaction). If a UserMessage is present, the POS must show it to the operator.

Machine-readable annotations for agents

Country and business-case requirements are also provided as vendor extensions: x-efr-mandatory-countries, x-efr-country-only, x-efr-mandatory-when and x-efr-datatype on fields, and the vocabularies x-efr-countries and x-efr-payment-groups at the top level. Country requirements are recorded in these extensions rather than as JSON Schema required rules. Schema validation alone does not check country requirements.

Versioning

The specification uses the latest changelog date as info.version. The download filename includes this date. Release notes are listed under Changes below.

Changes

Releases are listed from newest to oldest.

2026-09-16 — Initial release

  • Initial publication of the EFR Unified API specification.
  • POST /register with 71 business-case examples (common and country-specific), each available in JSON and XML.
  • Field definitions for ESR, Ctm, Pos, Mod, Lin, Pay, Tax and Audit, including country and business-case requirements.
  • Administrative routes: configuration (/cfg, /profile), state and journal access (/state, /find, /last, /retrieve, /disk), rendering (/render), printer control (/peri/*), /service/restart, /qr and /recorder/lastdh.
  • Response format TraC with JSON and XML samples for success (OK) and the error cases BAD and NO.

Transactions

The /register super-endpoint and transaction-level operations.

Register a transaction (all business cases)

The single super-endpoint. The business case is determined by the combination of ESR.NFS/ESR.NF, ESR.Void, Pos.PTY, ESR.DD/ESR.DT and the presence of ESR.Ctm. The named examples (grouped by category in their summaries) give one body per business case. Also accepts an Audit record for technical/export events. Country-conditional mandatoriness is annotated via x-efr-mandatory-countries (never enforced as required, to preserve one API for all countries).

Request Body schema:
required
Any of
required
object
object

Start of a transaction ([DE]); the response carries the TSE TID to send back in the closing Tra.

object (Audit)

Technical/audit event record (Export Events).

property name*
additional property
any

Responses

Request samples

Content type
Example

Standard fiscal sale with explicit tax array.

{
  • "Tra": {
    }
}

Response samples

Content type
{
  • "SQ": "string",
  • "Result": {
    },
  • "ESR": {
    },
  • "Fis": { }
}

Re-send the last transaction after a crash/restart

Identical body to /register; use it instead of /register when re-sending after a POS crash or restart, because duplicate detection is 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, and when ESR.D is missing or differs from the stored transaction — so a re-send still matches even if the POS could not preserve the original number or timestamp. An already-registered transaction returns Result.RC=OK with ErrorCode=#DUPLICATE and is not recorded twice.

Request Body schema:
required
Any of
required
object
object

Start of a transaction ([DE]); the response carries the TSE TID to send back in the closing Tra.

object (Audit)

Technical/audit event record (Export Events).

property name*
additional property
any

Responses

Request samples

Content type
Example

Standard fiscal sale with explicit tax array.

{
  • "Tra": {
    }
}

Response samples

Content type
{
  • "SQ": "string",
  • "Result": {
    },
  • "ESR": {
    },
  • "Fis": { }
}

Configuration

Company/base data and cloud profile.

Get configuration

Returns the current company header/base data.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

header Parameters
Accept
string
Example: application/json

Response format: application/json (default) or text/xml.

Responses

Response samples

Content type
{
  • "Cfg": {
    }
}

Set configuration

Sets receipt header fields (company, location, terminal, …). Must be sent before the first transaction; recommended on each POS startup. No effect if values are unchanged.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

Request Body schema:
required
required
object
object (Cmp)
object (Loc)
object (Trm)
object (Doc)
Array of objects (CfgDev)

Input devices.

Array of objects (Agentur)

Agencies (third-party providers).

Responses

Request samples

Content type
{
  • "Cfg": {
    }
}

Response samples

Content type
{
  • "SQ": "string",
  • "Result": {
    },
  • "ESR": {
    },
  • "Fis": { }
}

Set profile (Badge/TaxId)

Sets the Badge field to connect the instance to the efsta cloud.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

Request Body schema:
required
Badge
required
string

Badge value from the company details in the efsta portal.

TaxId
string

Responses

Request samples

Content type
{
  • "Badge": "XXX",
  • "TaxId": "XXX"
}

Response samples

Content type
{
  • "SQ": "string",
  • "Result": {
    },
  • "ESR": {
    },
  • "Fis": { }
}

Status & Journal

Runtime state, journal search/retrieval and storage info.

EFR state

Runtime state of the EFR installation.

header Parameters
Accept
string
Example: application/json

Response format: application/json (default) or text/xml.

Responses

Response samples

Content type
{
  • "pid": 0,
  • "arch": "string",
  • "uptime": 0,
  • "name": "string",
  • "version": "string",
  • "Country": "string",
  • "Online": true,
  • "Recorder": "string",
  • "RN": "string",
  • "RecSent": 0,
  • "RecQueued": 0,
  • "RetryQueued": 0,
  • "TimeOffset": 0,
  • "D": "string",
  • "DiskUsage": 0,
  • "DiskQuota": 0,
  • "Company": "string"
}

Find journal records

Search the EFR journal. Any ESR property may be used as an additional query criterion.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

from
string
Example: from=2024-01-15

From date (YYYY-MM-DD).

till
string
Example: till=2024-12-31

Till date (YYYY-MM-DD).

limit
string
Example: limit=10rows10000ms

Volume/runtime limit 'XrowsYms'. Default 1000rows5000ms.

sort
string
Example: sort=asc

Sort order. Default 'desc'.

continuation
string
Example: continuation=51856974

Continuation token.

fn
string
Example: fn=001/1/10

Fiscal number (instead of tl/tt/tn).

tn
string
Example: tn=5

Transaction number.

d
string
Example: d=2024-11-05

Date.

sq
string
Example: sq=10

Sequence number.

_
string
Example: _=Tra

Record type: Tra, TraS, Rep, Cfg, log, …

t
string
Example: t=8.38

Total.

nfs
string
Example: nfs=Z

Non-fiscal type filter.

header Parameters
Accept
string
Example: application/json

Response format: application/json (default) or text/xml.

Responses

Response samples

Content type
{ }

Get last transaction

Fetches the last registered data object (POST /register). Use on restart or for display.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

_
string
Example: _=Tra

Record type: Tra, TraS, Rep, Cfg, log, …

header Parameters
Accept
string
Example: application/json

Response format: application/json (default) or text/xml.

Responses

Response samples

Content type
{ }

Retrieve journal records

Periodical retrieval of records for backup/reporting, starting behind the given SQ.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

last
required
string
Example: last=0

Read records behind this SQ (last=0 from the beginning).

endSQ
string
Example: endSQ=2000

End SQ.

target
string
Example: target=C:/exports

Target folder to save the export/retrieved file to.

_
string
Example: _=Tra

Record type: Tra, TraS, Rep, Cfg, log, …

Responses

Response samples

Content type
{ }

Storage information

Total storage used (MB) and per-directory usage.

Responses

Response samples

Content type
{
  • "Usage": 0,
  • "Path": { }
}

Rendering

Receipt rendering (HTML/PDF/text/ESC-POS).

Render last receipt (HTML)

HTML rendering of the receipt (fiscal.pug).

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

FN
string
Example: FN=4711

Fiscal number to render. Default: last receipt.

Responses

Render a posted transaction

Render a specific transaction supplied in the body (Tra JSON or XML, fetched via /find or /tra).

Request Body schema:
optional
Any of
required
object
object

Start of a transaction ([DE]); the response carries the TSE TID to send back in the closing Tra.

object (Audit)

Technical/audit event record (Export Events).

property name*
additional property
any

Responses

Request samples

Content type
{
  • "Tra": {
    },
  • "TraS": {
    },
  • "Audit": {
    }
}

Render receipt (PDF)

PDF rendering of the receipt.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

FN
string
Example: FN=4711

Fiscal number to render. Default: last receipt.

Responses

Render receipt (text)

Plain-text rendering of the receipt.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

FN
string
Example: FN=4711

Fiscal number to render. Default: last receipt.

Responses

Render receipt (ESC/POS)

ESC/POS commands line by line for a receipt printer.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

FN
string
Example: FN=4711

Fiscal number to render. Default: last receipt.

Responses

Peripherals (PERI)

Direct printer, customer display and cash-drawer control.

Direct print

Prints text directly on the connected printer without registering a transaction.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

Request Body schema: text/plain
required
string

Responses

Printer state

Information about the connected printer / fiscal module.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

header Parameters
Accept
string
Example: application/json

Response format: application/json (default) or text/xml.

Responses

Response samples

Content type
{
  • "ModuleName": "string",
  • "ID": "string",
  • "ZI": 0,
  • "SimpleState": {
    }
}

Line display

Displays text on the connected customer line display.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

Request Body schema: text/plain
required
string

Responses

Open cash drawer

Opens the cash drawer.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

Responses

Maintenance

Service restart.

Shut the EFR app down

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 it, the EFR stays down.

query Parameters
password
string
Example: password=mypwd

Profile password (when not localhost).

Responses

Utility

QR images and document handle.

Last document handle

Document handle of the last transaction, for downloading the digital receipt from the efsta cloud.

query Parameters
rn
string
Example: rn=1_1

Register Number (client). Default 'def'.

Responses

QR image

Renders a QR code image from arbitrary text.

query Parameters
text
required
string
Example: text=hello%20world

QR source data (URL-encoded).

type
string
Example: type=png

Image type: png (default), bmp, svg, pc437.

size
string
Example: size=5

Module size in pixels.

margin
string
Example: margin=4

Margin in modules. Default 1.

Responses