# CryptoSAF-T ## Sumário O [**Decreto Lei n.º 48/2020 de 3 de agosto**](https://data.dre.pt/eli/dec-lei/48/2020/08/03/p/dre) estabelece a obrigação de **encriptação** do ficheiro [**SAF-T (PT)**](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/SAFT_PT/Paginas/news-saf-t-pt.aspx) para o efeito da entrega da IES/DA, bem como os respetivos procedimentos a adotar. > Na sequência desta alteração, a [Lei n.º 119/2019](https://dre.pt/web/guest/pesquisa/-/search/124793094/details/normal?l=1), de 18 de setembro, veio alterar o n.º 6 do artigo 2.º do [Decreto-Lei n.º 8/2007](https://dre.pt/web/guest/pesquisa/-/search/522813/details/normal?l=1), de 17 de janeiro, que passou a prever que devem ser excluídos, previamente à submissão, os campos de dados do ficheiro SAF-T (PT), relativo à contabilidade, que sejam considerados de menor relevância ou de desproporcionalidade face ao âmbito e objeto do referido decreto-lei, designadamente dados que possam pôr em causa deveres de sigilo a que, legal ou contratualmente, os sujeitos passivos se encontrem obrigados. As aplicações de software de gestão são obrigadas a cumprir com as disposições deste diploma, designadamente, a criar **um ficheiro SAF-T (PT) descaracterizado**, através da encriptação do subconjunto de [**elementos**](/informacao-tecnica/cryptosaf-t/elementos) que constam do referido diploma. ## Índice de conteúdos deste repositório * [CryptoSAF-T](/) (esta página) * [Conceito](/conceito) * [Obrigações](/obrigacoes) ### Informação Técnica * [SAF-T (PT)](/informacao-tecnica/saf-t-pt) * [Checksum](/informacao-tecnica/saf-t-pt/checksum) * [CryptoSAF-T](/informacao-tecnica/cryptosaf-t) * [Elementos](/informacao-tecnica/cryptosaf-t/elementos) * [Mecanismo de cifra](/informacao-tecnica/cryptosaf-t/mecanismo) * [INCM](/informacao-tecnica/incm) * [Pedido de chave](/informacao-tecnica/incm/pedido-de-chave) * [Chave simétrica](/informacao-tecnica/incm/chave-simetrica) * [Webservice](/informacao-tecnica/incm/webservice) * [Testar Webservice](/informacao-tecnica/incm/testar-webservice) ### Ferramentas * [SAF-T: Utils](/ferramentas/cryptosaf-t-utils) ### Outra informação * [Mantenha-se em contacto](/outra-informacao/mantenha-se-em-contacto) ## Ajuda Use a secção de [**issues**](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/issues) para consultar, colocar questões ou sugerir alterações à documentação. ## Contributos Temos muito gosto em contar com a sua colaboração neste projeto. Faça Fork deste [**repositório**](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/) e envie o seus [**pull requests**](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/pulls)! ## Licença Este projeto está licenciado nos termos [MIT License](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/blob/master/LICENSE). # Conceito O CryptoSAF-T, designação dada pela comunidade, consiste no ficheiro SAF-T (PT) em parte dos elementos são descaracterizados. São [**elementos**](/informacao-tecnica/cryptosaf-t/elementos) que, ao serem tratados sem quaisquer medidas de proteção, podem expor e colocar em causa a segurança e a privacidade dos contribuintes, bem como daqueles que têm relações comerciais com esses. ## Em que consiste * Um conjunto [elementos](/informacao-tecnica/cryptosaf-t/elementos) que compõem o ficheiro SAF-T (PT) de contabilidade passam a ser encriptados. * O CryptoSAF-T só tem efeitos práticos para entrega da IES/DA. * O processo de encriptação tem por base o algoritmo de cifra [AES-128-CTR](/informacao-tecnica/incm/chave-simetrica#aes-128-ctr) que retira partido do uso de uma [**chave simétrica**](/informacao-tecnica/incm/chave-simetrica). * [Imprensa Nacional Casa da Moeda (INCM)](https://www.incm.pt/) intervém no processo através do serviço de geração e armazenamento seguro das chaves. * Existe apenas uma chave simétrica por contribuinte e por ano, respeitante a cada exercício para qual é submetida a IES. # Obrigações Para o efeito da submissão da IES/DA os contribuintes passam a ter que usar o CryptoSAF-T. Essa obrigação reverte-se igualmente nas aplicações de gestão de contabilidade, que passam a ter que o suportar. ## Aspetos chave do CryptoSAF-T * Ficheiros SAF-T (PT) têm que obedecer **integralmente às regras de estrutura** do ficheiro previstas na [Portaria n.º 321-A/2007](https://dre.pt/web/guest/pesquisa/-/search/664305/details/normal?l=1), de 26 de março, na sua redação [atual](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/SAFT_PT/Paginas/news-saf-t-pt.aspx). * É necessário obter uma **soma de verificação (**[**checksum**](/informacao-tecnica/saf-t-pt/checksum)**)** do ficheiro SAF-T (PT) original antes da encriptação dos elementos. * O checksum é enviado em conjunto com o CryptoSAF-T no momento da submissão da IES/DA. * A encriptação dos [**elementos**](/informacao-tecnica/cryptosaf-t/elementos) do SAF-T (PT) ocorre com sucesso se assegurada a reversão do processo usando a mesma chave [simétrica](/conceito#o-que-vai-acontecer), através da qual se obtém o ficheiro original, **estruturalmente sem erros**. * O checksum é usado para validar que o ficheiro baseado no CryptoSAF-T que é submetido para o efeito da entrega da IES/DA é igual ao original. ## Segurança da chave simétrica O [Decreto-Lei Decreto-Lei n.º 48/2020 de 3 de agosto](https://data.dre.pt/eli/dec-lei/48/2020/08/03/p/dre) estabelece na alínea b) do Artigo 3.º que a chave simétrica tem de ser mantida em sigilo **e não pode ser usada para a encriptação de outro ficheiro relativo o outro exercício ou outro contribuinte (NIF), como uma obrigação do fabricante de software**. A interpretação à letra da legislação pode dar a entender que será necessário um mecanismo de custódia da chave simétrica pelo software. Não é isso que se pede. A responsabilidade da segurança da chave é em primeira instância do contribuinte para quem foi emitida. Porém, nada impede que o software possa dispor de mecanismos de custódia e de gestão das chaves dos contribuintes. ### Sobre este aspeto é portanto necessário * Usar a chave de forma segura nas comunicações com os serviços em que esta é requerida. * Garantir que é usada a chave correta para a encriptação do ficheiro do contribuinte. * Garantir que a chave não é usada para encriptar outro ficheiro do mesmo contribuinte relativo a outro exercício ou outro ficheiro de um contribuinte diferente. * Garantir que a chave não é usada para outro fim que não aquele que está estabelecido na legislação. # SAF-T (PT) ## Estrutura do SAF-T (PT) de contabilidade A estrutura encontra-se regulada pela Portaria 302/2016 de 2 de dezembro ( [**PT**](https://info.portaldasfinancas.gov.pt/pt/informacao_fiscal/legislacao/diplomas_legislativos/Documents/Portaria_302_2016.pdf) | [**EN**](https://info.portaldasfinancas.gov.pt/pt/docs/Portug_tax_system/Documents/Ordinance_No_302_2016_of_the_2nd_December.pdf) ) e o respetivo schema XSD pode ser descarregado [**aqui**](https://info.portaldasfinancas.gov.pt/apps/saft-pt04/saftpt1.04_01.xsd). {% hint style="info" %} Para mais informação pode aceder à área destinada ao SAF-T (PT) no [Portal das Finanças](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/SAFT_PT/Paginas/news-saf-t-pt.aspx). {% endhint %} | Índice | Elemento | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1. | Cabeçalho (Header) | | 2.1. | Tabela de código de contas ([GeneralLedgerAccounts](/informacao-tecnica/cryptosaf-t/elementos#2-1-tabela-de-codigos-de-contas-generalledgeraccounts)) | | 2.2. | Tabela de clientes ([Customer](/informacao-tecnica/cryptosaf-t/elementos#2-2-tabela-de-clientes-customer)) | | 2.3. | Tabela de fornecedores ([Supplier](/informacao-tecnica/cryptosaf-t/elementos#2-3-tabela-de-fornecedores-supplier)) | | 2.5. | Tabela de impostos ([TaxTable](/informacao-tecnica/cryptosaf-t/elementos#2-5-tabela-de-impostos-taxtable)) | | 3. | Movimentos contabilísticos ([GeneralLedgerEntries](/informacao-tecnica/cryptosaf-t/elementos#3-tabela-de-movimentos-contabilisticos-generalledgerentries)) | | 4.4. | Documentos de recibos emitidos ([Payments](/informacao-tecnica/cryptosaf-t/elementos#4-4-tabela-de-documentos-de-recibos-emitidos-payments)) | # Checksum ## Algoritmo SHA-256 ## Descrição O algoritmo de checksum `SHA256` permite calcular o hash de um determinado ficheiro ou de um bloco de informação. Neste caso, o checksum é usado para validar que um ficheiro SAF-T (PT) é igual ao ficheiro original, após ter sido desencriptado. ![Processo de criação de checksum do SAF-T (PT)](/files/-MTkfCnmqYu-EA12oXN1) ## Canonização O cálculo do [**checksum**](/informacao-tecnica/saf-t-pt/checksum) do ficheiro deve ser antecedido da sua canonização (Canonical XML \[[XML-C14N](https://www.w3.org/TR/xml-exc-c14n/#ref-XML-C14N)]). Este é um processo que tem por objetivo remover a informação desnecessária e que possa estar a mais no `XML` e que vai garantir que o hash diz respeito exclusivamente ao conteúdo do ficheiro. {% hint style="danger" %} Este passo é particularmente importante na medida [**em que vai ser usado pela AT**](/informacao-tecnica/incm/pedido-de-chave#fase-3---acesso-pela-at-ao-ficheiro-original) nos casos em que se proceda à desencriptação de ficheiros CryptoSAF-T que estejam em sua posse. {% endhint %} ## Algoritmo de canonização * Canonização seguido de resumo (checksum) ### Método * [Canonical XML Version 1.1](https://www.w3.org/TR/xml-c14n11/) ### Parâmetros * sem comentários e não-exclusivo ## Algumas ferramentas * .NET [XmlDsigExcC14NTransform Class](https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.xml.xmldsigexcc14ntransform?view=dotnet-plat-ext-3.1) * Windows / Linux / Unix: [libxml2](https://www.aleksey.com/xmlsec/c14n.html) * JAVA: [XOM](https://github.com/elharo/xom/), [Santuario Class Canonicalizer](http://santuario.apache.org/Java/api/org/apache/xml/security/c14n/Canonicalizer.html) {% hint style="info" %} Consulte o repositório [**CryptoSAF-T: SAF-T Utils**](https://github.com/assoft-portugal/CryptoSAF-T-SAF-T-Utils) onde pode verificar e testar os métodos de canonização e encriptação do XML. {% endhint %} # CryptoSAF-T ## Aspetos chave do CryptoSAF-T * Ficheiros SAF-T (PT) têm que obedecer **integralmente às regras de estrutura** do ficheiro previstas na [Portaria n.º 321-A/2007](https://dre.pt/web/guest/pesquisa/-/search/664305/details/normal?l=1), de 26 de março, na sua redação [atual](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/SAFT_PT/Paginas/news-saf-t-pt.aspx). * É necessário obter uma **soma de verificação (**[**checksum**](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/tree/2da229614b164df4da078ea9f3a571bb84dc2344/informacao-tecnica/cryptosaf-t/informacao-tecnica/saf-t-pt/checksum.md)**)** do ficheiro SAF-T (PT) original antes da encriptação dos elementos. * O checksum é enviado em conjunto com o CryptoSAF-T no momento da submissão da IES/DA. * A encriptação dos [**elementos**](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/tree/2da229614b164df4da078ea9f3a571bb84dc2344/informacao-tecnica/cryptosaf-t/informacao-tecnica/cryptosaf-t/elementos.md) do SAF-T (PT) ocorre com sucesso se assegurada a reversão do processo usando a mesma chave [simétrica](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/tree/2da229614b164df4da078ea9f3a571bb84dc2344/informacao-tecnica/cryptosaf-t/conceito.md#o-que-vai-acontecer), através da qual se obtém o ficheiro original, **estruturalmente sem erros**. * O checksum é usado para validar que o ficheiro baseado no CryptoSAF-T que é submetido para o efeito da entrega da IES/DA é igual ao original. # Elementos Nesta página encontra as listas de elementos da cada uma das tabelas que têm de ser encriptados para o efeito da criação do CryptoSAF-T. ## \[2.1.] Tabela de códigos de contas (GeneralLedgerAccounts) | Índice | Elemento | | -------- | --------------------------------------- | | 2.1.2.2. | Descrição da conta (AccountDescription) | ## \[2.2.] Tabela de clientes (Customer) | Índice | Elemento | | -------- | --------------------------------------------------------- | | 2.2.3. | Número de identificação fiscal do cliente (CustomerTaxID) | | 2.2.4. | Nome da empresa (CompanyName) | | 2.2.5. | Nome do contacto na empresa (Contact) | | 2.2.6.1. | Número de polícia (BuildingNumber) | | 2.2.6.2. | Nome da rua (StreetName) | | 2.2.6.3. | Morada detalhada (AddressDetail) | | 2.2.6.4. | Localidade (City) | | 2.2.6.5. | Código postal (PostalCode) | | 2.2.6.6. | Distrito (Region) | | 2.2.6.7. | País (Country) | | 2.2.7.1. | Número de polícia (BuildingNumber) | | 2.2.7.2. | Nome da rua (StreetName) | | 2.2.7.3. | Morada detalhada (AddressDetail) | | 2.2.7.4. | Localidade (City) | | 2.2.7.5. | Código postal (PostalCode) | | 2.2.7.6. | Distrito (Region) | | 2.2.7.7. | País (Country) | | 2.2.8. | Telefone (Telephone) | | 2.2.9. | Fax (Fax) | | 2.2.10. | Endereço de correio eletrónico da empresa (Email) | | 2.2.11. | Endereço do sítio Web da empresa (Website) | ## \[2.3.] Tabela de fornecedores (Supplier) | Índice | Elemento | | -------- | ------------------------------------------------------------ | | 2.3.3. | Número de identificação fiscal do fornecedor (SupplierTaxID) | | 2.3.4. | Nome da empresa (CompanyName) | | 2.3.5. | Nome do contacto na empresa (Contact) | | 2.3.6.1. | Número de polícia (BuildingNumber) | | 2.3.6.2. | Nome da rua (StreetName) | | 2.3.6.3. | Morada detalhada (AddressDetail) | | 2.3.6.4. | Localidade (City) | | 2.3.6.5. | Código postal (PostalCode) | | 2.3.6.6. | Distrito (Region) | | 2.3.6.7. | País (Country) | | 2.3.7.1. | Número de polícia (BuildingNumber) | | 2.3.7.2. | Nome da rua (StreetName) | | 2.3.7.3. | Morada detalhada (AddressDetail) | | 2.3.7.4. | Localidade (City) | | 2.3.7.5. | Código postal (PostalCode) | | 2.3.7.6. | Distrito (Region) | | 2.3.7.7. | País (Country) | | 2.3.8. | Telefone (Telephone) | | 2.3.9. | Fax (Fax) | | 2.3.10. | Endereço de correio eletrónico da empresa (Email) | | 2.3.11. | Endereço do sítio Web da empresa (Website) | ## \[2.5.] Tabela de impostos (TaxTable) | Índice | Elemento | | -------- | ---------------------------------- | | 2.5.1.4. | Descrição do imposto (Description) | ## \[3.] Tabela de Movimentos contabilísticos (GeneralLedgerEntries) | Índice | Elemento | | ------------- | -------------------------------------------------------- | | 3.4.2. | Descrição do diário (Description) | | 3.4.3.4. | Código do utilizador que registou o movimento (SourceID) | | 3.4.3.5. | Descrição do movimento (Description) | | 3.4.3.11.1.5. | Descrição da linha de documento (Description) | | 3.4.3.11.2.5. | Descrição da linha de documento (Description) | ## \[4.4.] Tabela de Documentos de recibos emitidos (Payments) | Índice | Elemento | | ------------- | ------------------------------------ | | 4.4.4.7. | Descrição do pagamento (Description) | | 4.4.4.9.4. | Código do utilizador (SourceID) | | 4.4.4.11. | Código do utilizador (SourceID) | | 4.4.4.14.2.3. | Descrição da linha (Description) | # Mecanismo de cifra A encriptação dos [**elementos**](/informacao-tecnica/cryptosaf-t/elementos) tem por base o algoritmo de cifra aes-128-ctr que retira partido do uso de uma **chave simétrica**. ## Parâmetros da cifra **Algoritmo de Cifra**: Advanced Encryption Standard (AES) – FIPS 197\ **Modo de Operação**: Counter (CTR) – NIST Special Publication 800-38A\ **Chave De Cifra**: Aleatória de 128 bits\ **Vetor de Inicialização(IV)/Counter**: Aleatória de 128 bits ## CryptoSAF-T e IES/DA ![Criação e envio de CryptoSAF-T](/files/-MTkfCz_ipTreMe_Z5ZF) ### Descrição do processo O ERP de Contabilidade tem de criar **dois ficheiros**: (1) o `SAF-T (PT)` de Contabilidade para efeitos de entrega da IES/DA e (2) o `CryptoSAF-T` a partir do ficheiro anterior. O CryptoSAF-T tem por base a encriptação da lista de [**elementos**](/informacao-tecnica/cryptosaf-t/elementos) referidos na legislação através do algoritmo de chave simétrica `aes-128-ctr`. {% hint style="danger" %} Para garantir a autenticidade do ficheiro original é necessário calcular o seu [**checksum**](/informacao-tecnica/saf-t-pt/checksum). No entanto, o CryptoSAF-T **deve ser criado a partir do ficheiro original** e não a partir do ficheiro canonizado. {% endhint %} {% content-ref url="/pages/-MLOJMMzzhLVlF\_l-hw\_" %} [SAF-T: Utils](/ferramentas/cryptosaf-t-utils) {% endcontent-ref %} Uma vez concluídos todos estes procedimentos o utilizador estará em condições de submeter o ficheiro para efeitos do pré-preenchimento da IES/DA. O envio destes elementos é da competência exclusiva do contabilista da empresa. # INCM A INCM é responsável pela disponibilização e manutenção do serviço de geração e armazenamento de chaves. Estas chaves são guardadas pelo período de conservação estabelecido do decreto, de 15 anos. No regulamento da INCM (ainda por publicar) constam os termos de adesão ao serviço, bem como as regras técnicas para a sua utilização. Nesta secção encontra informação sobre o método de obtenção da chave e o IV usados para encriptar o SAF-T (PT). {% hint style="info" %} Encontra mais informação sobre o serviço de CryptoSAFT da INCM em e através da linha de apoio pelo email . {% endhint %} # Pedido de chave Em baixo apresentam-se um conjunto de diagramas que permitem perceber cada uma das fases do processo, desde o pedido inicial da chave até à submissão da IES/DA. {% hint style="danger" %} Para a realização dos testes iniciais é necessário solicitar à INCM a criação de caixas de teste no serviço viaCTT. As entidades que pretendam participar podem fazê-lo através da [linha de apoio](/informacao-tecnica/incm). {% endhint %} ## Fase 1 - Pedido de geração de chave ![Fase 1 - Pedido de geração de chave](/files/-MDwCrl4D8KPxMn-qLo_) ### Descrição O início do processo tem origem na invocação de um `webservice` da INCM. Nesta fase é feito um pedido geração de chave simétrica e para o qual são requeridos os parâmetros `NIF` e `Ano` a que respeita a declaração da IES/DA. A chave tem que ser autenticada pelo contribuinte, pelo que na segunda fase do pedido este tem que inserir o código que recebeu viaCTT. Apesar de não ser necessário nenhum pré-registo para se conseguir obter o código de segurança que permite o levantamento da chave criptográfica, é necessário que o sujeito passivo tenha a sua conta criada e ativa na Caixa Postal ViaCTT. ## Fase 2 - Pedido de chave ![Fase 2 - Pedido de chave](/files/-MDwCrl5rwtQm3b3ca_T) ### Descrição A segunda fase do processo visa obter a chave simétrica para encriptação dos [**elementos**](/informacao-tecnica/cryptosaf-t/elementos) do SAF-T (PT). Nesta fase, já na posse do código de autenticação, estabelece-se uma nova ligação com o `webservice` onde se inserem os parâmetros `NIF`, `Ano` a que respeita a declaração da IES/DA e `código` recebido através de viaCTT. ## Fase 3 - Acesso pela AT ao ficheiro original ![Fase 4 - Acesso pela AT ao ficheiro original](/files/-MDwCrl7Z0YHPLE3mCRZ) ### Descrição A Autoridade Tributária e Aduaneira mantém os ficheiros CryptoSAF-T em sua posse pelo período de 15 anos a contar da data da sua submissão. Esses ficheiros podem ser usados no âmbito de eventuais procedimentos inspetivos tal e qual como descrito no Artigo 6.º do [**Decreto-Lei Decreto-Lei n.º 48/2020 de 3 de agosto**](https://data.dre.pt/eli/dec-lei/48/2020/08/03/p/dre). Uma vez que a custódia das chaves compete à INCM, sempre que a AT necessitar de desencriptar um ficheiro CryptoSAF-T terá que invocar o `webservice`. Dessa ação resultará a informação ao Contribuinte de que a sua chave foi requerida pela AT, que lhe será comunicada através do serviço viaCTT. # Chave simétrica A INCM é responsável pela disponibilização e manutenção do serviço de geração e armazenamento de chaves. Estas chaves são guardadas pelo período de conservação estabelecido do decreto, de 15 anos. No regulamento da INCM (ainda por publicar) constam os termos de adesão ao serviço, bem como as regras técnicas para a sua utilização. ## AES Consiste numa cifra de blocos que foi especificada pelo NIST em 2001. É conhecida por ser uma cifra de alta performance e baixa memória tendo implementações em todas as principais linguagens de programação e ferramentas (Java, C++, C#, OpenSSL) Não se conhecem ataques práticos a esta cifra principalmente quando são usadas com chaves de 128 bits ou superior. ### AES-128-CTR No modo CTR os blocos cifrados não dependem do anterior mas sim de um contador que é incrementado a cada bloco. Este modo de operação faz com que para valores de entrada idênticos não sejam obtidos resultados idênticos, que poderiam levar a uma fácil identificação do conteúdo. ## Pedido de chave simétrica 1. O pedido de chaves é efetuado pelas aplicações através da invocação de um `webservice` fornecido pela INCM. 2. No processo de invocação é necessário informar: - `NIF` do Contribuinte - `Ano` a que respeita a declaração da IES/DA 3. Posteriormente, a INCM envia a senha de autenticação para o endereço viaCTT do contribuinte. Este, terá que a fornecer à aplicação de contabilidade. 4. A aplicação invoca de novo o `webservice` da INCM, mas, nesta fase, indicando o `NIF`, o `Ano` e a `senha do contribuinte`, para obter, finalmente, a chave simétrica. > ### Este processo pode ser repetido, permitindo recuperar a chave caso seja necessário. Consulte a página de [**Pedido de chave**](/informacao-tecnica/incm/pedido-de-chave) para saber mais acerca deste processo. # Webservice ## **Descrição** O pedido da chave e do respetivo IV pode ser feito através de webservice cujas especificações assentam num WSDL standard. Nesta página encontra os métodos que o webservice disponibiliza para todos os utilizadores. Este webservice estará (quando for lançado) exposto ao publico sem qualquer autenticação e permitirá invocar as operações de pedido e levantamento de chave. {% file src="/files/-MKAWFJZWGmXZG5xhumP" %} public.wdsl (testes) {% endfile %} {% file src="/files/-MSpHnNcwQtYXvmVHjpR" %} Manual de Integração CryptoSAFT {% endfile %} ## Pedido de Chave (KeyRequest) Serviço de pedido de chave que associa uma chave a um par `Ano fiscal/NIF` e despoleta o envio de uma notificação ViaCTT para o contribuinte com o respetivo código de levantamento. ### Parâmetros de entrada * `KeyRequest.FiscalYear` (Obrigatório, Valor numérico entre 2020 e 9999) - Ano fiscal a que se refere o pedido de chave * `KeyRequest.VatNumber` (Obrigatório, Valor numérico entre 100000000 e 999999999) - Número de identificação fiscal a que se refere o pedido de chave ### Parâmetros de saída * `KeyRequestResponse.Response` (Obrigatório) - Ver Response mais abaixo ## Levantamento de Chave (KeyRetrieve) Serviço de pedido de levantamento de chave que devolve a chave associada a um par `Ano fiscal/NIF`, validando o código de autenticação. ### Parâmetros de entrada * `KeyRetrieve.FiscalYear` (Obrigatório, Valor numérico entre 2020 e 9999) - Ano fiscal a que se refere o levantamento de chave * `KeyRetrieve.VatNumber` (Obrigatório, Valor numérico entre 100000000 e 999999999) - Número de identificação fiscal a que se refere o levantamento de chave * `KeyRetrieve.RetrieveCode` (Obrigatório, Valor alfanumérico com tamanho 10) - Código de levantamento enviado ao contribuinte pelo ViaCTT. ### Parâmetros de saída * `KeyRetrieveResponse.Key` - (Opcional) Chave produzida pelo serviço correspondente ao Ano Fiscal/Nif (Base64) * `KeyRetrieveResponse.IV` - (Opcional) Vector de inicialização (IV) produzida pelo serviço correspondente ao Ano Fiscal/Nif (Base64) * `KeyRetrieveResponse.Response` (Obrigatório) - Ver Response mais abaixo ### Response * `Response.ResponseCode` (Obrigatório, Valor numérico) - Código de resposta que indica o sucesso ou erro da mesma (ver tabela de Códigos de erro) * `Response.Error` (Opcional, Valor alfanumérico) - Breve descrição do erro ## Códigos de erro | ResponseCode | Descrição | | ------------ | ------------------------------- | | 0 | Sucesso | | 1 | Ano fiscal inválido | | 2 | NIF inválido | | 3 | Código de levantamento inválido | | 4 | Ano fiscal/NIF bloqueado | | 5 | Aviso - Canal ViaCTT não ativo | ## Ambientes Existem dois ambientes de funcionamento do serviço disponíveis: produção e testes. O ambiente de teste destina-se a fornecer um meio para o desenvolvimento da integração de aplicações de descaracterização. É de acesso exclusivo a fabricantes de aplicações que desenvolvam este tipo de aplicações. Durante o processo de integração é necessário o acesso a uma conta no ambiente de testes do ViaCTT, sendo recomendável [**contactar a linha de apoio**](mailto:cryptosaft@incm.pt) previamente ao início do processo de integração. ### Endereços dos ambientes | Ambiente | Tipo | Endereço | | -------- | ------- | --------------------------------------------------------- | | Produção | Serviço | | | | WDSL | | | Testes | Serviço | | | | WDSL | | # Testar Webservice Existem inúmeras ferramentas que possibilitam a integração com Webservices SOAP. A generalidade das tecnologias de desenvolvimento tem suporte de integração com webservices de forma nativa ou através de integração com outros serviços. Estas são algumas das ferramentas disponíveis: * [SoapUI (windows, linux, mac)](https://www.soapui.org/) * [Microsoft Visual Studio](https://docs.microsoft.com/en-us/visualstudio/test/how-to-create-a-web-service-test?view=vs-2019#to-create-a-simple-web-service) * [Postman](https://learning.postman.com/docs/sending-requests/supported-api-frameworks/making-soap-requests/) * [Zeep: Python SOAP Client](https://docs.python-zeep.org/en/master/) * [JAVA JAX-WS](https://javaee.github.io/metro-jax-ws/) * [PHP](https://www.php.net/manual/en/book.soap.php) ## Testar com o SoapUI Neste exemplo vamos demonstrar como realizar o teste com o webservice da INCM usando o SoapUI. {% hint style="info" %} O SoapUI é uma ferramenta open source para testes de API. É uma ferramenta amplamente usada por *developers*, *testers* e utilizadores finais, com suporte para a generalidade dos testes funcionais de Serviços Web SOAP e API REST. Para além dos testes funcionais o SoapUI também permite tarefas de análise, testes de segurança, de virtualização e de *mocking*. {% endhint %} ### Criar Projeto SOAP a partir de um WSDL 1. No SoapUI crie um novo projeto através da menu **File > New SOAP Project** ![Criar Projeto SOAP a partir de um WSDL](/files/-MRaPSd6195ck7x0KH2c)
2. Dê um **Nome** ao projeto e coloque seguinte URL no campo Initial URL: ``` https://keys-tst.cryptosaft.incm.pt/service/public?wsdl ``` 3. Pode deixar as restantes opções tal e qual como estão por defeito e clique em **OK**. O SoapUI tratará de gerar o serviço e um conjunto de testes de simulação opcionais. ### Trabalhar com WSDL no SoapUI {% hint style="info" %} WSDL ou *Web Service Description Language* consiste numa linguagem baseada na definição de XML. É usada para descrever as funcionalidades do serviço SOAP podendo comparar-se com um schema de XML, embora para fins distintos. Os ficheiros WSDL são fundamentais para testar e usar corretamente webservices baseados em SOAP. Para saber mais pode visitar [**esta página**](https://www.w3.org/TR/2001/NOTE-wsdl-20010315). {% endhint %} Após a criação do projeto, as ligações do serviço serão carregadas no SoapUI. ![Ligações do serviço CryptoSAF-T](/files/-MRaPSd7Wvn2M_JFH2sG) ### Operações O serviço de WSDL apresenta duas operações, `KeyRequestOperation` e `KeyRetrieveOperation`. Ambas com suporte às funções de pedido e de resposta a mensagens. ### Pedidos Os pedidos são apresentados sob a forma de nós das operações. No SoapUI podem ser adicionados quantos pedidos quantos os necessários, mas, por defeito são sempre criados pedidos de exemplo. ### KeyRequestOperation Para realizar este pedido, preencha os valores correspondentes a `FiscalYear` e `VatNumber` e clique em ![Run](/files/-MRaPSd81Go7IQjlO0DD). ![KeyRequestOperation](/files/-MRaPSd9wYu0FhR36mAJ) A resposta a este pedido desencaderá o envio de uma mensagem para a caixa de correio [**viaCTT**](/informacao-tecnica/incm/pedido-de-chave). ### KeyRetrieveOperation O código `RetrieveCode` que permite invocar a operação `KeyRetrieveOperation` é enviado para a caixa de correio viaCTT do utilizador. Para invocar o segundo pedido, preencha os valores `FiscalYear`, `VatNumber` e `RetrieveCode` e clique em ![Run](/files/-MRaPSdGoy4OaqbttKuY). ![KeyRetrieveOperation](/files/-MRaPSdITQwweOW4hxwb) A mensagem deste pedido contem os valores correspondentes à chave de cifra `Key` e o vetor de inicialização `IV` necessários para realizar o processo de cifra do ficheiro SAF-T (PT) da Contabilidade. # SAF-T: Utils [**CryptoSAF-T: SAF-T Utils**](https://github.com/assoft-portugal/CryptoSAF-T-SAF-T-Utils): é um ambiente escrito em JAVA que permite testar o método de encriptação do ficheiro SAF-T (PT) usando o algoritmo AES-128-CTR (FastSaftEncrypt), assim, como a canonização do ficheiro SAF-T (PT) original (FastHashCannon). {% tabs %} {% tab title="FastHashCannon" %} ### Execução `pt.cryptosaft.demo.FastHashCannon [inputXml] [outputXml]` | Argumento | Descrição | Valores | | --------- | ------------------------- | ------------------ | | inputXml | Ficheiro SAF-T de entrada | Ex: `saft.xml` | | outputXml | Ficheiro SAF-T canonizado | Ex: `saft_can.xml` | ### **JAR** `java -jar jar/FastHashCannon.jar-jar-with-dependencies.jar src/main/resources/Exemplo_Facturacao.xml` {% endtab %} {% tab title="FastSaftEncrypt" %} ### Execução `pt.cryptosaft.demo.FastSaftEncrypt [modo] [inputXml] [outputXml] [chave] [iv]` | Argumento | Descrição | Valores | | --------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- | | modo | Modo de operação |

E - Descaracterização (Encrypt);
D - Reversão (Decrypt);

| | inputXml | Ficheiro SAF-T de entrada | Ex: `saft.xml` | | outputXml | Ficheiro SAF-T de saída | Ex: `saft_desc.xml` | | chave | Chave simétrica em formato Base64 | Ex: `8/K97v8vQqbD/ShX5yx+3g==` | | iv | Vetor de inicialização em formato Base64 | Ex: `+KSjwLJcoMXl7W+U1y5VtQ==` | ### **JAR** `java -jar jar/FastSaftEncrypt.jar-jar-with-dependencies.jar E src/main/resources/Exemplo_Facturacao.xml /src/main/resources/CryptoSAFT-Exemplo_Facturacao.xml 8/K97v8vQqbD/ShX5yx+3g== +KSjwLJcoMXl7W+U1y5VtQ==` {% endtab %} {% endtabs %} # Mantenha-se em contacto Mantenha-se a par das últimas novidades sobre este e outros temas. * [**URL da ASSOFT**](https://www.assoft.org/) * [**URL da INCM**](https://www-tst.cryptosaft.incm.pt/) * [**Medium**](https://medium.com/assoft) * [**Slack**](https://www.assoft.org/pt/65/plataforma-colaborativa/) (grupo de discussão #wg-ies-pt) * [**Twitter**](https://www.twitter.com/assoft) * [**Facebook**](https://www.facebook.com/assoft.org) * [**LinkedIn**](https://www.linkedin.com/company/assoftassociacaoportuguesadesoftware/) ## Participe nas reuniões de acompanhamento dos testes Estão a decorrer testes de implementação das plataformas de submissão da IES através do ficheiro SAF-T (PT) na [**plataforma**](https://oa.portaldasfinancas.gov.pt/iessaft/) da Autoridade Tributária e Aduaneira e também de CryptoSAF-T. | Data | Assunto | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | quartas-feiras, 14h30 | [Balanço: Plataforma de Submissão da IES por SAF-T](https://teams.microsoft.com/l/meetup-join/19%3aa0299b73a6cb474683f866b7f9793237%40thread.skype/1610713710650?context=%7b%22Tid%22%3a%22ec237b6a-26a1-4fb6-849a-0564a8196832%22%2c%22Oid%22%3a%22161a2b31-3bd2-4b00-a6e7-f09cdbd5effd%22%7d) | | quartas-feiras, 15h30 | [Balanço: Testes e implementação do CryptoSAF-T](https://teams.microsoft.com/l/meetup-join/19%3aa0299b73a6cb474683f866b7f9793237%40thread.skype/1610713791309?context=%7b%22Tid%22%3a%22ec237b6a-26a1-4fb6-849a-0564a8196832%22%2c%22Oid%22%3a%22161a2b31-3bd2-4b00-a6e7-f09cdbd5effd%22%7d) | ## Ajude a para esta documentação atualizada Use a secção de [**issues**](https://github.com/assoft-portugal/documentacao-CryptoSAF-T/issues) para consultar, colocar questões ou sugerir alterações à documentação.