Comunicacao Dados Documentos Transporte

MANUAL DE INTEGRAO DE SOFTWARE

Comunicao dos Documentos de Transporte AT

Manual de Integrao de Software


Av. Eng. Duarte Pacheco, 28 - 18., Lisboa Tel: (+351) 21 383 4200 Fax: (+351) 21 383 4646

Email: [email protected] www.portaldasfinancas.gov.pt

HI ST RI CO DE ALTERA ES

DATA ALTERA ES

19-02-2013 Criao do documento

21-02-2013 Alterao das descries do SOAP:Body.

14-03-2013 Includo cdigo de resposta ao Webservice para pedidos SOAP invlidos.

Alterados os portos dos endereos de testes e de produo para 701 e 401, respetivamente.

Indicao da data de disponibilizao dos Webservices nos respetivos ambientes: 2 de abril de 2013 para testes; 1 de julho de 2013 para produo.

Alterao do SOAP:Body.

Alterao do logotipo.

25-03-2013 Alterao do SOAP:Body com a incluso de lista de referncias para o documento de origem ao nvel do bem e remoo da referncia do documento de origem ao nvel do documento de transporte.

02-04-2013 Incluso do formato do ficheiro de resposta.

Alterao do SOAP:Body com a uniformizao do wsdl para ingls.

04-04-2013 Alterao do Endereos para envio de dados AT por Webservice (Ambiente de teste).

15-04-2013 Adio de novos cdigos de erro.

Alterao WSDL: endereos.

24-04-2013 Atualizao da data de disponibilizao do ambiente de produo para 1 de julho de 2013.

15-05-2013 Indicao da data de 17 de maio de 2013 para disponibilizao do porto 401 para a comunicao de Documentos de Transporte via Webservices durante o perodo experimental.

26-06-2013 Adio de novos cdigos de erro retornados pelo webservice.

Atualizao dos Endereos teis com o Link para as FAQS dos Documentos de Transporte: Informao sobre o fim do perodo experimental.



Av. Eng. Duarte Pacheco, 28 - 18., Lisboa Tel: (+351) 21 383 4200 Fax: (+351) 21 383 4646

Email: [email protected] www.portaldasfinancas.gov.pt

NDI CE

1 INTRODUO ............................................................................................................... 4

2 ENQUADRAMENTO ........................................................................................................ 5 2.1 Comunicao dos Documentos por Webservice .............................................................................................. 5 2.2 Comunicao dos Documentos de Transporte por SAF-T (PT) ....................................................................... 6 2.3 Registo direto no Portal das Finanas .............................................................................................................. 8

3 ADAPTAO DO SOFTWARE .......................................................................................... 9 3.1 Comunicao por Webservice .......................................................................................................................... 9 3.2 Comunicao por SAF-T (PT) ........................................................................................................................ 15

4 ESTRUTURA DO ENVIO DE DADOS AT (SOAP) ........................................................... 16 4.1 SOAP:Header ................................................................................................................................................. 17 4.2 SOAP:Body ..................................................................................................................................................... 20 4.3 Resposta ao pedido SOAP ............................................................................................................................. 24

5 ASSINATURA CERTIFICADO SSL (CSR) ....................................................................... 27 5.1 Gerar um certificado SSL ................................................................................................................................ 28 5.2 Verificar contedo do CSR gerado ................................................................................................................. 29 5.3 Integrar certificado SSL com a chave privada ................................................................................................ 29

6 ENDEREOS TEIS ..................................................................................................... 30 6.1 Pgina de produtores de software .................................................................................................................. 30 6.2 Certificao de software ................................................................................................................................. 30 6.3 SAF-T (PT) - Verso portuguesa .................................................................................................................... 30 6.4 Gesto de subutilizadores no PF .................................................................................................................... 30 6.5 FAQS dos Documentos de Transporte ........................................................................................................... 30 6.6 WSDL do envio de dados AT por Webservice ............................................................................................. 30 6.7 Endereos para envio de dados AT por Webservice ................................................................................... 30

7 GLOSSRIO ............................................................................................................... 31



26 de Junho de 2013 4 / 32

1 Introduo

O presente documento descreve os procedimentos e requisitos necessrios comunicao de

dados dos documentos de transporte Autoridade Tributria e Aduaneira, adiante designada

por AT.

Este documento destina-se a apoiar as empresas ou indivduos que desenvolvam e/ou

comercializem software para os sujeitos passivos (seus clientes utilizadores do software

produzido), doravante designados por produtores de software.

Os produtores de software so responsveis por desenvolver programas que cumpram com os

requisitos legais da comunicao dos documentos de transporte e, para este efeito, devem

guiar-se pelas especificaes produzidas pela AT para este efeito de comunicao.

O Sujeito Passivo (tambm designado por remetente) responsvel pelo envio e contedo da

mensagem, uma vez que utiliza as suas credenciais no Portal das Finanas (Utilizador e

Senha). Estas credenciais s podem ser conhecidas pelo Sujeito Passivo devendo o software

produzido estar preparado para solicitar estas credencias, sempre que necessrio

comunicao dos dados.

Cada software identificado perante a AT atravs de um Certificado SSL emitido pelo produtor

de software e assinado digitalmente pela AT atravs de processo de adeso disponvel no site

e-fatura.

A AT s aceita estabelecimento de comunicao de dados se for enviado no processo de

comunicao, o Certificado SSL emitido para este efeito. Este certificado apenas garante o

estabelecimento da comunicao sendo responsabilidade do produtor de software transmitir

corretamente os dados dos Sujeitos Passivos, seus clientes.



26 de Junho de 2013 5 / 32

2 Enquadramento

De acordo com o disposto no Decreto-Lei n. 198/2012 de 24 de agosto, os sujeitos passivos

de IVA tm de comunicar os documentos de transporte emitidos AT, por uma das seguintes

vias:

Por transmisso eletrnica em tempo real, integrada em programa informtico,

utilizando o Webservice disponibilizado pela AT;

Atravs do envio do ficheiro SAF-T (PT), exportado pelo programa informtico

certificado e recorrendo a aplicao de envio de dados disponibilizada no site e-fatura

no Portal das Finanas;

Atravs da emisso direta no Portal das Finanas do documento de transporte

utilizando as funcionalidades previstas para esta comunicao.

2.1 Comunicao dos Documentos por Webservice

Para efetuar a comunicao por Webservice, tal como disposto no Decreto-Lei n. 198/2012 de

24 de agosto, os programas informticos tem que estar adaptados de forma a:

1. Respeitar o modelo de dados tal como previsto no Decreto-Lei n. 198/2012 de 24 de

agosto e definido em formato WSDL publicado no site e-fatura, na pgina dedicada aos

produtores de software, ou em alternativa atravs do endereo:

http://info.portaldasfinancas.gov.pt/NR/rdonlyres/A75E1110-7EB8-479E-BC09-

6D5B726F6A1C/0/documentosTransporte.wsdl

2. Utilizar os protocolos de comunicao definidos para a transmisso de dados utilizando

este servio, designadamente o protocolo SOAP:

3. Implementar os mecanismos de segurana na transmisso de dados que visam garantir

a confidencialidade dos dados tal como disposto no Artigo 6. do Decreto-Lei n.

198/2012 de 24 de agosto, designadamente:

a) Comunicao de dados atravs de canal HTTPS, com utilizao de certificado

SSL que identifica o produtor de software e que foi previamente assinado pela

AT;

b) Encriptao da senha do utilizador do sujeito passivo no portal das finanas

recorrendo a chave pblica (RS) do sistema de autenticao utilizado pelo Portal

das Finanas na identificao dos seus utilizadores;

c) Demais mecanismos, definidos em detalhe neste documento para garantir a

segurana da transmisso dos dados para a AT.



26 de Junho de 2013 6 / 32

2.2 Comunicao dos Documentos de Transporte por SAF-T (PT)

Para comunicar os dados dos documentos de transporte por ficheiro SAF-T (PT), cada sujeito

passivo (remetente) ter de proceder em dois passos:

1. Extrao do ficheiro SAF-T (PT);

2. Envio do ficheiro no Portal das Finanas, site e-fatura.

2.2.1 Extrao do Ficheiro SAF-T (PT)

O sujeito passivo (remetente) extrai do seu sistema informtico o ficheiro SAF-T (PT) para o

efeito de comunicao AT dos documentos de transporte.

O ficheiro XML para este efeito deve conter as seguintes tabelas do SAF-T (PT) e os respetivos

elementos definidos na estrutura de dados disponvel no seguinte endereo:

http://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/NEWS_SAF-T_PT.htm

1 - Cabealho (Header);

2.2 - Tabela de clientes (Customer);

2.3 - Tabela de fornecedores (Supplier);

4.2 - Documentos de movimentao de mercadorias (MovementOfGoods) adiante

tambm designados por documentos de transporte.

Para efeitos de otimizao de envio do ficheiro, este deve conter apenas:

Os documentos de transporte que ainda no tenham sido enviados - sem cdigo de

identificao do documento atribudo pela AT;

Os documentos de transporte com data de incio de transporte entre a data incio e data

fim de perodo de ficheiro (Ano, Ms, Dia);

Os clientes e fornecedores que tenham referncia nos Documentos de movimentos de

mercadorias (deixando de fora os que no movimentaram mercadorias naquele

perodo);

recomendvel que o envio de movimentos por ficheiro seja efetuado no dia ou dias

imediatamente anteriores ao transporte, dependendo o nmero de dias do processo

organizativo de cada sujeito passivo. Assim se vou fazer os movimentos na sexta-feira de

manh, devo comunicar os movimentos na quinta ao final do dia.

Apesar desta recomendao, sero processados todos os ficheiros e at contendo movimentos

no prprio dia.



26 de Junho de 2013 7 / 32

2.2.2 Envio do Ficheiro SAF-T (PT) extrado

Na posse do ficheiro extrado, o sujeito passivo (remetente) acede ao Portal das Finanas e ao

site e-fatura:

Escolhe a opo de Comunicao por Ficheiro - Enviar disponvel na rea dos

remetentes;

Ao escolher esta opo -lhe disponibilizado um formulrio para indicao do ficheiro a

comunicar (caminho-da-diretoria-onde-est-guardado e nome.xml); note-se que a

extenso do ficheiro ser obrigatoriamente .xml.

Aps escolha do ficheiro este automaticamente validado, apresentando mensagens

de erro no caso de o ficheiro no estar em condies de ser submetido;

Aps a correta validao do ficheiro apresentado um resumo estatstico do seu

contedo e disponibilizada a opo de envio para a AT - Submeter;

Ao submeter ser necessrio introduzir as credenciais (Utilizador e Senha) do Portal

das Finanas referentes ao sujeito passivo (remetente) responsvel pelo envio do

ficheiro de documentos de transporte;

Aps a completa transmisso do ficheiro para a AT mostrada uma mensagem de

confirmao do envio.

Posteriormente, o ficheiro ser processado pela AT e, se o contedo desse ficheiro for vlido,

sero processados todos os elementos dos documentos de Transporte, que sero integrados

na base de dados de documentos de transporte para os efeitos determinados na lei. Como

resposta receber um ficheiro onde constaram os cdigos de identificao AT atribudos a cada

documento vlido e com mensagens de validao para os que no foram aceites indicado o

motivo de rejeio.

2.2.3 Processamento do ficheiro de resposta

Como resultado do processamento do ficheiro, seja total ou parcialmente integrado, ser

gerado um ficheiro de resposta contendo:

Um cdigo de identificao de documento gerado pela AT para cada documento

integrado com sucesso;

Uma mensagem de rejeio de integrao indicado o motivo da rejeio.

Quando receber este ficheiro o Sujeito passivo dever importar os cdigos de identificao de

documento gerados pela AT para a sua aplicao de gesto de documentos de transporte, de

onde originalmente extraiu o ficheiro enviado.



26 de Junho de 2013 8 / 32

2.2.4 Consulta do processamento dos ficheiros

Para seguimento do tratamento do ficheiro comunicado, o remetente ter disponvel uma opo

de consulta aos ficheiros SAF-T (PT) por ele submetidos AT. Sempre que comunique um

ficheiro, o remetente dever posteriormente aceder a essa consulta e verificar se o ficheiro foi

processado com Sucesso.

As situaes de processamento previstas so:

Pendente - quando ainda espera processamento;

Integrado com sucesso - quando o ficheiro foi totalmente processado e registado na

base de dados da AT;

Integrado parcialmente - quando s parte da informao foi processada, por exemplo

a que difere da enviada anteriormente por este ou outro meio.

Rejeitado - quando se detetou um problema a nvel de contedo que impediu o

respetivo processamento.

2.3 Registo direto no Portal das Finanas

De acordo com o Decreto-Lei n. 198/2012 est prevista a disponibilizao de funcionalidades

para a emisso direta de documentos de transporte no portal das finanas, onde os sujeitos

passivos devem introduzir todos os elementos obrigatrios para emisso do documento e de

onde no final podero obter o cdigo de identificao atribudo pela AT.

Existir uma funcionalidade de recolha de dados para o registo das informaes dos

documentos de transporte que foram parcialmente comunicados por via telefnica e para os

quais h a obrigatoriedade de comunicar a totalidade dos dados at ao 5. dia til seguinte ao

transporte.



26 de Junho de 2013 9 / 32

3 Adaptao do software

Nesta seco a AT apresenta as suas recomendaes aos produtores de software de forma a

mudarem os seus programas informticos para inclurem o envio de documentos de transporte,

um a um por Webservice ou para o envio de documentos de transporte por ficheiro SAF-T (PT).

3.1 Comunicao por Webservice

O envio de documentos de transporte por Webservice pressupe que este feito medida que

os documentos de transporte so registados no programa informtico, estando associado ao

conceito de comunicao em tempo real, ou seja, assim que o sujeito passivo regista um

documento transporte no programa este de imediato comunicada AT por este canal.

Cada produtor de software responsvel por implementar o mdulo que vai enviar os

documentos de transporte que, para alm dos requisitos gerais j enunciados na seco 2.1,

dever respeitar os seguintes passos:

1. Se ainda no tiver efetuado a adeso ao servio, dever realizar o processo de adeso

comunicao de documentos de transporte,

a) necessrio utilizar o certificado SSL e submete-lo para ser assinado pela AT,

atravs do processo de adeso ao envio de dados dos documentos de

transporte por parte dos produtores de software;

2. O sujeito passivo (remetente) emite documento de transporte no programa informtico

prprio;

3. O programa informtico solcita as credenciais do sujeito passivo tal como definidas no

portal das finanas e na gesto de subutilizadores:

a) Cada sujeito passivo deve criar um subutilizador para o envio de dados relativos

aos documentos de transporte na opo disponvel no Portal das Finanas na

seco Servios tributrios/Outros servios/Gesto de utilizadores;

b) A este subutilizador deve ser atribuda a operao WDT - Comunicao de

dados de documentos de transporte;

4. Com base nos dados do documento de transporte criado no passo n. 1 e nas

credenciais solicitada no passo n. 2 deve construir o pedido SOAP tal como definido:

a) No WSDL disponvel no endereo:



b) Este pedido SOAP (Webservice) composto pelas seguinte seces descritas

na seco 4 deste documento e que se resumem a:



26 de Junho de 2013 10 / 32

SOAP:Header - onde se incluem os campos de autenticao do utilizador

que vai ser responsvel pela invocao do Webservice (a senha que vai

nesta seco tem que ser cifrada recorrendo chave pblica do sistema

de autenticao do portal das finanas);

SOAP:Body - contm os dados do documento de transporte;

5. Estabelecer uma ligao segura em HTTPS com o portal das finanas e utilizando o

seguinte endereo de envio de dados de documentos de transporte:

https://servicos.portaldasfinancas.gov.pt:701/sgdtws/documentosTransporte

NOTA: este endereo apenas estar disponvel a partir do dia 2 de abril

de 2013.

6. Processar corretamente o cdigo de resposta devolvido pelo Webservice, que pode ser

de trs tipos:

a) Mensagens de autenticao invlida;

b) Mensagens de processamento invlido dos dados do documento de transporte;

c) Registo com sucesso dos dados do documento de transporte.

Para adaptar os programas informticos recomendada execuo das seguintes fases

implementao:

Desenvolvimento

Testes

Distribuio

Produo

3.1.1 Fase de Desenvolvimento

Para poder iniciar o desenvolvimento cada produtor de software deve obter junto da AT os

elementos necessrios para o efeito, designadamente:

1. Criar subutilizador do prprio produtor de software fazendo-o no Portal das Finanas:

Portal das Finanas -> Outros Servios -> Gesto de utilizadores

Ao criar o subutilizador no Portal das Finanas (1 passo) deve atribuir a autorizao WDT

disponvel para a comunicao de dados dos documentos de transporte. Para criar este

utilizador necessrio indicar um Nome, uma senha (e respetiva confirmao) e um endereo

de email para utilizao em contactos por parte da AT. No final obtm a identificao do

subutilizador (e.g., 555555555/55) e a respetiva senha deve ser comunicada equipa de

desenvolvimento.



26 de Junho de 2013 11 / 32

2. Obter a chave pblica do Sistema de Autenticao do Portal das Finanas para cifrar a

senha do utilizador e certificado SSL assinado para comunicao com o endereo de

testes:

necessrio enviar um email AT a solicitar o envio dos mesmos. A mensagem a enviar por

email devem respeitar o seguinte template:

TO: [email protected]

Subject: Obteno do certificado SSL para testes e chave pblica do

sistema de Autenticao - NIF

Exmos. Senhores,

O Produtor de Software (NIF ) vem por este meio solicitar o

envio dos seguintes elementos para desenvolvimento e testes de envio de

documentos de transporte por Webservice:

Chave pblica do Sistema de Autenticao do PF;

Certificado SSL para comunicao com o endereo de testes de

Webservices.

Estes elementos sero utilizados por este produtor de software para incluir nos

seguintes programas:

Designao Software Certificado AT / DGCI

... ...

Aguardamos a vossa resposta.

No template anterior, cada produtor de software deve substituir os seguintes elementos pelos

seus dados:

- Substituir pelo NIF do produtor de software;

- Substituir pelo NIF do produtor de software.

- Designao do software N

- N de certificado da AT (DGCI se ainda for o caso)



26 de Junho de 2013 12 / 32

3. Obter o WSDL que define a estrutura do pedido SOAP a construir para enviar os dados

dos documentos de transporte, disponvel em:

Site e-fatura -> pgina Produtores de Software -> opo Testar Webservice

Para a correta construo do pedido SOAP (invocao do Webservice) deve utilizar a

informao complementar disponvel neste documento na seco 4, onde se detalha a

informao que deve constar dos campos do pedido SOAP bem como a sua forma de

construo.

3.1.2 Fase de Testes

A AT disponibiliza um endereo de testes para verificao da comunicao de dados AT de

forma a apoiar cada produtor de software na correta disponibilizao dos seus programas aos

sujeitos passivos, seus clientes.

Para este efeito, cada produtor de software deve seguir o seguinte procedimento:

1. Solicitar as credenciais de subutilizador e senha criada para os testes de comunicao

dos documentos de transporte (e.g., 555555555/55 + SENHA);

2. Cifrar a senha e compor o SOAP:Header de acordo com o definido na seco 4.1;

3. Com base no documento de transporte inserido, construir o SOAP:Body de acordo com

o definido na seco 4.2;

4. Estabelecer uma ligao HTTPS com o seguinte endereo disponibilizado apenas para

testes:

a) https://servicos.portaldasfinancas.gov.pt:701/sgdtws/documentosTransporte

NOTA: este endereo apenas estar disponvel a partir do dia 2 de abril

de 2013.

b) Este endereo s aceita ligaes com o certificado SSL disponibilizado para

testes (vide 3.1.1);

5. Submeter o pedido SOAP construdo no ponto 3;

6. Processar a resposta que o servio lhe devolve de acordo com as vrias hipteses

definidas na seco 4.3. As respostas so dos seguintes tipos:

a) Cdigo de sucesso;

b) Erros de autenticao referentes aos campos do SOAP:Header;

c) Erros nos dados dos documentos de transporte referentes aos campos

preenchidos no SOAP:Body.



26 de Junho de 2013 13 / 32

Para efeitos de despiste, disponibilizada uma pgina de testes de conectividade e exemplos

de pedido e resposta SOAP para comparao com o programa do produtor de software. Mais

informao na seco 4.1.1 deste documento.

3.1.3 Fase de Distribuio

Depois de confirmarem a correta adaptao do programa informtico e antes de distribuir os

vossos programas aos vossos clientes (sujeitos passivos) necessrio proceder da seguinte

forma:

1. Efetuar a adeso ao envio de dados dos documentos de transporte atravs do

formulrio disponvel em:

Site e-fatura -> pgina Produtores de Software -> opo Aderir ao Servio

a) necessrio aceitar os termos e condies do servio, disponveis para

consulta no formulrio;

b) Para completar o pedido de adeso necessrio gerar um certificado SSL de

acordo com as instrues disponveis na seco 5;

c) A AT responde a este pedido por mensagem de email contendo o certificado

SSL assinado digitalmente pela AT;

2. Alterar o endereo de comunicao para o endereo de comunicao de dados AT

em ambiente de produo:


NOTA: Este endereo est disponvel a partir do dia 17 de maio no mbito do

perodo experimental. E a partir do dia 1 de julho ser disponibilizado

em ambiente de produo.

3. Substituir o certificado SSL utilizado em testes (ponto 4 da Fase de Testes) pelo

certificado SSL de produo emitido no ponto 1 alnea c) desta fase.

Depois de concluda este procedimento o(s) vosso(s) programas informticos esto prontos

para serem distribudos aos vossos clientes (sujeitos passivos).

3.1.4 Fase de produo

Depois de instalado o programa informtico nos computadores dos vossos clientes (sujeitos

passivos) est tudo pronto para comear o envio de documentos de transporte por Webservice.

Cada sujeito passivo deve criar um subutilizador para a comunicao de dados dos

documentos de transporte de forma em tudo idntica ao definido no ponto 1 da Fase de

Desenvolvimento (vide 3.1.1) e com permisses WDT para comunicao dos documentos de

transporte AT.



26 de Junho de 2013 14 / 32

Depois de criado este subutilizador, o sujeito passivo, responsvel pelas credenciais emitidas

(utilizador e senha), deve configurar no programa informtico com estas credenciais, atravs de

opo prpria.

Por regra, o envio procede da seguinte forma:

1. Sujeito passivo emite documento de transporte no programa informtico;

2. So obtidas as credenciais do sujeito passivo configuradas no programa informtico;

3. construdo o pedido SOAP e invocado o Webservice em produo com os dados do

ponto 1 e ponto 2;

4. Programa processa a resposta do servio e informa o utilizador do sucesso ou solicita

ao do utilizador para o caso de erro no envio.

Uma vez que este servio deve ser utilizado no envio de cada documento de transporte

individualmente, sempre que o produtor de software identificar a necessidade de envio massivo

de documentos transporte, deve indicar ao sujeito passivo que tem de utilizar o envio por

ficheiro SAF-T (PT), tal como definido na seco 3.2 deste documento.



26 de Junho de 2013 15 / 32

3.2 Comunicao por SAF-T (PT)

Tal como descrito na seco 2.2 o envio do ficheiro SAF-T (PT) composto por dois passos:

extrao a partir do software prprio e posteriormente realizado o envio no site e-fatura.

Para otimizao do envio, os produtores de software devem considerar implementar as

seguintes caractersticas nos seus produtos:

1. Extrair a informao de documentos de transporte que no tenham cdigo de

identificao AT;

2. Extrair a informao com a indicao de um determinado perodo (datas, por dia, etc.);

3. Extrair apenas a informao da tabela de clientes e fornecedores que tenham referncia

em documentos comerciais desse ficheiro, no incluindo os restantes;

Estas otimizaes tm dois efeitos: reduzem o tamanho do ficheiro e consequentemente

ocupam menos espao em disco; e consequentemente reduzem o tempo necessrio para

processar cada ficheiro.

Com reduo do tamanho poupa-se espao em disco e consumo de memria de cada

processamento efetuado. Reduzindo a informao ao que relevante em cada ficheiro, permite

acelerar o tempo de extrao, validao local e consequentemente o tempo total de

comunicao dos documentos de transporte AT.

3.2.1 Processamento do ficheiro de resposta

Como resultado do processamento do ficheiro, ser gerado um ficheiro de resposta em formato

normalizado, na linguagem XML, respeitando o esquema de validao "FicheiroResposta.xsd"

disponvel no endereo abaixo:

http://info.portaldasfinancas.gov.pt/NR/rdonlyres/D5EC8326-8297-43AF-BCE6-

1CE4B0EF344D/0/FicheiroResposta.xsd



26 de Junho de 2013 16 / 32

4 Estrutura do envio de dados AT (SOAP)

Nesta seco descreve-se informao complementar ao definido no WSDL do servio de

comunicao de dados de documentos transporte em tempo real.

O servio disponibiliza uma operao de registo de documento de transporte, que possibilita o

envio dos elementos previstos no Decreto-Lei n. 198/2012, documento de transporte a

documento de transporte.

O pedido efetuado segundo o protocolo SOAP e constitudo por duas seces:

d) SOAP:Header;

e) SOAP:Body

A primeira seco, o Header, inclui todos os campos de autenticao do utilizador que vai ser

responsvel pela invocao do Webservice. Este utilizador ser um subutilizador do NIF do

sujeito passivo (remetente) com perfil WDT.

Para criar o subutilizador deve ser utilizada a opo Servios tributrios/Outros servios/Gesto

de utilizadores.

A segunda seco contm os dados do documento de transporte os quais se detalham no

tpico SOAP:Body.



26 de Junho de 2013 17 / 32

4.1 SOAP:Header

O desenho do Header tem como requisito garantir a confidencialidade dos dados de

autenticao e a impossibilidade de reutilizao dos mesmos em ataques Man-in-the-middle

(MITM). Por este motivo, s sero aceites invocaes que respeitem os seguintes

procedimentos de encriptao.

O SOAP:Header construdo de acordo com o standard WS-Security, definido pela OASIS e

recorrendo definio do Username Token Profile 1.1, tambm definido pela mesma

organizao.

Na seguinte tabela, detalha-se a forma de construo de cada campo e de acordo com as

necessidades de segurana especficas do sistema de autenticao do portal das finanas.

Parmetro Descrio Obrig.1 Tipo

Dados2

H.1 - Utilizador (Username) Identificao do utilizador que vai submeter os dados,

composto da seguinte forma e de acordo com a

autenticao do portal das finanas:

/

Exemplos possveis:

1. 555555555/1 (subutilizador n. 1)

2. 555555555/0002 (subutilizador n. 2)

3. 555555555/1234 (subutilizador n. 1234)

S String

H.2 - Nonce Chave simtrica gerada a cada pedido e para cifrar o

contedo dos campos H.3 - Password e H.4 - Created.

Cada invocao do Webservice dever conter esta chave

gerada aleatoriamente e a qual no pode ser repetida.

Para garantir a confidencialidade, a chave simtrica tem

de ser cifrada com a chave pblica do Sistema de

Autenticao de acordo com o algoritmo RSA e

codificada em Base 64.

A chave pblica do sistema de autenticao do portal das

finanas deve ser obtida por solicitao prpria e atravs

do endereo de email [email protected].

O campo construdo de acordo com o seguinte

procedimento

S String (base64)

1 Obrigatrio: S Sim; N No.

2 A validar na especificao WSDL (Web Service Definition Language) do servio

))((64: , sKpubRSA KCBaseNonce SA



26 de Junho de 2013 18 / 32

KS := array de bytes com a chave simtrica de 128

bits, produzida de acordo com a norma AES.

CRSA,KpubSA := Funo de cifra da chave simtrica

com o algoritmo RSA utilizando a chave pblica do

sistema de autenticao (KpubSA).

Base64 := Codificao em Base 64 do resultado.

H.3 - Password O campo Password dever conter a senha do utilizador /

subutilizador, a mesma que utilizada para entrar no

Portal das Finanas.

Esta Password tem de ser cifrada atravs da chave

simtrica do pedido (ver campo Nonce) e codificado em

Base64.

))((64: 5,, SenhaPFCBasePassword PaddingPKCSECBAESKs

SenhaPF := Senha do utilizador definido no campo

H.1 - Username;

PaddingPKCSECBAES

KsC 5,, := Funo de cifra

utilizando o algoritmo AES, Modelo ECB,

PKCS5Padding e a chave simtrica do pedido

(KS).


S string (base64)

H.4 - Data de sistema (Created)

O campo Created dever conter a data e hora de sistema

da aplicao que est a invocar o webservice.

Esta data usada para validao temporal do pedido,

pelo que crucial que o sistema da aplicao cliente

tenha o seu relgio certo.

Sugere-se a sincronizao com o Observatrio

Astronmico de Lisboa:

http://www.oal.ul.pt/index.php?link=acerto

A zona temporal deste campo dever estar definida para

UTC e formatado de acordo com a norma ISO 8601 tal

como definido pelo W3C:

http://www.w3.org/QA/Tips/iso-date

http://www.w3.org/TR/NOTE-datetime

e.g.: 2013-01-01T19:20:30.45Z

Este campo cifrado com a chave de pedido (KS) e

codificada em Base 64.

))((64: 5,, TimestampCBaseCreated PaddingPKCSECBAESKs

string (base64)



26 de Junho de 2013 19 / 32

Timestamp := data hora do sistema (UTC);

PaddingPKCSECBAES

KsC 5,, := Funo de cifra

utilizando o algoritmo AES, Modelo ECB,

PKCS5Padding e a chave simtrica do pedido

(KS).


4.1.1 Exemplo SOAP:Header

Como resultado da aplicao das regras de construo anteriores ser produzido um header

de pedido SOAP tal como o seguinte:

599999993/37

ikCyRV+SWfvZ5c6Q0bhrBQ==

fkAHne7cqurxpImCfBC8EEc2vskyUyNofWi0ptIijYg4gYCxir++unzfPVPpusloEtmLkcZjf+E6

T9/76tsCqdupUkxOhWtkRH5IrNwmfEW1ZGFQgYTF21iyKBRzMdsJMhhHrofYYV/YhSPdT4dlgG0t

k9Z736jFuw061mP2TNqHcR/mQR0yW/AEOC6RPumqO8OAfc9/b4KFBSfbpY9HRzbD8bKiTo20n0Pt

amZevCSVHht4yt/Xwgd+KV70WFzyesGVMOgFRTWZyXyXBVaBrkJS8b6PojxADLcpWRnw5+YeOs3c

PU2o1H/YgAam1QuEHioCT2YTdRt+9p6ARNElFg==

>YEWoIoqIY5DOD11SeXz+0i4b/AJg1/RgNcOHOYpSxGk



26 de Junho de 2013 20 / 32

4.2 SOAP:Body

Nesta seco so definidos os campos para o registo de um novo documento de transporte.

Os campos utilizados no pedido por Webservice derivam do definido na Portaria n 382/2012

de 23 de novembro para os campos de SAF-T (PT).


Dados4

1.1 NIF Remetente

(TaxRegistrationNumber)

NIF do remetente

Preencher com o NIF portugus sem espaos

e sem qualquer prefixo do pas.

S int

1.2 Nome da empresa

(CompanyName)

Nome da empresa

Denominao social da empresa ou nome do

sujeito passivo.

S string

1.3 Endereo da Empresa (CompanyAddress) S

1.3.1 Morada detalhada

(AddressDetail)

Dever incluir o nome da rua, nmero de polcia e

andar, se aplicvel.

S string

1.3.2 Localidade (City) Localidade. S string

1.3.3 - Cdigo postal

(PostalCode)

Cdigo Postal. S string

1.3.4 Pais (Country) Preencher com . S string

1.4 Identificao nica do

documento

(DocumentNumber)

Identificao nica do documento de transporte

Deve ser idntico ao que consta no ficheiro

SAF-T (PT), quando gerado a partir sistema

informtico que emitiu este documento;

Deve respeitar o formato definido na legislao

relativa ao ficheiro SAF-T (PT), em vigor

aquando da comunicao dos elementos dos

documentos de transporte:

o composto pelo cdigo interno do

documento, seguido de um espao,

seguido do identificador da srie do

S string





26 de Junho de 2013 21 / 32

documento, seguido de uma barra (/),

e de um nmero sequencial do

documento dentro da srie;

No podem existir registos com a mesma

identificao.

No podem ser utilizados o mesmo cdigo

interno de documento em tipos de documentos

(InvoiceType) diferentes.

1.5 Cdigo de

Identificao do documento

(ATDocCodeID)

Cdigo de identificao atribudo pela AT ao documento,

nos termos do decreto-lei n 198/2012, de 24 de agosto.

N string

1.6 - Estado atual do

documento

(MovementStatus)

Estado de documento. Pode assumir os seguintes

valores:

N Normal;

T Por conta de terceiros;

A Anulada.

S string

1.7 Data do documento

(MovementDate)

Data de emisso do documento de transporte. S date

1.8 Tipo do documento

(MovementType)

Deve ser preenchido com:

GR Guia de remessa;

GT Guia de transporte;

GA Guia de movimentao de ativos

prprios;

GC Guia de consignao;

GD Guia ou nota de devoluo efetuada pelo

cliente.

S string

1.9 NIF Cliente

(CustomerTaxID)

NIF do cliente nacional

Nmero de Identificao Fiscal portugus (sem

qualquer prefixo do pas);

No caso em que no se conhece o destinatrio

dever ser preenchido com o NIF

;

Este campo tambm deve ser preenchido no

caso das guias que titulam a transferncia de

bens do prprio remetente.

N string



26 de Junho de 2013 22 / 32

1.10 NIF fornecedor

(SupplierTaxID)

NIF do fornecedor nacional

Nmero de Identificao Fiscal portugus (sem

qualquer prefixo do pas);

No caso em que no se conhece o destinatrio

dever ser preenchido com NIF

;

Este campo apenas deve ser utilizado no caso

de guias de devoluo ou guias de transporte

de bens mveis produzidos ou montados sob

encomenda com materiais que o dono da obra

tenha fornecido para o efeito e se o campo

anterior no estiver preenchido.

N string

1.11 Nome da Empresa

Cliente (CustomerName)

Nome da empresa Cliente

Denominao social da empresa ou nome do

sujeito passivo.

N string

1.12 Endereo da Empresa Cliente (CustomerAddress) N string


(AddressDetail)


andar, se aplicvel.

N string

1.12.2 - Localidade (City) Localidade. N string


(PostalCode)

Cdigo Postal. N string

1.12.4 Pais (Country) Preencher com . N string

1.13 Local de descarga (AddressTo) N


(AddressDetail)

Dever incluir o nome da rua, nmero de policia e

andar, se aplicvel.

N string

1.13.2 - Localidade (City) Localidade. N string


(PostalCode)

Cdigo Postal. N string

1.13.4 Pais (Country) Preencher com . N string

1.14 Local de carga (AddressFrom) S



26 de Junho de 2013 23 / 32


(AddressDetail)


andar, se aplicvel.

S string

1.14.2 - Localidade (City) Localidade. S string


(PostalCode)

Cdigo Postal. S string

1.14.4 Pais (Country) Preencher com PT. S string

1.15 Data hora fim de

transporte

(MovementEndTime)

Tipo de data e hora: em

que o pode ser , na ausncia de

informao concreta.

N dateTime

1.16 Data hora incio de

transporte

(MovementStartTime)

Tipo de data e hora: em

que o pode ser , na ausncia de

informao concreta.

S dateTime

1.17 Identificador do

veculo (VehicleID)

Matrcula do veculo. N string

1.18 Linhas do Documento com os bens (Line)

Linhas de bens do documento de transporte.

S

1.18.1 Referncia ao

documento de origem

(OrderReferences)

Existindo a necessidade de efetuar mais do que uma

referncia, este campo poder ser gerado tantas vezes

quantas as necessrias.

N string

1.18.2 Descrio do

Produto ou Servio

(ProductDescription)

Descrio da linha da fatura, ligada tabela de produtos

e servios.

S string

1.18.3 Quantidade

(Quantity)

Quantidade. S decimal

1.18.4 Unidade de medida

(UnitOfMeasure)

Unidade de medida. S string

1.18.5 Preo Unitrio

(UnitPrice)

Preo unitrio sem imposto e deduzido dos descontos

de linha e cabealho.

Em documentos no valorizados deve ser preenchido

com .

S decimal



26 de Junho de 2013 24 / 32

4.3 Resposta ao pedido SOAP


Dados6

1.1 - Cdigo do resultado

(ReturnCode)

Cdigo do resultado da invocao desta interface. Se a

resposta for zero, a operao foi bem sucedida. Se for um

nmero diferente de zero, significa que a operao no foi

bem-sucedida.

Cdigo de sucesso:

0 Documento registado com sucesso.

Cdigos de resposta (autenticao):

1 - Utilizador no preenchido;

2 - Tamanho do utilizador incorreto;

3 - NIF invlido;

4 - Utilizador com formato invlido;

5 - Subutilizador com formato invlido;

6 - Senha no preenchida;

7 - Codificao Base64 invlida;

8 - Cifra da chave pblica invlida;

9 - Formato do Timestamp invlido;

10 - Validade da credencial expirada;

11 - Chave simtrica invlida;

12 - Chave simtrica repetida;

13 - Estrutura da senha invlida;

33 - Pedido SOAP invlido;

99 - Erro na validao da senha (Senha errada,

acesso suspenso, etc.).

Cdigos de resposta (dados dos documentos de

transporte):

-1 Parmetro de entrada invlido;

S Int





26 de Junho de 2013 25 / 32

-2 O nmero do Documento Global no

corresponde a nenhum Documento de

Transporte existente;

-3 J foi inserido um Documento de Transporte

com o nmero fornecido;

-4 - J foi anulado o Documento de Transporte

com o nmero fornecido;

-5 - Estado de Documento de Transporte

invlido;

-6 - A Data de incio de transporte no pode ser

anterior data atual;

-7 - O NIF do Remetente no corresponde ao

anteriormente fornecido;

-8 - O Cdigo AT est preenchido mas no existe

Documento de Transporte;

-9 - O n de Documento de Transporte

diferente do anteriormente fornecido;

-10 - O Remetente no tem atividade registada;

-11 - O NIF do Adquirente no corresponde ao

anteriormente fornecido;

-12 - No foi possvel verificar se o Remetente

tem atividade aberta;

-13 - No pode ser alterado um Documento de

Transporte quando a Data de Incio j decorreu;

-14 - As referncias de Documento Global para

Documentos com tipo de emisso 4, tm que ser

do tipo 3;

-15 - No pode adicionar referncias para outros

documentos, uma vez que este documento j

referenciado por documentos parciais;

-16 - No pode alterar a data de emisso do

documento;

-99 Erro interno;



26 de Junho de 2013 26 / 32

1.2 - Mensagem

(ReturnMessage)

Mensagem descritiva da resposta. N string

1.4 Identificao nica do

documento

(DocumentNumber)

Identificao nica do documento de transporte

Deve ser idntico ao que consta no ficheiro SAF-

T (PT), quando gerado a partir sistema

informtico que emitiu este documento;

Deve respeitar o formato definido na legislao

relativa ao ficheiro SAF-T (PT), em vigor

aquando da comunicao dos elementos dos

documentos de transporte:

o composto pelo cdigo interno do

documento, seguido de um espao,

seguido do identificador da srie do

documento, seguido de uma barra (/), e

de um nmero sequencial do

documento dentro da srie;

No podem existir registos com a mesma

identificao;

N string

1.5 Cdigo de

Identificao do documento

(ATDocCodeID)

Cdigo de identificao atribudo pela AT ao documento,

nos termos do decreto-lei n 198/2012, de 24 de agosto.

N string



26 de Junho de 2013 27 / 32

5 Assinatura certificado SSL (CSR)

A invocao dos servios web pressupe um processo de autenticao mediante a validao

da chave privada da aplicao, do conhecimento exclusivo do produtor de software (entidade

aderente), sendo a respetiva chave pblica comunicada e assinada pela AT.

O certificado SSL a ser utilizado na operao assinado pela AT, a pedido da entidade

aderente. Para este efeito, a empresa aderente deve efetuar um pedido de certificado SSL

(CSR Certificate Signing Request).

O CSR um pequeno ficheiro de texto cifrado que contm o certificado SSL e toda a

informao necessria para que a AT possa assinar e devolver o certificado SSL assinado

digitalmente para que possa ser utilizado no processo de autenticao na invocao do servio

web de apoio submisso dos documentos de transporte.

Os procedimentos para gerao do CSR so simples mas variam de acordo com a tecnologia

web utilizada pela entidade aderente, razo pela qual devem ser consultados os respetivos

manuais de apoio de cada ferramenta.

A informao que o CSR deve conter a seguinte, no podendo ultrapassar os tamanhos

mximos indicados pois vai ultrapassar o tamanho total aceite para o campo CSR e onde todos

os campos tm de estar preenchidos com informao relevante ou de acordo com a descrio

abaixo:

Campo CSR Descrio Tamanho Mximo

C = Country

O cdigo ISO de 2 letras referente ao local da sede.

Por exemplo, no caso de Portugal PT.

2 (chars)

ST = Province, Region,

County or State Distrito da sede.

32 (chars)

L = Town/City Local da sede. 32 (chars)

CN = Common Name Neste campo deve ser indicado o nmero de identificao fiscal da entidade aderente.

9 (chars)

O = Business

Name / Organisation Designao legal da empresa.

180 (chars)

OU = Department

Name /Organisational Unit Departamento para contacto.

180 (chars)



26 de Junho de 2013 28 / 32

E = An email address

O endereo de correio eletrnico para contacto, geralmente do responsvel pela emisso do CSR ou do departamento de informtica.

Tem que ser um endereo de email vlido.

80 (chars)

Key bit length

Chave pblica do certificado SSL gerado pelo produtor de software tem de ser gerado com 2048 bits.

2048 (bits)

A utilizao de carateres especiais (e.g., portugueses, lnguas latinas, etc.) no aceite em

nenhum dos campos acima indicados, uma vez que a utilizao desses carateres vai invalidar

a assinatura digital do certificado SSL.

Como resultado deste processo a AT proceder assinatura do certificado SSL e remete em

resposta ao pedido o certificado SSL assinado para integrao na chave privada do produtor

de software.

O certificado SSL ter a validade de 12 meses a contar da data da assinatura.

5.1 Gerar um certificado SSL

Um certificado SSL uma chave RSA composta por duas partes: chave privada e chave

pblica.

Como a chave privada deve ser apenas do conhecimento do produtor de software a emisso

da mesma tem sempre de ser efetuada pelo prprio, em computador prprio e nunca num site

ou servio web que encontre para o efeito.

Existem diversas ferramentas para gerao de certificados SSL, proprietrias e Opensource.

Para efeitos de exemplo a AT utiliza a ferramenta OpenSSL, que a ferramenta Opensource

de referncia, livre de custos de utilizao.

Para gerar um certificado SSL cada produtor de software deve faz-lo no seu prprio

computador utilizando o seguinte comando:

openssl req -new -subj "/C=PT/ST=Distrito da Sede/L=Local da Sede/O=Empresa

/OU=Departamento de

Informatica/CN=555555555/[email protected]" -newkey

rsa:2048 -nodes -out 555555555.csr -keyout 555555555.key

Cada produtor de software deve substituir a informao especifica no comando anterior pelos

seus dados, uma vez que os apresentados so apenas exemplificativos e no deve alterar a

informao indicada a BOLD.

Como resultado o comando anterior ser gerado o certificado SSL e sero produzidos dois

ficheiros:



26 de Junho de 2013 29 / 32

555555555.csr - Ficheiro com o pedido CSR a enviar AT;

555555555.key - Ficheiro com a chave privada gerada.

5.2 Verificar contedo do CSR gerado

Antes de enviar o CSR para assinatura digita pela AT pode e deve ser verificado o contedo do

ficheiro para garantir que toda a informao est como pretendido. Para tal deve ser usado o

seguinte comando:

openssl req -text -noout -in 555555555.csr

Onde cada produtor de software deve substituir os parmetros que no esto a BOLD pelos

nomes dos ficheiros corretos.

5.3 Integrar certificado SSL com a chave privada

Depois de receber o certificado SSL assinado pela chave digital da AT necessrio integrar

esse certificado com a chave privada gerada no passo anterior (555555555.key). Para tal deve

ser usado o seguinte comando:

openssl pkcs12 -export -in 555555555.crt -inkey 555555555.key -out

555555555.pfx

Onde cada produtor de software deve substituir os parmetros que no esto a BOLD pelos

nomes dos ficheiros corretos.

Como resultado, o certificado SSL assinado pela AT integrado com a chave privada e

gravada com uma password de acesso que cada produtor de software deve definir na

execuo do comando.



26 de Junho de 2013 30 / 32

6 Endereos teis

6.1 Pgina de produtores de software

https://www.portaldasfinancas.gov.pt/pt/external/factemipf/painelInicialProdSoftware.action

6.2 Certificao de software

http://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/CertificacaoSoftware.htm

6.3 SAF-T (PT) - Verso portuguesa

http://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/NEWS_SAF-T_PT.htm

6.4 Gesto de subutilizadores no PF

https://www.portaldasfinancas.gov.pt/pt/external/factemipf/painelInicialProdSoftware.action

6.5 FAQS dos Documentos de Transporte

http://info.portaldasfinancas.gov.pt/pt/faturas/m_doctransp.html

6.6 WSDL do envio de dados AT por Webservice



6.7 Endereos para envio de dados AT por Webservice

Ambiente de testes


NOTA: este endereo apenas estar disponvel a partir do dia 2 de abril de 2013.

Ambiente de produo


NOTA: este endereo est disponvel a partir do dia 17 de maio no mbito do

perodo experimental. E a partir do dia 1 de julho ser disponibilizado em ambiente

de produo.



26 de Junho de 2013 31 / 32

7 Glossrio

Tabela de acrnimos, abreviaturas e definies de conceitos utilizados neste documento,

ordenados alfabeticamente por termo.

Termo Definio

AES http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

Chave Pblica do SA http://wsautentica.segautenticacaodev.ritta.local/certificates/SA.cer

ECB Referncia do ECB:

http://www.itl.nist.gov/fipspubs/fip81.htm

Explicao do ECB:

http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation#Electron

ic_codebook_.28ECB.29

OAL Observatrio Astronmico de Lisboa: http://www.oal.ul.pt/

Para acertar a hora do computador seguindo as instrues do Observatrio:

http://www.oal.ul.pt/index.php?link=acerto

OpenSSL http://www.openssl.org/

PF Portal das Finanas: www.portaldasfinancas.gov.pt

PKCS#5 Referncia do PKCS #5:

http://tools.ietf.org/html/rfc2898

Explicao do PKCS #5:

http://en.wikipedia.org/wiki/PKCS

SA Sistema de autenticao do Portal das Finanas: www.acesso.gov.pt.

Sistema responsvel por validar as credenciais de um utilizador registado no Portal

das Finanas.

SAF-T (PT) http://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/NEWS_SAF-T_PT.htm

SOAP http://www.w3.org/TR/soap/

Standard Date Format ISO 8601

http://www.w3.org/TR/NOTE-datetime

http://www.w3.org/QA/Tips/iso-date

Username Token Profile https://www.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os-

UsernameTokenProfile.pdf



26 de Junho de 2013 32 / 32

Webservice http://www.w3.org/TR/ws-arch/

WS-Security https://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-

SOAPMessageSecurity.pdf

WSDL http://www.w3.org/TR/wsdl

Documents

Comunicacao Dados Documentos Transporte