EFR Germany

Quick Start

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

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 support@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 Setup

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 Setup

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

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

Configure a Company for Sending E-Invoices

To allow a company to send E-Invoices with the efsta EFR, the configuration of the company’s base data is required. The necessary base data includes:

• Company data
• Location data
• E-Invoicing settings

Details on setting up the necessary company and location configuration can be found in the chapter API - Base data/company header data and Cfg - Configuration.

Setting up the E-Invoicing profile for the sending company

1. Please login to the efsta portal and select the config button on the right side of the company or organization overview:

   

2. Select the E-Invoice Profile tab and fill out the fields.

   

   note

   Depending on the country, there are additional fields at the bottom of this view which need to be filled in as well:

   • Germany: peppolSenderID
   • Poland: (KSeF) Token

3. Save and Send the configuration to the EFR by clicking button SEND CURRENT CFG eDocument”

   

   tip

   • SET DEFAULT CFG
     Sets the default configuration and does not send anything to the registers. When a new register is created, it checks if a default configuration exists and, if so, applies it.

   • SEND CURRENT CFG
     Sends the current configuration to all registers.

The buyer of a B2G invoice will receive their XRechnung via email (specified in ESR.DDto).

The config field “ContactElectronicMail” in the E-Invoicing profile (see "Setting up..." section above) contains the seller’s email address. This address is used to inform the seller about any errors which need their attention, as well as send them the XRechnung file along with a notice that it has been created and must be uploaded to the OZG-RE portal.

Step 3 - Local Installation // Web-API

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)
[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 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"
    }
  }
}

Step 4 - Preconfiguration

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)

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)

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

Step 5 - Order and configure a signature device (TSE)

A signature device can be ordered in the efsta portal. All information about signature devices and how to configure them in the EFR service can be found in topic fiscal devices.

Step 6 - Automate signature device (TSE) reporting

Coming soon

Step 7 - efsta Implementation Checklist

Before going live, you must submit the implementation checklist for validation. To acquire access, please contact your partner manager.

info

Please be aware that our consulting team requires 2–4 weeks to complete the review.