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. This will be supplied by us upon request. We will do this for you at the start of the project.
Auditing:PublicKeyBlobID-Blob containing the public key. This will be supplied by us upon request. We will do this for you at the start of the project.
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.
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:AuditGeneratorNameDATE_RANGENeeded for the proper date generation of the audit file.
Auditing:AuditCreatorStrategyNameDATE_RANGE_PER_COMPANYAllows for having one SAF-T file for the entire company regardless the amount of OUs i.e. one file per country.
Checking missed configuration(s)

Once you're done with all configuration steps. Make sure to run the service: AuditingValidateConfiguration which should return any step(s) that you may have missed or possibly undocumented.

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 (a numeric value)
  • 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
Company ID field

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.

Madeira and Azores

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.


Ecom organization unitsā€‹


For web shop/ecom organization units, additional considerations are needed on the OU level as follows:

  • The setting AutoOpenCloseFinancialPeriod must be set to true.

  • The setting Auditing:Provider remains SAFT as earlier advised under settings.

  • The setting Auditing:IncludeWebShopForAudits must be set to true.

  • The organization unit is set to "Open".

  • The web shop organization unit must be attached to the Portuguese company.

  • The financial period of the webshop OU must be set to "Open".

  • The following tasks need to be set up:

    • EVA.Core.Finance.Periods.AutoOpenCloseFinancialPeriod
    • EVA.Auditing.Tasks.CreateFinancialPeriodAuditTask (For this one, please input the Portuguese web shop/ecom OU ID in the designated field).

Periodic SAF-T file generationā€‹

In order to periodically generate the SAF-T file, we need to set up a task called EVA.Auditing.Tasks.CreateFinancialPeriodAuditTask from Admin 1.0 under Management ā†’ Tasks.

The following fields need to be set:

  • Name - (can be any unique name you want).
  • Cron: 0 4 2 * * (this will automatically generate the file on 2nd of every month at 4:00 am)
  • Arguments
    • Type - (can be left blank).
    • Organization unit - (the ID of the country of the Portuguese OU).
Generating SAF-T files impactful settings

When it comes to generating the SAF-T file there are two settings that impact the behavior. The two settings are:

  • Auditing:AuditCreatorStrategyName
  • Auditing:AuditGeneratorName

For Portugal, the Auditing:AuditGeneratorName is set to DATE_RANGE this will allow you to generate the SAF-T files using a "from" and "to" date. However, this always becomes the first until the last day of a month.

The other setting, Auditing:AuditCreatorStrategyName can be set with one of the following two values:

  • DATE_RANGE_COMPANY: This will generate the SAF-T file on a company level. It means that you'll get 1 SAF-T file covering all transactions made in Portugal regardless the organization unit.

  • DATE_RANGE: This will generate the SAF-T file on an organization unit level. It means you'll get a SAF-T file for each organization unit with Country specified as Portugal.

The reason why generating a SAF-T file on company level is we believe the invoice number in the file should be sequential and with the introduction of ATCUD weā€™ve moved to invoice numbers on a company level and not per OU.

Downloading the fileā€‹


The generated file can be downloaded from the Audit files chapter overview of Admin Suite.

Filter on the organization unit and select the proper file.

Generating the SAF-T file manually

The SAF-T file can also be manually triggered from the Audit files chapter of Admin Suite using the Generate audit file feature.

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.
  • 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.

Giftcardsā€‹


The following behavior applies when it comes to giftcard sales.

  • Giftcard 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.

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 (this is optional - if not provided the default one available in EVA will be used).
  • .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 - this parameter is not mandatory)
  • 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)

Here is a sample requestā€‹



const request: Partial<EVA.Auditing.SetSeriesSettings> = {
    "OrganizationUnitID": 36,
    "ClientCertificate": "MIIdOAIBAzCCHPQGCSqGSIb3DQEHAaCCHOUEghzhMIIc3TCCBg4GCSqGSIb3DQEHAaCCBf8EggX7MIIF9zCCBfMGCyqGSIb3DQEMCgECoIIE/jCCBPowHAYKKoZIhvcNAQwBAzAOBAjF5WML6zmWYAICB9AEggTYUQUj/1HhH9vwujULhhzfN3J+Zr",
    "ClientCertificatePassword": "TESTEwebservice",
    "Username": "yourusernamehere",
    "Password": "yourpasswordhere",
    "Endpoint": "https://servicos.portaldasfinancas.gov.pt:722/SeriesWSService"
}\

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 giftcards)
  • 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.

Stencil for Certified invoicesā€‹

For configuration and more details about Certified Invoices please refer to the general concepts section under Certified invoice stencil for thermal &/or PDF . A separate stencil is required to set up the email in which a certified invoice would be attached to. Configurations for such stencil can be found under Email invoice stencil.

Sample PDF and thermal receipts