INSTITUTO SUPERIOR DE ENGENHARIA DE COIMBRA

TRABALHO PRÁTICO – Nº 5

“Web services de assinatura de facturas promovido pela AMA: SAFE”

COMUNICAÇÕES INDUSTRIAIS E EMPRESARIAIS

Mestrado em Engenharia Electrotécnica
Ano Lectivo: 2023/2024

Mário Mendes Loureiro

Nº Estudante: 2021112398

Coimbra, 14 de Novembro de 2023

INTRODUÇÃO

O Serviço de Assinaturas de Facturas Electrónicas (SAFE) permite que o responsável de uma

empresa possa assinar facturas em formato electrónico, a partir de softwares de facturação integrados
com o este serviço. Esta assinatura é certificada pelo Estado Português.
O Decreto-Lei 28/2019 de 15 de Fevereiro e o Regulamento EU nº 910/2014 do Parlamento
Europeu e do Conselho, de 23 de julho de 2024 estipularam a necessidade de

1. PROCEDIMENTO E FLUXO DE PASSOS PARA ASSINAR FATURAS[1]

1.1. Processo de assinatura de PDF no portal autenticação.gov.pt

O procedimento para a assinatura de facturas de forma manual passa primeiro pela

autenticação do responsável da empresa no portal https://autenticacao.gov.pt, contado que este já
possua certificado para emitir este tipo de assinaturas.

Figura 1 – Portal autenticacao.gov.pt[1]

O portal autenticação.gov.pt permite aos clientes do SAFE comparar os documentos assinados

nas aplicações de assinatura de facturas com o documento assinado no portal. O procedimento para
assinar uma factura manualmente passa por aceder a “Assinatura de facturas > Assinatura de PDF” e
escolher o PDF da factura a assinar para upload, inserir o ID da credencial e o access token e clicar em
“Assinar” (figura 2).

Figura 2 - Processo de assinatura de facturas no portal autenticacao.gov.pt[1]

2
Depois do processo terminado, o portal permite fazer download do ficheiro assinado em formato PDF.
A assinatura tem validade jurídica e é certificada pelo Estado Português.

1.2. Processo de assinatura de PDF por via do software de facturação

Após a criação de conta de assinatura (que ilustramos na secção seguinte) o software de

facturação passa a comunicar apenas com o SAFE enviando o access token e o refreshtoken recebidos
no processo inicial. O processo de assinatura passa pelos seguintes métodos:
• crendentials/list para obtenção da credencial da conta de assinatura;
• credentials/info para obter informação sobre a conta de assinatura;
Depois o software invocar o método v2/credentials/authorize com a hash do documento a assinar e em
caso de sucesso deve devolver o código “HTTP 200”. Depois o método v2/signatures/signHash, devolve
apenas o código “HTTP 200” para que o software de de facturação possa gerar o ficheiro da factura
assinada, formado pelo documento original e pela hash assinada devolvida pelo SAFT. A AMA
recomenda que se utilizar software de facturação com Long-Term Validation (LTV) para reduzir o risco
de fraude.
No caso e erro retorna o código “HTTP 400”. Caso o cliente queira cancelar a conta de assinatura, o
software deve invocar o método signatureAccount/cancel.

Na página seguinte ilustra-se o processo de assinatura de facturas pelo software de facturação,

o FA e o SAFE.

3
Figura 3 - Esquema do processo de comunicação entre o sowftare de facturação, o FA e o SAFE
4
2. COMO REGISTAR UMA ENTIDADE (RESPONSÁVEL) [1,2]

2.1. Criação de conta no portal autenticação.gov.pt

2.1.1. Autenticação no portal autenticacao.gov.pt

O procedimento para a assinatura de facturas de forma manual passa primeiro pela

autenticação do responsável da empresa no portal https://autenticacao.gov.pt, por selecção do meio de
autenticação, cartão de cidadão ou chave móvel digital. O cidadão deve autorizar a recolha de dados
por parte do SCAP (Sistema de Certificação de Atributos Profissionais) e concluir o processo de
autenticação. Pressupõe-se que o cidadão em causa tem atributos de profissionais registados no SCAP.
O SCAP tem bases legais na Portaria 73/2018 que define as condições de utilização do SCAP
para certificar atributos profissionais, empresariais e públicos por meio de cartão de cidadão e/ou
chave móvel digital. Para isso, o cidadão deve ser portador dos conjuntos: chave móvel digita + PIN de
autenticação ou cartão de cidadão + pin de autenticação + leitor de cartões.

2.1.2. Processo de pedido de atributo no “Assinatura de Facturas Electrónicas” no SCAP

A conta de assinatura pode ser criada pelo software de facturação de forma preferencial ou
através do portal autenticação.gov.pt acedendo ao menu “assinatura de facturas > meus atributos
profissionais” e seleccionar a empresa em causa. No caso de o atributo não ter sido já configurado serve
solicitar-se o mesmo. Neste caso deve-se seleccionar o enquadramento jurídico do cidadão, se é
administrador, director, gerente ou procurador da empresa em causa. Inserir ainda o NIPC, nome da
empresa, número da certidão permanente, forma jurídica, entre outros documentos. Devemos por fim
configurar o prazo de validade da conta de assinatura e o número limite de facturas a realizar.

Figura 4 - Finalização do processo de requerimento de atributo de “Assinatura de Facturas Electrónicas”[1]

2.1.3. Processo de criação de uma conta de assinatura do SAFE pelo portal autenticação.gov.pt

Conforme indicamos da secção anterior, a conta de assinatura deve ser criada no software de
facturação, no entanto é possível criar a mesma pelo portal autenticação.gov.pt. Pelo processo manual
acedemos a “Os meus Atributos Profissionais > Assinatura de Facturas” e clica-se em “Adicionar
certificado”. Selecciona-se a empresa, a data de validade do certificado e emitir e o número limite de
assinaturas que se podem emitir com o certificado (figura 4). Confirma-se os dados e clica-se em
“Guardar”.

5
Figura 5 - Configuração do certificado de assinatura[1]

Após a confirmação o certificado deverá aparecer na lista de certificado associados ao cidadão conforme
se ilustra a título exemplificativo na figura 5.

Figura 6 - Certificado de assinatura activo[1]

Este certificado pode ser descarregado em forma de token pelo requerente (figura 6). Este token
consiste numa chave criptográfica. Explica-se no modo de criação de conta por software de facturação
como funciona a obtenção de token.

Figura 7 - Certificado de conta de assinatura de facturas em formato de token[1]

6
2.2. Criação de conta pelo software de facturação

2.2.1. Processo de registo no software de facturação[2,3]

O registo da criação de conta de assinatura de facturas pode ser efectuado por meio do software
de facturação de forma análoga ao registo no portal. No processo de criação de conta deve-se inserir os
seguintes dados aos quais se adicionou os requisitos dos mesmos para facilitar a programação da
plataforma:
• NIPC da empresa associada à conta – 9 dígitos;
• Informação adicional da empresa - máximo de 100 caracteres;
• Email associado à conta – obrigatório;
• Data de validade da conta de assinatura – opcional e no formato AAAA-MM-DD;
• Número máximo de assinaturas – obrigatório e no máximo 450000);
No entanto, qualquer pessoa poderia utilizar software de facturação para se autenticar,
bastando para isso ter as credenciais do responsável da empresa. No entanto, existe um mecanismo de
segurança autenticação.gov baseado no OAuth 2.0., que é um protocolo standard que gere a
autenticação de um utilizador e autoriza o acesso de aplicações externas à conta do mesmo, neste caso
o software de facturação. Para se efectuar a autenticação, o cidadão deve inserir os dados no software
de facturação, na área privada do mesmo. O portal deve redireccionar o utilizador para o portal
autenticação.gov com o pedido de autenticação acompanhado com assinatura digital. Depois o portal
afere o pedido de autenticação com pelos dados do cartão de cidadão e solicita a inserção do PIN.
Durante este tempo, o portal valida as credenciais com recurso ao cartão de cidadão e obtém os
atributos a partir do SCAP (figura 7).

Figura 8 - Mecanismo de autenticação autenticacao.gov[4]

2.2.2. Processo de autenticação de geração de token[3]

Após a recepção de dados, o FA mostra a página de autenticação no software de facturação, o

cidadão efectua a validação da autenticação com o cartão de cidadão e chave móvel digital, enviando a
página de autenticação os dados para o FA. Os dados são utilizados pelo FA para a obtenção de um
token.

Figura 9 - Processo de obtenção de token[3]

A obtenção de um token passa, primeiro por pedir ao site do FA os seguintes parâmetros de entrada:
• response_type com o valor token;
7
 • client_id com o identificador do sistema;
• redirect_uri com o url de redireccionamento para o sistema requerente;
• scope, uma lista de atributos com um espaço entre cada um deles derivados do documento de
identificação;
• authentication_level com o nível de segurança de operação, que é por norma o nível 3, pois o
nível 4 permite o acesso a todos os atributos do cartão de cidadão e deve ser aplicado apenas
com acesso presencial ao cartão de cidadão;
• default_selected_tab define uma opção de autenticação default que não deve ser alterada;
• hidden_tabs que são opções de autenticação escondidas ao utilizador;
• state que é o parâmetro de segurança do OAuth que quando estiver preenchido tem o mesmo
que está no redirect_uri para que o utilizador saiba que a resposta que obteve foi a resposta ao
pedido por si realizado.

O FA valida a autenticação e pede a criação de assinatura ao SAFE com os dados obtidos. Depois, o
FA utiliza a autenticação Implicit Grant para e devolve os seguintes atributos ao requerente:
• token_type com o valor Bearer;
• expires_in com um valor long que representa a validade do access token, que é reduzida e em
caso de expiração o SAFE retorna o erro “400: Bad request” e deverá ser feito um novo pedido;
• access_token é gerado pelo FA para ser utilizado no passo seguinte de obtenção dos atributos;
• state com o valor inserido no pedido inicial para que o software saiba que os atributos de
resposta coincidem com o pedido efectuado.
No caso do retorno de erro 400, deve existir a solicitação de actualização de um novo access token, com
recurso a um refresh token. Quando este for gerado, é devolvido um novo access token e um novo
refresh token. O processo ilustra-se na figura 9.

Figura 10 - Processo de actualização de tokens após erro 400[3]

Quando o sistema de facturação obtém o access token este envia-o para o API (Application
Programming Interface) do FA pelo método POST, enviando um objecto JSON (JavaScript Object
Notation) com os seguintes atributos:
• token com o valor do token obtido;
• attributesName com uma lista de strings opcional;
O esquema do processo de obtenção dos atributos é ilustrado na figura 10.

Figura 11 - Processo de obtenção dos atributos por parte do sistema requerente [3]

O sistema requerente recebe depois um objecto JSON com o token e o identificador do processo de
autenticação:

{"token": "a7ff26fb-392e-433b-94d6-c7182b5e7983",
"authenticationContextId": "b3e98d70-dc69-4e5b-bafa-184da35c0a13"}

Enquanto não o receber e o mesmo estiver a ser processado, no caso de se invocar os métodos do SAFE,
este retorna o erro “HTTP 401 Unauthorized”

8
Para obter estes atributos deve usar o parâmetro GET com o seguinte formato:
<FA-API URL>?token=<token>&authenticationContextId=<authenticationContextId>

Após o FA validar o token é devolvida a lista em JSON com os valores dos atributos obtidos, caso
algum venha devolvido do tipo null significa que não foi obtido em primeira instância. Caso isto
acontece o sistema repete o mesmo pedido a cada dois segundos, após sessenta segundos de tentativas
considera que não se consegue obter. No fim do processo, o software de facturação guarda esta
informação devolvida em objecto JSON e mostra uma mensagem de sucesso na criação de conta de
assinatura. Na figura seguinte ilustra-se de modo gráfico o processo descrito:

Figura 12 - Processo de criação de conta de assinatura[3]

A validade da conta de assinatura é o valor mais pequeno entre a validade definida pelo cidadão, a
validade do atributo “Assinatura de facturas electrónicas” do SCAP e a validade máxima da conta no
SAFE (45 dias). No fundo, quando um dos atributos de data expirar, a conta também expira.

3. ESPECIFICAÇÃO DOS WEB SERVICES[2]

3.2. Arquitectura, requisitos e funcionamento do sistema de assinatura de facturas electrónicas

Os webservices associados ao SAFE (Serviço de Assinatura de Facturas Electrónicas) necessitam

de corresponder a especificações técnicas definidas pela Agência para a Modernização da
Administração. Para explicar essas especificações obrigatórias por lei começamos por definir o SAFE e
explicitar o seu funcionamento.
O SAFE funciona com base no ecossistema autenticação.gov.pt. Este ecossistema contém o SAFE,
o Fornecedor de Autenticação (FA) e no Sistema de Certificação de Atributos Profissionais (SCAP),
como se ilustra na figura 12. O Fornecedor de Autenticação (FA) é o sistema responsável por proceder
à autenticação dos cidadãos com base na sua identificação ou chave móvel digital. Após esse processo,
o FA comunica esses dados ao SAFE, sob autorização do cidadão.

9
Figura 13 - Ecossistema autenticacao.gov[2]

O Sistema de Certificação de Atributos Profissionais (SCAP) comunica ao SAFE se o cidadão com esses
dados apresenta o atributo para assinatura de facturas electrónicas, quando esse lhe transmite os
dados. Se o atributo estiver atribuído, o SAFE finaliza o processo de criação de conta de assinaturas
electrónicas. O software de facturação comunica com ecossistema autenticação.gov para assinar
facturas, a partir do SAFE, e para transmitir os dados para criação de conta de assinatura, pelo FA.
Conforme explicitamos na secção anterior, a criação de conta por ser feito tanto pelo software de
facturação como pelo portal autenticação.gov.pt que comunica com o FA. A AMA define que este
software de facturação deve estar integrado com o SAFE e o FA e obter aprovação no processo de
integração e credenciação. A empresa deve ter consigo os documentos necessários especificados na
secção anterior e o atributo requerido em estado activo.

Em termos de protocolos, os dados trocados pelo ecossistema autenticação.gov e o software de

facturação/ entidade deve ser baseado em SAMLv2.0 (Security Assertion Markup Language) para que
a autenticidade e integridade de todas as transacções seja assegurada. A comunicação estabelece-se
por HTTP em canal cifrado com SSL/TSL sobre internet (figura 14).

Figura 14 - Processo de autenticação[2]

Na imagem seguinte mostramos um exemplo de um pedido de autenticação proveniente da

entidade requerente:

10
Figura 15 - Solicitação de autenticação[3]

4. EMPRESAS QUE FORNECEM O SERVIÇO INTERMÉDIO PARA A ASSINATURA DE

FATURAS

Existem, em Portugal diverso fabricante de software de facturação interligado com o SAFE. Na

lista abaixo ilustram-se alguns softwares:
• PHC Software
• Sage Software
• Primavera Software
• XD Software

As principais vantagens de adquirir um sistema deste tipo são:

• Existência de equipa de suporte técnico à distância;
• Soluções de software adaptáveis ao perfil da empresa;
• Soluções e interligação com vários departamentos da empresa;

Existem ainda sistemas de facturação open source como, por exemplo o Invoice Express e o OpenERR
que pode ser certificado pelo cliente que pretende utilizar este sistema junto da AMA.

11
BIBLIOGRAFIA

1. Agência para a Modernização Administrativa I.P. (2021). Serviço de Assinatura de Faturas

Eletrónicas Guia de Fluxos Complementares Versão 1.1.

2. Agência para a Modernização Administrativa I.P. (2022). Serviço de Assinatura de Faturas

Eletrónicas Documento de Integração Versão 2.0.

3. Agência para a Modernização Administrativa I.P. (sem data). Guia rápido de utilização do OAuth2

do FA.

4. Agência para a Modernização Administrativa I.P. (2022). AUTENTICAÇÃO.GOV Serviço de

autenticação da Administração Pública Portuguesa—Versão 1.5.9.

ÍNDICE

INTRODUÇÃO............................................................................................................................................ 2
1. PROCEDIMENTO E FLUXO DE PASSOS PARA ASSINAR FATURAS[1] ....................................... 2
1.1. Processo de assinatura de PDF no portal autenticação.gov.pt .................................................... 2
1.2. Processo de assinatura de PDF por via do software de facturação.............................................. 3
2. COMO REGISTAR UMA ENTIDADE (RESPONSÁVEL)[1,2] ......................................................... 5
2.1. Criação de conta no portal autenticação.gov.pt............................................................................ 5
2.1.1. Autenticação no portal autenticacao.gov.pt .......................................................................... 5
2.1.2. Processo de pedido de atributo no “Assinatura de Facturas Electrónicas” no SCAP .............. 5
2.1.3. Processo de criação de uma conta de assinatura do SAFE pelo portal autenticação.gov.pt ... 5
2.2. Criação de conta pelo software de facturação .............................................................................. 7
2.2.1. Processo de registo no software de facturação[2,3] ..................................................................... 7
2.2.2. Processo de autenticação de geração de token[3] ....................................................................... 7
3. ESPECIFICAÇÃO DOS WEB SERVICES[2] ....................................................................................... 9
3.2. Arquitectura, requisitos e funcionamento do sistema de assinatura de facturas electrónicas ... 9
4. EMPRESAS QUE FORNECEM O SERVIÇO INTERMÉDIO PARA A ASSINATURA DE
FATURAS.................................................................................................................................................. 11
BIBLIOGRAFIA ........................................................................................................................................ 12
ÍNDICE ..................................................................................................................................................... 12

12