EFR Italy

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

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	Host	Used for
[AT]	A-Trust	https://hs-abnahme.a-trust.at:443 https://rksv.a-trust.at/	external HSM signature
	Prime-Sign	https://rs-1f9e614c.ps.prime-sign.com:443 https://rs-2759ffb9.ps.prime-sign.com (please see note below)	external HSM signature
[DE]	Deutsche Fiskal	https://fiskal.cloud:443	remote TSE
	Fiskaly	https://kassensichv.io:443 https://*.fiskaly.com:443	remote TSE
[SE]	Infrasec	https://ccu.infrasec.se:8449	productive
	Infrasec	https://ccu-verify.infrasec.se:8449	test

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	Host	Used for
[CZ]	EET	https://prod.eet.cz:443	productive
		https://pg.eet.cz:443	test
[ES]		https://ticketbai.araba.eus	Álava productive
		https://pruebas-ticketbai.araba.eus	Álava test
		https://tbai-z.egoitza.gipuzkoa.eus	Guipúzcoa productive
		https://tbai-z.prep.gipuzkoa.eus	Guipúzcoa test
		https://sarrerak.bizkaia.eus	Bizkaia productive
		https://pruesarrerak.bizkaia.eus	Bizkaia test
[HR]	FINA	https://cis.porezna-uprava.hr:8449	productive
		https://cistest.apis-it.hr:8449	test
[PT]		https://servicos.portaldasfinancas.gov.pt:422/SeriesWSService	productive
[SI]	FURS	https://blagajne.fu.gov.si:9003	productive
		https://blagajne-test.fu.gov.si:9002	test

Fiscal Printer

	Partner	Host	Used for
[HU]	BBOX	193.91.88.26:4791	productive
[SK]	BBOX	193.91.88.26:4791	productive
[IT]	Epson	-	productive
	Custom	-	productive
[PL]		https://esb.mf.gov.pl:5062	productive
		https://e-kasy.mf.gov.pl	productive
		https://esb-te.mf.gov.pl:5062	test
		https://test-e-kasy.mf.gov.pl	test
	Exorigo	crr-eh01-prd.servicebus.windows.net:443 crr-eh02-prd.servicebus.windows.net:443	productive
	Exorigo	crr-eh-we-tst.servicebus.windows.net:443	test
	Exorigo	upfirm.exorigo-upos.pl:4433	Firmware Update
	Exorigo	tempus1.gum.gov.pl:123	NTP
	Exorigo	tempus2.gum.gov.pl:123	NTP
	POSNET	-

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

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

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.

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 200 registers. API login details can be found in the Cloud EFR settings in the portal.

Authentification

The following steps should be implemented for OAuth authentication of the Cloud EFR in your cloud POS system:

1. With the apiKey and securely stored apiSecret, the POS gets its access- and refresh tokens (POST https://efr.efsta.net/auth/gettoken)
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":"jwt expired"}), 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":"jwt expired"}), access- and refresh token must be queried with apiKey and apiSecret

note

The access key is currently valid for 24 hours, and the refresh key for 4 days. These expiry dates may still be up to change.

EFR Requests

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

Request Headers:

Name	Value
Authorization	OAuth token

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

Example requests:

GET https://efr.efsta.net/[api_key]/state

POST https://efr.efsta.net/[api_key]/register

Step 4 Printer Installation

By law, a fiscal printer is required to print customer receipts and daily closures. EFR handles communication to the printer as well as to the peripheral devices connected, i.e. line display and cash drawer. After having established a cable connection, set up and check the printer connection over http://localhost:5618.

Setup Connection

Printer connection can be set on page "Profilo":

Test Connection

Basic hardware tests can be made on page "Gestione":

Element	Description
Arrotondamento	Enable/disable automatic rounding function of printer
Ristampa	Reprint last fiscal receipt
Stampante	Non-fiscal test print
Cassetto	Open cash drawer
Visore	Send text to line display

Epson Printer FP-90III & FP-81II

see Epson

Custom Printer

see Custom