Skip to main content

🇵🇹 Portugal

This document describes all necessary configuration for a compliant setup in Portugal.

Configuration​

In order to configure your store in Portugal to be compliant, the following configurations need to take place.

Settings​

All settings below should be set on the most convenient level possible. In other words, if your organization structure has a country organization which houses all Portuguese stores, then that's where they should go.

SettingValueDescription
Auditing:DuplicatePrinttrueIn Portugal there is the obligation to hand out a receipt to the customer. This setting ensures a customer receipt and a duplicate is always printed as a default action.
Auditing:IncludeWebShopForAuditstrueFlag to indicate that web shops should also be included as part of the audit file.
Auditing:PrivateKeyBlobID-Blob containing the private key to sign the invoice/receipt documents with. Is set by using the AuditingSetPrivateKey service. (See below).
Auditing:ProviderSAFTSets the certified aspects, e.g. makes sure that all SAF-T features in EVA are enabled for those OU’s.
Auditing:SoftwareVersion2.0.1.0The version of EVA (this is a setting because our version increments every week, this is nicer for the outside world).
AutoOpenCloseFinancialPeriodtrueTo be set on the web shop (ecom) organization unit.
RequiredData:MaximumOrderAmount15000Max value of an order.
UniqueInvoiceNumberSequencetrueThis setting makes sure that Invoices are created within their unique number sequence.
UniqueInvoiceNumberSequencePerTypetrueThis setting makes sure that different types of documents (e.g. Credit note vs Invoice) have their own sequence.
UseInvoiceOutputFacadetrueAttaches the Certified Invoice PDF when emailing the Invoice (e.g. from POS & EVA Companion app.) This setting enables the use of the CertifiedInvoice stencil with destination Mail.
Auditing:DailyConsolidation:MailToinput desired email addressTo be set on container level: The email address that would be receiving the reports from the report task called DailyConsolidationReportTask
PaymentProof:EnabledtrueTo be set on container level: When an order is fully Endless Aisle (all line items are set to "Deliver" and without a B2B customer attached) a payment proof needs to be automatically generated. This setting enables such behavior. A payment proof stencil is required for this setting.

Auditing:PrivateKeyBlobID​

In order to set this setting, use our AuditingSetPrivateKey service. We will do this for you at the start of the project.

Company​

When configuring your Portuguese organization unit(s), a company needs to be attached. If there isn’t a Portuguese company present yet, a new one can be created within Admin Suite under the Companies chapter. The following fields need be filled:

  • Name
  • VatNumber
  • RegistrationNumber
  • Address (VisitorAddress)
    • Street
    • HouseNumber
    • ZipCode
    • City
    • CountryID

Organization unit​

Once a company is in place, you need to attach it to an organization unit(s).

Make sure the following fields are filled when creating an organization unit:

  • Name
  • BackendID (store number)
  • Address
    • Street
    • ZipCode
    • City
    • CountryID
  • CompanyID
note

It is crucial that you have the CompanyID field filled when creating the organization unit. You can retrieve this ID from the Portuguese company you created/have. This is the legal entity under which this OU/store is operating and will be referred to when filling in the details on the invoices and receipts.

Further, please make sure to fill all the auditing fields for your respective Portuguese OU's.

note

Support for Portuguese islands Madeira and Azores tax system are available. To use those you need to select region (CountrySubdivisionID) as Madeira (PT-20) or Azores (PT-30) and specify the Tax code and VAT% fields when creating the respective organization unit.

the following setup need to be conducted during the creation of organization unit:

Periodic SAF-T file generation​

In order to periodically generate the SAF-T file, we need to set up a task under Management → Tasks.

The task is called system:DailyConsolidationReportTask, once set up it will run every day at 23:55. It will consolidate all ledgers of DailyTotalsConsolidation and place them in an Excel called report.xslx and email that file to you.

The email will be sent to the address specified in the setting called Auditing:DailyConsolidation:MailTo. You will also need SMTP settings, and a Stencil with the following configuration:

  • Type: Template
  • Organization: Leave empty
  • Name: DailyConsilidation
  • Country: None
  • Language: Empty
  • Layout: None
  • Destination: Email
  • Content: As you wish - This is the content of the email that is apart from the invoice. So your tone of voice and brand text for example, like thank you for shopping with us, etc...

Downloading result​

The result of this export can be downloaded under Fiscal archiving → Archive → Download archive.

SAF-T applied criteria​

Here are some (included but not limited to) SAF-T applied criteria/behavior.

Sales amount​

The following behavior applies when it comes to the amount of a sales transaction.

  • For sales greater than €1,000/- (over the counter) it is mandatory to create a customer profile with a VAT number.
  • For sales over €3,000/- made to residents in national territory, a cash payment will not be possible.
  • For sales over €10,000/- made to residents outside national territory, a cash payment will not be possible.

Gift cards​

The following behavior applies when it comes to gift card sales.

  • Gift card sales are tax-exempt.
  • The Tax table in audit files will display the corresponding TaxExemptionReason as per your configuration. Here you can find how to create/manage TaxExemptionReasons.

Quotation support​

In some instances a quote is given to a customer (inclusive a special price/offer) with a set expiration date. To comply with SAF-T requirements in this regard, an entry in the SAF-T file is created. Editing the entry in the SAF-T file is then not possible in a scenario where you would like to edit the underlying offer. In that case you would need to create a new order/duplicate order and restart the quotation flow.

ATCUD setup​

As per Portuguese tax authority (Autoridade Tributaria e Adueneira - AT), effective January 1, 2023 it is mandatory to include a unique document code called ATCUD (Sequential Number Validation Code) and a QR code on invoices and relavent tax documents. An ATCUD code looks something like this "AAJFF2TKXW-7".

In order to comply with ATCUD requirements, certain configurations need to be made on both our side and yours. We categorize those into 2 steps "Authentication" and "EVA setup".

Authentication​

As with everything else, the flow starts with authentication, no surprises here. We need to authenticated to properly implement this, and that involves "creating a web user", and "applying for a digital certificate".

Creating web user​

In the Portuguese tax authority portal, a new user for New Black must be created. This should be done on your side. Go to https://www.acesso.gov.pt/gestaoDeUtilizadores/criarForm?partID=PFIN and create a New Black user with the permission WSE - Communication and Series Management via webservice and an email address input as "compliance@newblack.io".

note

The username and password you specify for this account will need to be shared with us. The credentials will be valid for both test and production and environments.

Applying for a digital certificate​

A digital certificate is an RSA key composed of two parts "Private" and "Public" key (issuing of the private key is always done on our side).

In order to issue the certificate the following information is needed from your side:

  • (C) Country of your company headquarters in two-letter code (Alpha-2 code).
  • (ST) Province, region, county or state of your company headquarters.
  • (L)Town / city of your company headquarters.
  • (CN) Common name, also known as the fiscal identification number of the underlying entity.
  • (O) Business organization name, is the legal name of the company.
  • (OU) Department name, the department to contact if any issues (example IT).
  • (E) Email Address, compliance@newblack.io

This information should be shared with us. Once received, we will generate the digital certificate and the outcome of it will generate two files:

  • csr: The file with the CSR request that is to be sent to the Portuguese tax authority (AT).
  • key: The file with the generated private key.

The "csr" should be uploaded to the AT portal https://faturas.portaldasfinancas.gov.pt/painelInicialProdSoftware.action. This can be done through the following steps:

  • Click the "Aderir ao serviço" button.
  • Apply for a new request by clicking the "Efetuar Novo Pedido" button.
  • Paste the .csr text that you have received from us, then click "Aderir"`.
  • The NIF and email field are pre-filled by the portal itself.

It can take multiple days before AT approve the request. AT will then share an email with a zip file. The content would include three files. That zip file needs to be shared with us in order to authenticate EVA with AT. The certificates are valid for 24 months and need to be renewed one month before expiration.

Once we've received the zip file, we'll integrate the certificate with the private key. As a result, the digital certificate signed by AT is integrated with the private key and saved with an access password that each software developer must define when executing the command.

At the end of all steps the following information must be accounted for and available:

  • .csr file that was shared with the AT portal.
  • .key file that will be integrated with the .cer file received from the governement.
  • .cer file received from the AT portal (used with .key file to generate .pfx file).
  • .cer file received from the AT portal.
  • .p7b file received from the AT portal.
  • .pfx file created by us.
  • Webuser credentials to the AT portal.

EVA setup​

note

With the introduction of ATCUD, the invoice sequence has been changed to company level and follows the structure: {documentType} {documentSeries}/{sequence} an example would be "it0 FT/1". This also impacts the way Audit files are generated. Audit files can only be generated on country level and not on single OU level. An audit file per company is created. Therefore, all organization units must have a company attached.

The service SetSeriesSettings is available to set up ATCUD within EVA. The service needs to following parameters:

  • OrganizationUnitID (Country OU on which the settings will be set e.g. Portugal)
  • SigningCertificate (certificate used for signing the message. Example: ChaveCifraPublicaAT2023.cer)
  • ClientCertificate (certificate used to secure the connection. Usually, a .pfx)
  • ClientCertificatePassword (password to the above)
  • Username (username of the webuser with the WSE permission)
  • Password (password of the username above)
  • Endpoint
    • https://servicos.portaldasfinancas.gov.pt:722/SeriesWSService (test)
    • https://servicos.portaldasfinancas.gov.pt:422/SeriesWSService (production)

The result of the SetSeriesSettings service request will create the following settings. These do not have to be set manually.

  • Auditing:SAFT:Series:ClientCertificatePassword
  • Auditing:SAFT:Series:Endpoint
  • Auditing:SAFT:Series:Password
  • Auditing:SAFT:Series:SigningCertificateBlobID
  • Auditing:SAFT:Series:Username
  • Auditing:SAFT:Series:ClientCertificateBlobID

After the service is successfully run, EVA will generate the ATCUD sequences. Each document type will have its own series. EVA supports the following document types:

  • Fatura Recibo (FT) = type 0
  • Fatura Simplificada (FS) = type 1
  • Fatura (FR) = type 2
  • Nota de Crédito (NC ) = type 4
  • Table checks (CM) = type 9 - (used for selling of gift cards)
  • Budgets (OR) = type 6 (used for offers / quotations in EVA)

With the service ListSeries the ATCUD series can be fetched for a specific organization unit. The service CancelSeries can be used to cancel an ATCUD series.

A task in EVA will be created in EVA to proactively check if the registered series are still active in the AT Portal. When the series are unavailable EVA will log a warning in the monitoring tools of EVA and will notify our compliance team.