How to connect fiscaldoo to the Tax Authority

What is it for?

To communicate series, invoices and delivery notes directly to the Tax and Customs Authority (AT), fiscaldoo uses the company's access data for the AT webservices: the sub-user and its password, the certificate and the AT public key. This data is stored once per company and per environment (Test or Production), protected by the credentials vault: once saved, the password and the private key can no longer be read.

Only someone with the Edit permission on the company's vault can save or change these credentials. In a new company nobody has it yet, so the first step is to start the vault.

Issuing does not need this connection. A company without credentials can issue and print invoices; what is left to do is the communication, which is then done through the monthly file or the Portal das Finanças.

When to use it?

• So that the company communicates series, invoices and delivery notes through fiscaldoo, without going to the Portal das Finanças.
• In a new company, when the Readiness of the communications with the AT says “There are no access data for the … environment”.
• When the AT certificate is close to expiry (Valid until) and the AT has given you a new one.

Where to find it?

• Accounting › Configure › Credentials vault › Start the vault (only in a company where nobody has Edit).
• Accounting › Configure › Credentials vault › Permissions (who can save and grant permissions).
• Accounting › Configure › Certified invoicing › Tax Authority credentials (the access data). The record's Check the readiness button opens the company's Readiness of the communications with the AT.

Before you start

• Do the steps with a user who has Fiscal administration. Steps 1 to 10 were done from start to finish with that profile, in a new company in the demo (Empresa Nova Exemplo, Lda). If you do not have this access, ask the administrator: in Settings › Users & Companies › Users, on the person's form, Advanced settings tab, they choose Fiscal administration in PT Localization — Invoicing, accounting and tax levels and add the company in Companies (the Profile tab does not have this option). See Profiles and permissions.
• The technical administrator (the user who manages the system) does not start the vault or grant permissions: their Credentials vault menu only shows Credentials.
• The company already has its tax number and the program certificate (Software certificates). See How to prepare the company to issue certified documents. Without the program certificate, the series and invoice lines in the Readiness stay at Something is missing (see “Common problems”).
• On the Portal das Finanças, the company has a sub-user for the webservices, with the profiles for the services it will use: WSE (series), WFA (invoices) and WDT (delivery notes). fiscaldoo cannot confirm these profiles: the Readiness reminds you of them on each line. Pending on-screen validation: creating the sub-user on the Portal das Finanças (the demo never connects to the real AT, only to the simulator).
• You have the certificate file the AT gave the company (.pfx) and its password, and the AT public key for the chosen environment. Pending validation by a certified accountant: how and from whom the company requests the certificate and the public key, and who keeps them.
• The server has the vault's encryption key. This is a matter for the system administrator.

How to use it

1. In the top right corner, check that you are in the right company. Open Accounting › Configure › Credentials vault › Start the vault. The Start the credentials vault window opens: “Nobody has “Edit” on this company's credentials vault yet, so nobody can grant permissions or save credentials. If you confirm, you RECEIVE “Edit” on all this company's portals, once only, and it is recorded in the audit log (who, when, which company).…” If someone in the company already has Edit, do not start the vault: ask them for the permission and go to step 3.
2. Click Confirm. Vault permissions opens with one line: your user, the company, Portal empty (all portals), Level Edit and the Warning “Can read the passwords in clear text. Recorded in the audit log.”.
3. Open Accounting › Configure › Certified invoicing › Tax Authority credentials and click New. The form warns “These credentials are incomplete: still missing web-service user, password, client certificate, private key. Until they are filled in, this company cannot communicate with the Tax Authority.”. The warning updates as you fill in: the user and password disappear as soon as you type them, and the client certificate and private key disappear when you choose the .pfx (step 6). With everything filled in, the warning disappears before you save.
4. Check the Company (it defaults to the company you are working in). Environment defaults to Test; the options are Test and Production. Start with Test.
5. In Web-service user, type the sub-user, in the format NIF/number (in the example, 599999993/1). In Web-service password, type its password.
6. In the AT CERTIFICATE FILE (.PFX) block, choose the file in Certificate file (.pfx) and type the Password of the .pfx. The screen explains: “Choose the .pfx the AT sent you and enter its password, then save: the certificate and the private key are extracted and stored below. The file and its password are not kept.” In AT public key (PEM), paste the AT public key for this environment.
7. Tick Used for sending. This is the environment the company communicates with; there can only be one per company. If the company's other environment was already ticked, the form warns straight away, for example: “The credentials of the Test environment are the ones used for sending. Saving these makes Production the environment this company communicates with, and the other one is unticked.” When you save, the other environment is unticked.
8. Click Save (cloud icon). Valid until is filled in with the certificate's date (in the example, 03/11/2027) and the password is shown masked. The Test the connection (simulator) button appears, next to Check the readiness, which was already on the new record.
9. Click Test the connection (simulator). fiscaldoo checks that the credentials are complete and queries the simulated AT; it sends nothing to the real AT.
10. Click Check the readiness. The company's Readiness of the communications with the AT opens, grouped by company and environment. Open the groups and check the lines for the environment you saved.

For the production environment, repeat steps 3 to 8 with Environment Production and the production credentials, and tick Used for sending on that record. You do not need to start the vault again: the Edit from step 2 applies to both environments. Pending on-screen validation: production credentials (the demo never uses real data or the real AT).

Shared from the parent company. In a child company (for example, a branch) with the same NIF as the parent company, choose the parent company's credentials for the same environment in this field, instead of repeating them. Nothing is copied.

Granting the permission to other people. Whoever has Edit grants, changes or removes permissions for others in Accounting › Configure › Credentials vault › Permissions (columns User, Company, Portal and Level). Nobody can grant it to themselves. See How to store portal passwords in the credentials vault.

Expected result

• Test passed: the credentials are complete and valid, and the simulated Tax Authority answered (accepted). Nothing was sent to the real Tax Authority.
• In the Readiness of the communications with the AT, the company has six lines: Test and Production for Series, Invoices and Transport guides. The three Test lines became Ready. The Production lines stay at Something is missing, with “There are no access data for the production environment of the Tax Authority. Without them nothing can be sent. Fiscal Administration enters them in Accounting › Configure › Certified invoicing › AT credentials.” and the Fix button.
• In Warnings, each line reminds you of the sub-user's profile on the Portal das Finanças, for example “The sub-user must have the profile WSE on the Finanças Portal. This can only be confirmed there, so it is not checked here.”. In Connection to the Tax Authority, the demo says Switched off: nothing is sent to the Tax Authority.

• In Vault permissions, the person who started the vault has Edit in this company, and the start-up was recorded in the audit log.
• Saving credentials does not create journal entries and does not communicate anything.

The credentials in the images are fictitious.

Important notes

Ready does not mean connected

Ready says the credentials are complete. The Connection to the Tax Authority column says whether the server actually sends: with Switched off, nothing goes out to the AT, and series, invoices and delivery notes remain to be communicated. Switching on real sending is a server setting, made by the system administrator, not a button on this screen. Check with them before you stop communicating through the Portal das Finanças. Pending on-screen validation: switching on real sending and the first submission in production (the demo only uses the simulator).

• Starting the vault is done once per company. After that, only someone with Edit grants permissions. Edit also lets you reveal passwords in the vault, and each reveal is recorded: give it only to whoever handles the credentials.
• What the Readiness does not see. It does not confirm the sub-user's profiles on the Portal das Finanças, or whether the password is correct at the AT. The test in step 9 uses the simulator.
• Tax Authority credentials and vault Credentials are different things. The Tax Authority credentials are the ones in this article and connect fiscaldoo to the webservices. The Credentials vault › Credentials menu stores portal passwords for the company's people: saving the sub-user's password there does not connect fiscaldoo to the AT. Both depend on the same vault permission.
• Secrets. The web-service password and the private key are write-only: once saved they appear masked and cannot be read, only replaced. The .pfx file and its password are not kept.
• When the certificate expires (Valid until), open the record, choose the new .pfx with its password and save.

Common problems

“You do not have permission to create, change or delete the AT credentials…”

• Symptom: Save opens Access Error: “You do not have permission to create, change or delete the AT credentials. Ask to be given “Edit” for this company and the Tax Authority portal in the credentials vault. Who grants it: a Fiscal administration user who already has the “Edit” permission on the vault, in Accounting › Configure › Credentials vault › Permissions. If nobody has “Edit” in this company yet, a Fiscal administration user starts the vault in Accounting › Configure › Credentials vault › Start the vault.” Seen when changing the credentials of another company in the demo, where the vault had not been started.
• Cause: you do not have Edit on the vault of the company you are working in.
• What to do: click Close and discard the change. If someone in the company already has Edit, ask them for the permission (Permissions). If nobody does, start the vault (steps 1 and 2) and try again.

“The vault of company … is already started…”

• Symptom: Confirm, in the Start the credentials vault window, opens Invalid Operation: “The vault of company Empresa Nova Exemplo, Lda is already started: Administração Fiscal (demonstração) can give permissions. Ask one of them.…”
• Cause: someone in the company already has Edit. The vault can only be started once.
• What to do: click Close and ask one of the people named in the message for the permission.

“The credentials are not ready: - The program certificate number is missing…”

• Symptom: Test the connection (simulator) shows, in the corner of the screen, “The credentials are not ready: - The program's certificate number at the Tax Authority is missing. Series and invoices must carry it.…”. In the Readiness, the Series and Invoices lines stay at Something is missing with the same sentence; the Transport guides line is Ready.
• Cause: the new company does not yet have the program certificate in Software certificates.
• What to do: Fiscal administration registers it in Accounting › Configure › Certified invoicing › Software certificates (outside the Administrator, the menu only appears in developer mode); the technical administrator also finds it in Settings › fiscaldoo · Certification, group Configure the certification: series and keys, line Software certificates. See How to prepare the company to issue certified documents. Then repeat step 9.

“The operation cannot be completed: This company already has credentials for this environment.”

• Symptom: Save opens Validation Error with this message.
• Cause: you clicked New for a company and environment that already have a record (in the demo, a second Test record for Empresa Nova Exemplo, Lda).
• What to do: click Close and discard the new record. Open the existing record in the list and replace what has changed there.

“The client certificate is not a valid PEM certificate…”

• Symptom: Save opens Validation Error: “The client certificate is not a valid PEM certificate. Paste the whole certificate, from "-----BEGIN CERTIFICATE-----" to "-----END CERTIFICATE-----".”
• Cause: instead of the .pfx, you pasted text into Client certificate (PEM) and that text is not a complete certificate (the first or last line is missing, or it is a different file).
• What to do: click Close and clear the field. Use the .pfx (step 6) or paste the whole certificate, with the lines “-----BEGIN CERTIFICATE-----” and “-----END CERTIFICATE-----”.

“The company has no tax number…”

• Symptom: the form warns “The company has no tax number, and the Tax Authority identifies who communicates by it. Fill it in on the company data.” and Test the connection (simulator) shows “The credentials are not ready: - The company has no tax number. The Tax Authority identifies who communicates by this number. Fill it in on the company data.”
• Cause: the company's form has no NIF.
• What to do: ask the administrator to fill in the company's NIF (How to fill in the company's tax data) and repeat step 9.

The Readiness still shows “Something is missing” after saving

• Cause: the credentials are for another environment (Test credentials do not cover the Production lines), for another company, or another piece of company data is missing.
• What to do: read the line's What is missing column and click Fix. Check the record's Environment and Company and the company selected in the top right corner.