EFR Portugal
Quick Start
The EFSTA System serves as software blackbox to fulfill country specific fiscal requirements for POS systems using a unified API.
So, the frontend application operated by the cashier prepares transaction data (items, prices), which finally is registered with the EFR (EFSTA Fiscal Register) service. Here the transaction is augmented with fiscal reference data and stored on local disk and in the EFSTA cloud archive.
In Portugal it is mandatory to use officially certified software (CERTIFICAÇÃO DE SOFTWARE MODELO 24), for this different approaches exist:
-
Variant A: Certification of your POS software using EFR
You have to implement specific rules in your master data administration, POS frontend, EFSTA is used for cryptography, archiving and periodic SAF-T export to the Fiscal Authority. Be aware that you will require consulting and the full certification process will take about one year. -
Variant B: Use of the certified SimplePOS API
Your software will act as data entry only, the registration of transactions is done by EFR, you have to print the preformatted documents. Also here consulting is required, but in total your efforts will be a fraction of variant A.
Firewall settings
Printer
You will have to print fiscal documents according to law. If your software is certified (Variant A), your document layout will be part of the certification. With SimplePOS (Variant B) either EFR prints directly (only Epson TM-T88 or compatible over USB, LAN or RS232), or you send the preformatted output to the printer controlled by your software (recommended).
The printer must be able to print the mandatory QR code (https://info.portaldasfinancas.gov.pt/pt/docs/Conteudos_1pagina/Documents/QR_Code_Technical_ Specifications.pdf).
API-Key
For certification and field usage of EFR you have to obtain a partner specific API-Key from your efsta sales representative, which has to be entered in "Perfil":
[PT] Specific ESR Fields
Unique Fiscal Number (FN)
In cash register systems usually each transaction gets an incremental transaction number. But the fiscal rules determine numbering per document type (e.g. invoice, credit note, ...). You can register your transaction number in ESR field TN as reference, but always a separate Fiscal Number FN will be assigned and stored in the journal. The current number part is reset to 1 with each year's first transaction.
Fiscal Signature
A digital signature is created for each transaction and blockchained according to law, parts of the signature are printed in receipt trailer line Processado por programa certificado... As the signature is included in SAF-T [PT] export data, the fiscal authority can and will verify signature values and chain.
Document Types
Sale / Credit Note (Fatura Simplificado / Nota de crédito)
As with other countries using fiscal printers, mixing of positive (sales) and negative (return/void) positions within one transaction is not allowed and will lead to a <TraC><Result RC="BAD"> response. Please train your cashiers to do this in two separate steps. To accept data from applications, which do not remove lines, but immediately void unwanted scans, negative (return/void) positions are allowed, as long as they correspond to positive positions within the same transaction.
Transactions with negative total (e.g. ESR.T="-3.98") automatically are registered as credit notes "Nota de Crédito", which are printed showing inverted amounts and quantities. You have to reference the original transaction in fields ESR.RFN (or ESR.RTL, ESR.RTT, ESR.RTN) and Pos.RPN.
Also specify a reason for SAF-T export:
<Tra>
<ESR T="-3.98" … RFN="FS 001_1.23/1234" Rsn="Jacket did not fit">
…
Invoice (Fatura)
For sales with a total from EUR 1000.00 instead of FS "Fatura simplificado" an invoice FT "Fatura" is issued.
For this, customer data including the customer's TaxId NIF is required:
<Tra>
<ESR T="1008.98" …>
<Ctm TaxId="PT123456789" Nam="Nuno MUELLER" Adr="Rua do Porto, 12" City="Carcavelos"
Zip="2775-543" Ctry="PT"/>
…
If a ticket (with lower ESR.T) is registered including <Ctm TaxId= , also FT will be used. <Ctm> information without TaxId is shown as unknown customer (CustomerTaxID=Desconhecido) in SAF-T, document type is FS. Please be advised that cash payment (PayG="NU" | PayG="cash") must be less than EUR 3000.00.
Voiding Documents (Anulação)
Mark the transaction with <ESR … Void="1", specify RFN and send the positions inverted. You will not get a <Fis> tag in the response, as the void trigger itself not signed - the original ticket is flagged as voided (InvoiceStatus=A) in SAF-T. For voiding the last transaction /register/void/last (see EFR Reference) may be used.
Override of Document Type
The document type is selected automatically upon signum of the transaction total.
If another document type as FS/FT/NC is required, you can specify it in ESR field Document Type DT:
<Tra>
<ESR DT="CM" …
See appendix for a full list of supported document types.
Nonfiscal Documents
Administrative transactions like PAYIN, PAYOUT or Z report (closure) can be registered using field ESR.NF, e.g. <ESR NF="Z"... . Using NF no signature will be created, these document types are not included in SAF-T export.
POS Administration
Document Reprints
To access the fiscal journal use http://localhost:5618 "Diário", where you can search for specific field values. Single transaction reprints can be requested, which will be marked "Cópia do documento original ...".
Backup Strategy
During fiscal certification the backup strategy of the POS (databases) and recovery procedure will have to be presented. Usually on larger POS infrastructure base and configuration data is provided by replication, so a local base data backup will not be required. Transaction data backup from EFR is done immediately after each registration into the EFSTA cloud archive, so data loss cannot occur as long as either EFR has an online connection or the local hard disk works without total failure.
Manual Integration of Documents Lost with Backup Restore
Although a loss of transaction data is highly unprobable, the fiscal auditor may ask for the procedure how to proceed after system failure and replacement. After restore of the last backup, a function to manually integrate documents that have been lost may be required to provide a gapless SAF-T export.
For integration of "Lost Documents" please register the original transaction including the additional fields Fiscal Number FN and original Date D:
<Tra>
<ESR TL="001" TT="1" T="0.98" Opr="102" FN="FT 001_1.22/4711"
D="2022-01-02T14:12:00">
<PosA>
…
Manual integration will automatically start a new numbering series (see chapter below). Documents integrated manually are tagged with <SourceBilling>M</SourceBilling> ("manual") in SAF-T, and other reference fields are set according to the regulations.
Integration from Manual Invoice Book
In case of POS outage the company may use a Manual Invoice Book with prenumbered invoice forms, which have to be manually entered at end of outage. The transactions are registered being FN the form number and D the original Date:
<Tra>
<ESR TL="001" TT="1" T="0.98" Opr="102" FN="abc/00001" D="2023-07-14T14:12:00">
<PosA>
…
Manual integration will automatically start a new numbering series (see chapter below). According to "ponto 2.4 do Despacho n.º 8632/2014 de 03 de Julho do Diretor Geral da Autoridade Tributária e Aduaneira" Manual Invoice Books can be ordered from a certified printing company. Before, the retailer has to open a manual series in AT Portal to get an ATCUD, which is required by the printing company. The forms are sequentially numbered.
Numbering Series
The numbering of documents has to be unique within the whole company. For this the ID of the POS system and the document date is used: Transaction Location (business premise) TL="001", Transaction Terminal (POS number on premise) TT="1" with transaction Date D="2022-..." will result in series "001_1.22". The whole Fiscal Number then shows as "FS 001_1.22/1234" An automatic enumerator reset is performed with each new year (first transaction on January, 1st 2023), giving e.g. "FS 001_1.23/1". If the system is restored from backup, you eventually may have to enter missing documents (see Manual Recovery of Lost Documents). Then [start new series] on the "Controle" page (http://localhost:5618/control).
Client Certificate for the Software Producer
Steps:
- please open http://localhost:5618 page "Controle" and click on "Registration"
- check if NIF (=TaxId) is that of you (the software producer)
- in "Request" enter the certificate subject fields, e.g. "FR, none, Paris, ..."
CN will show your NIF - then create [new .csr]
- the content of the .csr file (PEM base64 formatted) has to be copied into the request field in the AT portal
- the request will be processed by AT and you will get the public key part via email
- then paste the PEM formatted certificate in the "Registration" page and [create .pfx]
The .pfx file then will be used as client certificate in the WSDL communication. Another certificate for communication with the test backend is provided by EFR.
ATCUD
Each document (e.g. Fatura Simplificado) has to show a number prefix, which is issued by the [PT] fiscal authority AT. EFR does the communication automatically on behalf (open or close series) using a web service interface. You will have to configure a login (sub-user/password) in the fiscal portal https://www.acesso.gov.pt/gestaoDeUtilizadores/criarForm?partID=PFIN.
Then enter the data on "Controle", [configurar…] login:
With [teste e salve] a communication test is performed, on success an ecrypted file with the login credentials is created. With [distribuir] you can immediately provide the credentials to all systems belonging to your company. This function is disabled in test mode (before certification).
Open series at AT always can be shown on "Controle", [listar…]:
Network communication with the AT portal is done with following endpoints: https://servicos.portaldasfinancas.gov.pt:422/SeriesWSService (production) and https://servicos.portaldasfinancas.gov.pt:722/SeriesWSService (test)
Please assure that these URLs and ports are appropriate configured on your local firewall.
During certification with the fiscal authority please set "Perfil" "Attributes" "Fiscal_test"
This will force communication with the test endpoint.
Automatic New Series
As far as possible opening an new series is done automatically by EFR on following events:
- first transaction on a new (empty) EFR
- first transaction in a new year (e.g. on January 1st)
- first transaction in Manual Integration of Lost Documentsm
(because after hardware failure a new series is required) - first normal transaction after Manual Integration of Lost Documents
Closing Series
On new series, the old series always are closed automatically. But if a POS system is taken out of operation, please use the function "Controle", "Serie e ATCUD" [finalizer ativas / close active].
SAF-T Export
The Portuguese Fiscal Authority "AT" requires at least monthly upload of sales data of all POS systems. This usually is performed from the EFSTA Cloud Portal for the whole company. During certification and for audit on premise by the Fiscal Authority a local export is required. This can be found on http://localhost:5618 (open with your browser) under "Controle".
An export of all POS systems of the business premise is required, so all other EFR systems within the local network (LAN) are shown (for this UDP broadcasting is used, if your systems are not shown properly check your network switch/router/firewall configuration). By default checkbox "LAN" is checked, so a SAF-T export will include all other POS systems (with matching field Loc.TL, see "Dados básicos"). If LAN=on and a known POS cannot be reached, a warning is shown on the GUI, but the export will be performed.
REST Implementation
For export use e.g.
GET /control/export?lan=on&from=2022-01-01&till=2022-12-31
Before starting the export please check the current network state with:
GET /control/lan
(for XML response instead of JSON set request header Accept=application/xml).
POS systems not accessible are listed with "state":"offline". In case of systems being offline, request a user confirmation that the resulting export will not be complete. As network reachability can change, the /control/lan result is cached for 60 sec and then will be used in an subsequent export, offline systems will be skipped. Optional query parameters for /control/export:
&headercomment=... will be exported in `<header><HeaderComment>`...
&target=... specify a directory path, where the export .xml shall be stored. Else, a .zip containing the export file will be sent in response body.
Special Cases
Reduced Tax Rates for Madeira, Azores
For Portuguese islands reduced tax rates are valid; extend TaxG with "M" for Madeira and "A" for Azores. For details see "VAT Rates" in Appendix. For stores in these regions you have to set field TaxGR in "Dados básicos", "Location":
B2B Sales
For sales business-to-business at least the 'NIF' TaxId (with or without leading "PT") of the buyer shall be registered; example:
<Tra>
<ESR T="3.98" TN="1234" Opr="555">
<Ctm TaxId="PT980701066">
<PosA>
...
TaxId PT999999990 ("undefined"/"desconhecido") is ignored and will not trigger a "Fatura". For further customer data fields see EFR Reference.
Receipt Layout
The receipt print layout is controlled in /EFR/rn/def/cfg/fiscal.ejs (or .pug). EJS/Pug (ejs.co/pugjs.org) are templating languages to transform JSON data into HTML, afterwards the formatted HTML is rendered for a character font receipt printer. A basic layout is provided by default, details of print configuration can be found in EFR Reference.
Software Certification
Finally, the POS software has to undergo a certification with the Portuguese fiscal authority AT.
Prerequisites
For details please contact sales@efsta.eu, EFSTA will accompany you through the preparation phase.
Initiation at the Fiscal Portal
The fiscal public key file public.pem has to be uploaded (download from page "Controle").
After registration you will receive an email from your fiscal auditor.
Data Transfer to the Tax Authority
Part of the Portugal ruleset is to periodically (per day or per month) deliver receipt (invoice) data in SAF-T [PT] 1.04_01 format. An appropriate export function is included in EFR and can be found in the user interface http://localhost:5618, page "Controle". By now this is a manual task, further process automation is planned in accordance with the Tax Authority.
Appendix
VAT Rates
Following rates are used by default, if only TaxG is delivered, but no tax rate in TaxA element (/EFR/app/FR/cfg/taxg.cfg):
| TaxG | Prc | Description |
|---|---|---|
| A | 23 | Normal |
| AM | 22 | Normal (Madeira) |
| AA | 18 | Normal (Azores) |
| B | 13 | Intermédia |
| BM | 12 | Intermédia (Madeira) |
| BA | 9 | Intermédia (Azores) |
| C | 6 | Reduzida |
| CM | 5 | Reduzida (Madeira) |
| CA | 4 | Reduzida (Azores) |
| M01 | 0 | Artigo 16.º n.º 6 do CIVA (ou similar) |
| M02 | 0 | Artigo 6.º do Decreto-Lei n.º 198/90, de 19 de Junho |
| M03 | 0 | Exigibilidade de Caixa |
| M04 | 0 | Isento Artigo 13.º do CIVA (ou similar) |
| M05 | 0 | Isento Artigo 14.º do CIVA (ou similar) |
| M06 | 0 | Isento Artigo 15.º do CIVA (ou similar) |
| M07 | 0 | Isento Artigo 9.º do CIVA (ou similar) |
| M08 | 0 | IVA – autoliquidação |
| M09 | 0 | IVA - não confere direito a dedução |
| M10 | 0 | IVA – Regime de isenção |
| M11 | 0 | Regime particular do tabaco |
| M12 | 0 | Regime da margem de lucro – Agências de viagens |
| M13 | 0 | Regime da margem de lucro – Bens em segunda mão |
| M14 | 0 | Regime da margem de lucro – Objetos de arte |
| M15 | 0 | Regime da margem de lucro – Objetos de coleção e antiguidades |
| M16 | 0 | Isento Artigo 14.º do RITI (ou similar) |
| M20 | 0 | IVA - Regime forfetário |
| M99 | 0 | Não sujeito; não tributado (ou similar) |
For tax exemptions set the appropriate code in field Pos.TaxG
SAF-T Payment Group Codes
Source: Diploma - Portaria n.º 302/2016, de 2 de dezembro (4.1.4.20.6.1. Meios de pagamento)
| PayG | EFSTA standard | Description | descrição |
|---|---|---|---|
| CC | creditcard | Credit card | Cartão crédito |
| CD | debitcard | Debit card | Cartão débito |
| CH | check, cheque | Bank cheque | Cheque bancário |
| CI | International Letter of Credit | Crédito documentário internacional | |
| CO | voucher | Gift cheque or gift card | Cheque ou cartão oferta |
| CS | creditnote | Balance compensation in current account | Compensação de saldos em conta corrente |
| DE | loyalty | Electronic Money, for example, on fidelity or points cards | Dinheiro eletrónico, por exemplo residente em cartões de fidelidade ou de pontos |
| LC | open | Commercial Bill | Letra comercial |
| MB | atm | Payment references for ATM | Referências de pagamento para Multibanco |
| NU | cash, change, refund, foreign | Cash | Numerário |
| OU | rounding | Other means not mentioned | Outros meios aqui não assinalados |
| PR | deposit | Exchange of goods | Permuta de bens |
| TB | mobile | Banking transfer or authorized direct debit | Transferência bancária ou débito direto autorizado |
| TR | title | Non-wage compensation titles regardless of their support [paper or digital format], for instance, meal or education vouchers, etc. | Títulos de compensação extrassalarial independentemente do seu suporte, por exemplo, títulos de refeição, educação, etc. |
SAF-T Document Type Codes
Source: 1.3.8. Códigos para o tipo de documento (Comunicação de Séries Documentais - Aspetos Específicos)
| DT | description descrição |
|---|---|
| FT | Invoice Fatura, emitida nos termos do artigo 36.º do Código do IVA |
| FS | Simplified Invoice issued according to article 40 of the VAT code Fatura simplificada, emitida nos termos do artigo 40.º do Código do IVA |
| FR | Invoice-receipt (default) Fatura-recibo |
| ND | Debit note Nota de débito |
| NC | Credit note (default for negative transaction) Nota de crédito |
| GR | Guia de remessa |
| GT | Guia de transporte |
| GA | Guia de movimentação de ativos fixos próprios |
| GC | Guia de consignação |
| GD | Guia ou nota de devolução |
| CM | Consultas de mesa |
| CC | Crédito de consignação |
| FC | Fatura de consignação |
| FO | Folhas de obra |
| NE | Nota de encomenda |
| OU | Outros |
| OR | Orçamentos |
| PF | Pró-forma |
| RP | Prémio ou recibo de prémio |
| RE | Estorno ou recibo de estorno |
| CS | Imputação a cosseguradoras |
| LD | Imputação a cosseguradora líder |
| RA | Resseguro aceite |
| RC | Recibo emitido no âmbito do regime de IVA de Caixa |
| RG | Outros recibos emitidos |