Interface Web services

(1)

Declarações Electrónicas

Interface Web services

DGCI 2008/06/18

DGCI, 2008/06/18

(2)

Objectivo

y

Promover a integração de aplicações remotas

com os Web services fornecidos pela DGITA

para a submissão de declarações fiscais

y

Esclarecer questões de uma forma

y

Esclarecer questões de uma forma

abrangente, optimizando a interacção das

empresas com a DGITA

p

(3)

Agenda

y

Ambiente de Testes

y

Requisitos para Testes

A bi

t d P d ã

y

Ambiente de Produção

y

Requisitos para Produção

y

Interface Web service

y

Interface Web service

y

Processo de Integração

y

Questões Frequentes

Q

q

y

Endereços

y

Referências

(4)

Ambientes

y

Testes vs. Produção

y Endereços

y Processo de autenticação no site

Utili d d t t

(5)

Diagrama do Ambiente de Testes

Cliente DGITA Aplicação Cli t SSL-Accelerator Porto: 443 Web Server Conteúdos Estáticos Servidor Aplicacional Testes Web Service Cadastro Testes Contabilidade Cliente Web Services (Post) HTTPS _Basic Authentication Estáticos HTTPS HTTP Conector Conector NIF (Testes)

(6)

Requisitos para Testes (1)

y

Declarações válidas

y Segundo os formatos disponibilizados no site

das DE:

Ajuda -> Suporte Informático – Formato de Ficheiros

(7)

(8)

Requisitos para Testes (2)

y

Nifs e Senhas de testes

y Obtenção de NIF/Senhas válidos no ambiente

de testes para os casos que se pretendem testar:

testar:

y NIF Colectivo (sujeito passivo colectivo) y NIF TOC (técnico oficial de contas)

(9)

Requisitos para Testes (3)

y

Acesso ao Ambiente de Testes

y Definição do Endereço de Testes da Declaração

que se pretende testar

y Definição do User/Password de acesso ao Site y Definição do User/Password de acesso ao Site

de Testes

Ex: Teste Modelo 22

http://www.e-financas.gov.pt/testes/jsp-dgci/WS/EntregaMod22.jsp

(10)

Diagrama do Ambiente de Produção

Cliente DGITA Aplicação SSL Accelerator Porto: 400 Web Server Conteúdos Estáticos Cadastro Servidor Aplicacional Web Service Cli t Client Authentication Estáticos HTTPS HTTP Conector Conector Contabilidade Cliente Web Services (Post) HTTPS Certificados (Chaves Públicas) Controlo Duplicados Certificados NIF Password Certificado Cliente (Chave Privada) NIF Password White List

(11)

Requisitos para Produção

y

Declarações válidas

y

Chave pública do certificado já enviada para a

G

(

ã

f

d

l

G

)

DGITA. (Recepção confirmada pela DGITA).

y

Acesso à chave privada do certificado a partir

da aplicação

(12)

Interface

y Web service:

y REST (Representational State Transfer) y Pedido: HTTP(S) Post

y Resposta: XML

P â t

y Parâmetros

y ws_version

y Nº da versão do Web Service y Obrigatório

(13)

Interface – Parâmetros(1)

y

declVersion

y Nº da versão do formato de ficheiro da

declaração que se pretende enviar (parâmetro declaração que se pretende enviar (parâmetro “decl”)

(tem que ser igual ao atributo “Versão de

( q g

ficheiro” do documento que especifica a declaração)

Ob igató io

(14)

Interface – Parâmetros(2)

y nif

Nº d id tifi ã Fi l d S j it P i

y Nº de identificação Fiscal do Sujeito Passivo y Obrigatório

y password

y Senha de acesso do Sujeito Passivo ao site das

õ ó ã

Declarações Electrónicas, se a declaração for

entregue pelo Sujeito Passivo ou se for entregue pelo TOC e este não representar o Sujeito Passivo

(15)

Interface – Parâmetros(3)

y

nifTOC

Nº d Id tifi ã Fi l d Té i Ofi i l d

y Nº de Identificação Fiscal do Técnico Oficial de

Contas, se a declaração for entregue por TOC

y Opcional

y

passwordTOC

S h d d TOC íti d

y Senha de acesso do TOC ao sítio das

Declarações Electrónicas, se a declaração for entregue por TOC

(16)

Interface – Parâmetros(4)

y

decl

y A declaração a ser submetida, no formato de

ficheiro publicado no site das Declarações Electrónicas e de acordo com o parâmetro: Electrónicas e de acordo com o parâmetro: declVersion

y A declaração deverá vir comprimida no formato

ZIP e codificada em Base64.

(17)

Interface – Resposta

(18)

Interface – Resposta (1)

y Código (Resultado)

y 0 – Sucesso

y 95 – Erro durante a validação do certificado. Mensagem de erro especificada num

elemento ‘erro’

y 96 – Pedido inválido. Verificar os parâmetros do pedido. Mensagem de erro especificada

num elemento ‘erro’

y 97 – Erro grave durante o processamento no Sistema. Tentar de novo mais tarde.

Mensagem de erro especificada num elemento ‘erro’

y 98 – Autenticação inválida. Corrigir autenticação do Sujeito Passivo e/ou TOC e tentar

de novo Mensagem de erro especificada num elemento ‘erro’ de novo. Mensagem de erro especificada num elemento erro

y 99 – Erro de validação. Corrigir a declaração e voltar a submeter. Os erros ou alertas

(19)

Interface – Resposta (2)

y

Resposta sem erros

y

dados submissao

y

dados submissao

y data (Data e Hora da entrega da declaração)

y ano (Exercício a que se refere a declaração)

d f ã d l ã

y idDecl (Identificação da Declaração)

y contribuinte (Lista de NIF’s associados à declaração e informação sobre os mesmos)ç ç )

y id (SP ou TOC)

(20)

Interface – Resposta (2)

Declaração Sem Erros

<?xml version="1.0" encoding="ISO-8859-1"?> <resposta> <codigo>0</codigo> <d d b i d t "2007 04 23 16 23 18" <dados-submissao data="2007-04-23 16:23:18" ano="2006" idDecl="3267"> <contribuinte id="SP" nif="555555555"/> <contribuinte id="TOC" nif="111111111"/> <contribuinte id= TOC nif= 111111111 /> </dados-submissao>

(21)

Interface – Resposta (3)

y erros (Informação sobre erros relativos à declaração submetida)ç )

y tem-mais-erros (Indicador de existência de mais erros para além dos enviados na resposta)

y erroerro (Lista de erros)(Lista de erros)

y Anexo (Indica o nome do anexo quadro sobre o qual se refere a mensagem, se existir )

y Quadro (Indica o quadro sobre o qual se refere a mensagem, se existir)

y Msg (Mensagem indicativa da situação de erro encontrada)

(22)

Interface – Resposta (3)

Declaração com Erros

<?xml version="1.0" encoding="ISO-8859-1"?> <resposta>

<tem-mais-erros>false</tem-mais-erros> <tem mais erros>false</tem mais erros> <erro anexo=”nomeAnexo-Base64Encoded” quadro=”nomeQuadro-Base64Encoded”>

<msg>Mensagem de erro Base64-Encoded</msg>

</erro> </erros>

</resposta> </resposta>

(23)

Processo de Integração (1)

y

Formalização do pedido de acesso aos Web

services

C t t DGCI

y Contacto com a DGCI

y Preenchimento do Contrato de Adesão

y Impresso e assinado em papel timbrado da y Impresso e assinado em papel timbrado da

entidade

(24)

Processo de Integração (2)

y

Testes

y Produção de ficheiros válidos para a declaração

t t a testar

y Formatos de ficheiro disponíveis em: y Formatos de ficheiro disponíveis em:

DE -> Menu Impressos

y Validação de formatos de ficheiro através das

aplicações Offline, disponibilizadas no site

l d DE -> Menu Downloads

(25)

Processo de Integração (3)

y Testes

y Obtenção de NIF/Senhas válidos no ambiente de testes

t d t t para os casos que se pretendem testar:

y NIF Colectivo (sujeito passivo colectivo) y NIF TOC (técnico oficial de contas)NIF TOC (técnico oficial de contas)

y NIF SP (sujeito passivo singular) Contacto: 213834200

E il SI AGI Á d G tã d I t Email: SI - AGI - Área de Gestão de Impostos

• [email protected]

(26)

Processo de Integração (3)

y

Testes

y Submissão de Declarações para o Ambiente de

Testes

y 1º Utilizando: HTTP y 1º Utilizando: HTTP

(permite visualizar todos os parâmetros do pedido/resposta)

y 2º Utilizando: HTTPS

(permite validar que o protocolo HTTPS está a ser correctamente utilizado)

(27)

Processo de Integração (4)

y

Produção

y Enviar para a DGITA:

y Chave pública do certificado da Empresa y Incluir a respectiva cadeia de certificação y Incluir a respectiva cadeia de certificação y Enviar o ficheiro no email em formato .Zip

y Acesso à chave privada do certificado cliente na

(28)

Questões Frequentes (1)

y

Utilização de Protocolo GET em vez de POST

Os Web services só respondem a pedidos

efectuados via: HTTP POST

Os pedidos efectuados, colocando por

exemplo o endereço fornecido num browser

exemplo o endereço fornecido num browser,

devolvem a página:

(29)

(30)

Questões Frequentes (1)

y

Construir um Form HTML com os vários

parâmetros, método: POST e um botão

“Submit”

<html>

<form name="test webservice" method "POST"

method="POST"

action="https://<utilizador>:<password>@www.e-financas.gov.pt/testes/jsp-dgci/WS/EntregaMod22.jsp">

<!–- nif: 123456789 -->

NIF: <input type="text" name="nif" value="MTIzNDU2Nzg5"> <br />

<!–- restantes parâmetros --> <br />

</form> </html>

(31)

Questões Frequentes (1)

Content-Type: application/x-www-form

urlencoded

Content-Length: <tamanho do pedido>

body=<endereço>&nome1=URLEncode(Base64(v

alor1))&nome2=URLEncode(Base64(valor2))

(32)

Questões Frequentes (2)

y

Codificação em Base 64

Os valores dos parâmetros devem ser todos

codificados, 1 a 1

Excepto os dados da declaração que devem

ser previamente:

“Zipados” e só depois:

codificados em Base64

(33)

Questões Frequentes (2)

y

Codificação em Base 64 e ZIP

Qual a codificação dos caracteres a utilizar ?

“UTF-8”

(34)

Questões Frequentes (3)

y

Combinação: NIF válido + Password Errada

y 5 Tentativas

y Esperar 24 horas (máximo) ou

C t t DGITA

y Contactar DGITA

y Tel: 213834200

y Email: SI - AGI - Área de Gestão de Impostosp

(35)

Questões Frequentes (4)

y

Erro 95:

“O certificado não foi encontrado no pedido”

- Não está a ser utilizado o porto: 400.

(36)

Questões Frequentes (5)

y

Erro 99:

“A declaração enviada está duplicada e não

f

d ”

foi processada.”

F i i d

ti

t

- Foi enviada consecutivamente, a mesma

declaração para o mesmo nif.

Enviar uma declaração com dados diferentes

para o mesmo NIF.

(37)

Questões Frequentes (6)

y Certificado:

O Certificado a adquirir deve ter as seguintes propriedades (Key Usage):

propriedades (Key Usage):

Digital Signature;Non Repudiation; Key Encipherment; Data Enciphermentp ; p

y A DGITA necessita da chave pública do certificado

em questão e da cadeia de certificação

ã

y Formato: Base64 encoded X.509 (extensão .CER). y Enviar no Email em formato: .Zip

(38)

Endereços de Testes

Autenticação: Basic access authentication (user + password)

y

Modelo 22

http(s)://www.e-financas.gov.pt/testes/jsp-dgci/WS/EntregaMod22.jsp

y

Modelo 10

http(s)://www e financas gov pt/testes/jsp dgci/WS/EntregaM10WS jsp http(s)://www.e-financas.gov.pt/testes/jsp-dgci/WS/EntregaM10WS.jsp

y

IES

(39)

Endereços de Produção

y

Modelo 22

https://www.e-financas.gov.pt:400/jsp-dgci/WS/EntregaMod22.jsp y

Modelo 10

https://www.e-financas.gov.pt:400/jsp-dgci/WS/EntregaM10WS.jsp y

IES

y

IES

https://www.e-financas.gov.pt:400/jsp-dgci/WS/EntregaIES-DA.jsp

(40)

Referências (1)

y

Base 64

y Decoder http://www.opinionatedgeek.com/dotnet/to ols/Base64Decode/ y Encoder http://www.opinionatedgeek.com/dotnet/to ols/Base64Encode/ ols/Base64Encode/