installation

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

Good to know

• EFR should run locally for fail-safety reasons.
• Cloud EFR can only be used for Cloud POS.

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
[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	Productive Test	https://prod.eet.cz:443 https://pg.eet.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

At this point, there are two different paths you can take with your setup: Local Installation or Web-API. Please continue with only one of the following two steps.

Local Installation

1. Go to public.efsta.net and select the appropriate country
2. Download the correct installers for your system
3. Install the software
4. Once finished, open a browser and enter “localhost:5618” in the address line
5. The EFR user-interface will open

Windows

Windows

• Windows 7 or higher
• .msi from public.efsta.net
• Runs as Windows service

Linux

Linux

• .zip from public.efsta.net
• Run file install.sh
• Run automation recommended, e.g. with systemd
• Setup run automation with install.sh: install.sh --service --service-user=USER

Required Packages

Required packages for USB/Serial devices: libudev-dev

Required packages for smartcard use: libpcsclite1 libpcsclite-dev pcscd build-essential libudev-dev

ATTENTION: Swissbit / Germany

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

Android

Android

• Android 8 or higher
• .apk from public.efsta.net
• 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.

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

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

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

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”.

Attention

Please allow communication to the efsta Portal through your firewall. If not, it will cause connection issues.

Web-API

Attention

Only recommended for Cloud POS systems that do not have offline capabilities.

info

Product only available on request.

Ordering a Cloud EFR

Cloud EFRs can only be created by efsta employees. To order one, please get in touch with your efsta partner!

note

The cloud EFR runs in a 1:n relationship (MultiPOS mode) with your cloud POS installations. One EFR is created per company and can handle up to 100 POS installations. API credentials can be found in the company properties in the portal. If a company expects more than 100 POS installations, their partner manager can also create more Cloud EFRs. These have the same API credentials. The POS installations are distributed evenly across the EFRs.

Authentification

The following steps must be implemented in your cloud POS system for OAuth authentication:

1. Authorize with ApiKey and ApiSecret to get access token und 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 (HTTP 401 { "error": "invalid_token", "error_description": "Invalid token: access token is invalid" }), access- and refresh token must be queried with apiKey and apiSecret

note

The access token is currently valid for 1 hour, and the refresh token for 7 days. These expiry dates may still be up to change.

Method 1: HTTP Basic Authentication

POST /auth/token

[Headers]
Authorization: Basic base64(ApiKey:ApiSecret)
Content-Type: application/x-www-form-urlencoded

[Body]
grant_type=client_credentials
TaxId=...
TL=...
TT=...

Method 2: Client Credentials in Request Body

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=...

note

Access tokens are scoped to the TaxId, TL, and TT used during issuance.

Use refresh token to get new access tokens

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=...

note

Refresh tokens are scoped to the same TaxId, TL, and TT as the access tokens issued with them.

Response (Initial and Refresh Token Requests)

{
  "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..."
}

note

The response format is identical whether you're requesting tokens via Basic Auth, body credentials, or using a refresh token.

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.

EFR Requests

Finally, send an EFR request with the access token in the as Authorization in the request headers.

Request Headers:

Name	Value
Authorization	Bearer [ACCESS_TOKEN]

The requests are the same as for a locally installed EFR service, with addition of the access token in the authorization header.

Example: /state Endpoint

API Reference: EFR State

GET /state

[Headers]
Authorization: Bearer [ACCESS_TOKEN]

Example: Cashier Log In

API Reference: Cashier Log In

POST /register

[Headers]
Authorization: Bearer [ACCESS_TOKEN]

[Body]
{
  "Tra": {
    "ESR": {
      "D": "2024-06-01T08:30:15",
      "TL": "001",
      "TT": "1",
      "TN": "35",
      "NFS": "LOGIN",
      "Opr": "101",
      "OprN": "Mario Rossi",
      "OprTIN": "xxx"
    }
  }
}