Fiscal Requirements
Functions of the EFR
- Fiscal message generation upon ESR data delivered
- Local message signature using the Fiscal Certificate (TicketBAI only)
- Request to the fiscal system over HTTPS TLS 1.2
- Response to the cash register application
- Transaction protocol
- Protocol of Grand Totals per tax group
- Retry handling according to regulations in case of network failure
- Tamper-proof archiving (encrypted cloud-storage)
Test (Playground) Environment
For testing transactions should be fiscalized against the playground system. Therefore the profile has to be set to fiscal test mode http://localhost:5618/profile:
Please set this attribute and confirm with [Save].
For testing you will need a Test/Demo certificate, which can be obtained like productive ones (see next section).
Fiscal Certificate Handling
By law receipts have to be digitally signed. The certificate used is issued over the fiscal authority's online system. Certificate file (xxx.p12) and password are confidential.
Local upload
On page http://localhost:5618/control you can upload the certificate file:
The certificate is installed correctly as soon as the green OK bar and the ES-Certificate is shown:
Certificate assignment
First, make sure the correct region is selected. At the section 'Region' of the 'Base' tab, please either select 'VERI*FACTU' or choose the specific province you are operating in when using TicketBAI.
The certificate can be selected in the 'Perfil' tab. When using VERI*FACTU, you will see the option "Certificate Number" and a drop down to select the appropriate certificate. With TicketBAI on the other hand, this is called "NumSerieDispositivo". Here the number of the received and uploaded device certificate (CN=...) has to be chosen.
If the certificate is not loaded and assigned correctly you will get error #CERT_NF for transactions. This is necessary because installed certificates are valid for the local machine, not for a specific client and multiple certificates can be loaded.
Certain information must be entered to successfully send data, including the TaxId, which has to be specified in client profile http://localhost:5618/profile:
- The section ES_Epigrafe only exists for TicketBAI, specifically in the region of Bizkaia.
- If SerieFactura is not filled out, TL_TT is used.
Network Access
The Spanish fiscal law stipulates online registration of each sale transaction via web request. A transaction code and its QR representation has to be printed on the receipt or invoice. Therefore the machine running EFR must be granted access to the fiscal system. Network devices (Router, Firewall) have to be configured accordingly or a web proxy is used.
The hosts for the firewall settings can be found in chapter firewall setting.
A proxy can be defined in the default profile http://localhost:5618/profile and is shown in the control web page; example:
By default a network timeout of 5000 ms is used (can be changed using Attribute Fiscal_timeout=).
The connection can be tested using the "Echo"-feature on http://localhost:5618/control
Offline Transactions
If the fiscal acknowledgement cannot be obtained within the timespan defined (5000 ms by default), the registration response is sent from EFR to the cash register software with an empty fiscal tag. It is marked with Errorcode="#OFFLINE", and the operator is informed with the first offline transaction (not to interfere cashier action) with UserMessage="Server offline".
Offline transactions are stored in folder /EFR/rn/def/retry (see chapter "Local Storage" in EFR Reference), and delayed an automatic retry is performed.
Typically, the fiscal response should be received within less than one sec.
VAT Handling
Tax Rates
In the Canary Islands, only the specific tax rates which apply to this region can be used - the standard rates for mainland Spain and Basque provinces will throw errors. Conversely, if the the rates of the Canary Islands are sent for mainland Spain or TicketBAI, they will also be rejected.
Here is an overview of the available tax groups:
Standard Tax Rates (Mainland Spain and Basque Provinces)
| Tax group | TaxG | Tax rate | Use |
|---|---|---|---|
| Normal | A | 21% | Appliances, cars, cinema tickets, smartphones, etc. |
| Lower | B | 10% | Cultural activities, transport and electricity |
| Reduced | E | 4% | Super reduced rates |
| Exempt | F | 0% | Donations of certain goods |
Tax Rates for Canary Islands
| TaxG | Tax rate | Use |
|---|---|---|
| A1 | 7% | General rate |
| B1 | 20% | Tobacco products, excluding cigars |
| C1 | 15% | Luxury goods, including cigars, jewelry, and perfumes |
| D1 | 9.5% | Delivery of certain vehicles and means of transport |
| E1 | 3% | Reduced rate for specific industries, including mining, chemical, textile, land transport, and vehicle repair |
| F1 | 0% | Bread, milk, cheese, eggs, fruits, vegetables, books, newspapers, medicines |
Request Example
{
"Tra": {
"ESR": {
"TL": "001",
"TT": "1",
"Opr": "101",
"OprN": "Mario Rossi",
"OprTIN": "xxx",
"TP": "Table 1",
"PosA": [
{
"_": "Pos",
"PN": "1",
"IN": "1001",
"Dsc": "Example Item 1",
"TaxG": "B1",
"Amt": "3.98",
"Qty": "2",
"QtyU": "Pc.",
"Pri": "1.99",
"Cat": "10",
"CatN": "Example Category 10"
},
{
"_": "Pos",
"PN": "2",
"IN": "1020",
"Dsc": "Example Item 2",
"TaxG": "A1",
"Amt": "1.50",
"Cat": "11",
"CatN": "Example Category 11"
},
{
"_": "Lin",
"Dsc": "Subtotal",
"LAmt": "5.48"
},
{
"_": "Pos",
"PN": "3",
"IN": "1030",
"Dsc": "Example Item",
"TaxG": "Z1",
"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"
}
]
}
}
}
Exemptions
Futhermore, there are certain VAT exemptions for which no sales tax will be added. They work the same as normal tax groups and can be sent with the appropriate code.
List of Exemptions
All of the exemptions listed below can be used for both standard- and Canary Island tax groups.
| TaxG | Code | Exemption |
|---|---|---|
| Z1 | E1 | Domestic transactions (Educational, healthcare, social services) |
| Z2 | E2 | Exports of goods |
| Z3 | E3 | Transactions treated as exports |
| Z4 | E4 | Free zones, free warehouses, and other deposits or customs and tax regimes |
| Z5 | E5 | Supplies of goods destined for another EU member state |
| Z | E6 | Other |
These are also certain transactions which are not subject to VAT and can be sent as TaxG:
| TaxG | Reason | Description |
|---|---|---|
| Z6 | OT | Not subject to Article 7, 14 and others of Provisional VAT regulation |
| Z7 | RL | Not subject to localization rules |
| Z8 | VT | Not subject due to sales made on behalf of third parties |
| Z9 | IE | Not subject to TAI due to location rules, but foreign tax, IPIS/IGIC, or VAT from another EU member state applies |
Z8 and Z9 reasons can be sent in both systems, but since VERI*FACTU does not currently support declaring these, they will be mapped to the other reasons in the background. "VT" will be sent as "OT" and "IE" as "RL". TicketBAI however sends them as they are.
Retry Handling
Automatic retry is performed for all offline transactions, the retry interval is increased up to one hour, as long as the fiscal system is not accessible.
A finally successful fiscal retry is logged in the fiscal journal file, so the whole transaction is tracked.
If retries remain unsuccessful, EFR gives a UserMessage once a day.
Special ESR Element (TicketBAI)
'NIFoper' is TicketBAI only and does not exist with VERI*FACTU.
| Name | Description |
|---|---|
| ES_NIFoper | Operator's Tax Number |
Field NIFoper is optional in the fiscal message, so ES_NIFoper is optional in the transaction data registered.
<Tra>
<ESR D="2017-05-15T09:28:00" TL="01" TT="1" TN="2071" ES_NIFoper="01234567890" …>
For convenience on systems with only one operator, a fixed value can be set in http://localhost:5618/profile. If standard ESR field Opr is provided, also an automatic assignment list (Opr=ES_NIFoper) can be entered:
UserMessage
Independent of the success of a transaction a message for the operator of the cashier may
be requested by the EFR in <UserMessage>: this shall be printed to a display (e.g. MessageBox).
| UserMessage (ES) | UserMessage (EN) | Reason | Action |
|---|---|---|---|
| Sistema Fiscal fuera de línea | Fiscal System offline | network error, Tax Authority does not respond | Transaction has been successfully registered locally, it will be sent to the fiscal CIS system as soon as the network error has been solved. Check internet access. An echo test can be performed using the EFR web interface. |
| Cambiar NIF | TaxId changed | fiscal certificate replaced | may occur only during testing |
| #CERT_NF | #CERT_NF | certificate not loaded | Please revisit Fiscal Certificate Handling -> Local upload! |
| #MISS | #MISS | missing data in request | check for mandatory information missing in your REST command |
Automatic Recovery with the Fiscal System
In case the signature request to the fiscal system of the Tax Authority fails (network error, response timeout > 5 sec), a transaction is registered without signature. The EFR resends transactions in original order in background as soon as the network connection is restored. The cash register operator is informed via UserMessage. Offline transactions do not contain a tag and are marked with ErrorCode="#OFFLINE".
According to fiscal law network repair has to be performed within 48 hours.
Acceptable Warnings
Whenever a warning is acceptable, the transaction is not denied (RC=OK).
Real errors cause the response to be denied completely, and the TraC object will not be visible at all since it was not fiscalized.
For example, the following warnings will be displayed when starting transactions on a new device:
TicketBAI:
“w-009-AVISO: Posible error de encadenamiento validation failed”
VERI*FACTU:
"#FIS_ERR 2007: No debe informarse como primer registro, existen facturas emitidas con el obligado emisión y el sistema informático actual."
Document Numbering
By default, the numbering logic initializes with the following settings:
- Counter starts at 1
- Series is set to 1
- Year is taken from the current system date
This default behavior can be overridden by providing custom values in the input. For instance, clients may choose to:
- Start a new series
- Set the counter to a specific value
The system will validate both the format and whether the provided values match the configuration settings saved in the system.
System Reinstallation
When the system is reinstalled, the default numbering values are reset. This can lead to duplicated numbering values being sent to the tax authorities, potentially resulting in warnings or errors.
To prevent such issues, it is strongly recommended to:
- Set the counter to a value higher than the last used
- Or start a new series to ensure numbering continuity
The FN or Fiscal Number that is sent to Spain consists of the following information:
-
Year: The current year of the record.
-
Series: The series of the current batch of transactions, by default this is set to 1 but users can set new ones trough the input on the Base config site.
-
TL: Transaction Location code / store number.
-
TT: Transaction Terminal code / number of cash register.
-
Counter: The number of the transaction. This is a counter that starts from 1 with the first transaction.
Transactions Input Field
Every transaction sent to either TBAI or Verifactu systems contains a short description. By default this message only contains the following message: "factura {FN} TBAI/Verifactu". By using the input field on the Control config page this can be customized: "factura {custom description} {FN} TBAI/Verifactu"
