3.Manual de Integração

3 ARQUITETURA DE COMUNICAÇÃO COM O CONTRIBUINTE

3.1 Modelo Conceitual
Utilizando Web Service, o Sistema de Notas Fiscais de Serviços
Serviço Eletrônicas das Administrações Tributárias Municipais disponibilizará serviços
que poderão ser acessados pelos sistemas sistemas dos contribuintes. A seguir, estão
resumidos os serviços disponíveis e suas respectivas funcionalidades básicas.

3.1.1 Recepção e Processamento de Lote de RPS (Gerar NFS-e)
Esse serviço compreende a recepção do Lote de RPS, a resposta com o número do protocolo gerado para esta transação e o processamento do lote. Quando efetuada a recepção, o Lote entrará na fila para processamento posterior quando serão feitas as validações necessárias e geração das NFS-e.

XML de Envio é validado pelo elemento do schema do arquivo nfse.xsd:gerarNFSe

Passos para execução:

1. A aplicação acessa o serviço de “Recepção e Processamento de Lote de RPS” enviando o lote de RPS (fluxo “b”).

2. A requisição é recebida pelo servidor do Web Service que grava as informações recebidas e gera o número de protocolo de recebimento (fluxo “c”).

3. O Web Service retorna uma mensagem com o resultado do processamento do serviço, (fluxo “d”).

A URL do serviço será:
https://www.janelaunica.srv.br:8443/wsjanelaunica/NfseWS?wsdl

3.1.3 Consulta de NFS-e
Esse serviço efetua a consulta da(s) NFS-e(s) gerada(s).
XML de Envio é validado pelo elemento do schema do arquivo nfse.xsd:buscarNfse

Passos para execução:

1. A aplicação acessa o serviço de “Consulta de NFS-e” e submete os dados para processamento.

2. A requisição é recebida pelo servidor do Web Service, que verifica os dados preenchidos e identifica a(s) NFS-e(s) correspondente (s).

3. O Web Service retorna uma mensagem com o resultado do processamento do serviço.

4 PADRÕES TÉCNICOS

O meio físico de comunicação utilizado entre os sistemas de informação dos contribuintes e o Sistema de Notas Fiscais de Serviço Eletrônicas das Administrações Tributárias Municipais será a Internet, com o uso do protocolo SSL, que além de garantir um duto de comunicação seguro na Internet, permite a utilização de nome ou código de usuário e senha em tráfego seguro.

O modelo de comunicação segue o padrão de Web Services definido pelo WS-I Basic Profile (Basic 128).

A troca de mensagens entre o Web Service do Sistema de Notas Fiscais de Serviço Eletrônicas das Administrações Tributárias Municipais e o sistema do contribuinte será realizada no padrão SOAP, com troca de mensagens XML no padrão Style/Enconding: Document/Literal, wrapped. A opção “wrapped”
representa esenta a chamada aos métodos disponíveis com a passagem de mais de um parâmetro. Para descrever os serviços disponibilizados, será utilizado um documento WSDL (Web Service DescriptionLanguage). O WSDL é o padrão recomendado para descrição de serviços SOAP.

As chamadas aos serviços serão feitas enviando como parâmetro um documento XML a ser processado pelo sistema. Esse documento não fará parte da descrição do serviço (arquivo WSDL), e o formato do XML
correspondente ao serviço está definido neste manual de integração, seção 5.

4.1 Habilitando Login
Para conectar um sistema gerador de RPS com o sistema emissor de NFS-e

Siga os seguintes passos:
1 - acesse a Área do Prestador de Serviços, no portal Janela Única.
2 - clique em Contribuinte e depois em RPS.
3 - clique no botão Alterar Senha.
A senha cadastrada será utilizada tanto na integração ao web Service de teste
quanto no Web Service de Produção. Uma vez cadastrada a nova senha a empresa
estará homologada.
As informações necessárias para acessar o Web Service são o código do usuário e
a senha.

5 PADRÃO DAS MENSAGENS XML

A especificação adotada para as mensagens XML é a recomendação W3C para XML 1.0, disponível em http://www.w3.org/TR/REC-xmle a codificação dos caracteres será em UTF-8.

As chamadas dos Web Services disponibilizados Administrações Tributárias Municipais e os respectivos resultados do processamento são realizadas com utilização de mensagens com o seguinte padrão:

• Área de Cabeçalho – estrutura XML padrão para todas as mensagens de chamada e retorno de resultado dos Web Services disponibilizados pelas Administrações Tributárias Municipais, que contêm os dados de controle da mensagem. A área de cabeçalho está sendo utilizada para armazenar a versão do leiaute da estrutura XML informada na área de dados

• Área de Dados – estrutura XML variável definida na documentação do Web Service acessado.

Abaixo, o leiaute da Área de Cabeçalho:

6 ESTRUTURA DE DADOS DO WEB SERVICE

Existe um único Web Service com todos os serviços apresentados no item 3.1. O fluxo de comunicação é sempre iniciado pelo sistema do contribuinte com o envio de uma mensagem XML ao Web Service com o
pedido do serviço desejado.

6.1 Modelo Operacional
A forma de processamento das solicitações de serviços no projeto Nota Fiscal de Serviços Eletrônica pode ser síncrona, caso o atendimento da solicitação de serviço seja realizada na mesma conexão ou assíncrona, quando o processamento do serviço solicitado não é atendido na mesma conexão, devido a uma demanda de processamento de grande quantidade de informação. Nessa situação torna-se necessária a realização de mais uma conexão para a obtenção do resultado do processamento.

As solicitações de serviços que exigem processamento intenso serão executadas de forma assíncrona e as demais solicitações de serviços de forma síncrona.

Assim, os serviços da NFS-e serão implementados da seguinte forma:

6.1.1 Serviços Síncronos
As solicitações de serviços de implementação síncrona são processadas imediatamente e o resultado do processamento é obtido em uma única conexão.

Abaixo, o fluxo simplificado de funcionamento:

1. O aplicativo do contribuinte inicia a conexão enviando uma mensagem de solicitação de serviço para o Web Service;

2. O Web Service recebe a mensagem de solicitação de serviço e encaminha ao aplicativo da NFS-e que irá processar o serviço solicitado;

3. O aplicativo da NFS-e recebe a mensagem de solicitação de serviços e realiza o processamento, devolvendo uma mensagem de resultado do processamento ao Web Service;

4. O Web Service recebe a mensagem de resultado do processamento e o encaminha ao aplicativo do contribuinte;

5. O aplicativo do contribuinte recebe a mensagem de resultado do processamento e caso não exista outra mensagem, encerra a conexão.

6.1.2 Serviços Assíncronos
As solicitações de serviços de implementação assíncrona são processadas de forma distribuída por vários processos e o resultado do processamento somente é obtido na segunda conexão.

Abaixo, o fluxo simplificado de funcionamento para solicitação e processamento:

1. O aplicativo do contribuinte inicia a conexão enviando uma mensagem de solicitação de serviço para o Web Service de recepção de solicitação de serviços;

2. O Web Service de recepção recebe a mensagem de solicitação de serviço e a coloca na fila de serviços solicitados;

3. O Web Service de recepção de solicitação de serviços retorna o protocolo da solicitação de serviço e a data e hora de gravação na fila de serviços solicitados ao aplicativo do contribuinte;

4. O aplicativo do contribuinte recebe o protocolo;

5. Na estrutura interna do aplicativo de NFS-e a solicitação de serviços é retirada da fila de serviços solicitados pelo aplicativo da NFS-e em momento específico, definido pela equipe técnica da NFS-e;

6. O serviço solicitado é processado pelo aplicativo da NFS-e e o resultado do processamento é colocado na fila de serviços processados;
   
   Obtenção do resultado do serviço:

7. O aplicativo do contribuinte, utilizando o protocolo recebido, envia uma consulta ao serviço que retornará o resultado do processamento daquele protocolo, iniciando uma conexão com o Web Service;

8. O Web Service recebe a mensagem de consulta e localiza o resultado de processamento da solicitação de serviço;

9. O Web Service devolve o resultado do processamento ao aplicativo contribuinte;

10. O aplicativo do contribuinte recebe a mensagem de resultado do processamento e, caso não exista outra mensagem, encerra a conexão.

7 FORMATOS E PADRÕES UTILIZADOS

Abaixo seguem algumas formatações de dados que devem ser seguidas para geração correta na estrutura dos arquivos.

Não deve ser inserido caractere não significativo para preencher o tamanho completo do campo, ou seja, zeros antes de número ou espaço em branco após a cadeia de caracteres. A posição do campo é definida na estrutura do documento XML através de TAGs (<tag>conteúdo</tag>).

A regra constante do parágrafo anterior deverá estender-se para os campos para os quais não há indicação de obrigatoriedade e que, no entanto, seu preenchimento torna-se obrigatório seja condicionado à legislação específica ou ao negócio do contribuinte. Nesse caso, deverá constar a TAG com o valor correspondente e, para os demais campos, deverão ser eliminadas as TAGs.

Para reduzir o tamanho final do arquivo XML da NFS-e alguns cuidados de programação deverão ser assumidos:

• não incluir "zeros não significativos" para campos numéricos;
• não incluir "espaços" no início ou no final de campos numéricos e alfanuméricos;
• não incluir comentários no arquivo XML;
• não incluir anotação e documentação no arquivo XML (TAG annotation e TAG documentation);
• não incluir caracteres de formatação no arquivo XML ("line-feed", "carriagereturn", "tab", caractere de "espaço" entre as TAGs);
• para quebra de linha na exibição para os campos contendo caracteres Discriminação e Outras informacões, utilizar a sequência “\s\n”.

As TAGs que permitirem valores nulos devem ser omitidas da estrutura XML a ser enviada quando seus valores forem nulos.

7.1 Tipos Simples

A seguir encontra-se a tabela com a lista dos tipos simples que serão utilizados como tipos de dados. A tabela está dividida em 4 colunas, a saber:

Campo: nome do tipo simples;
Tipo: tipo primitivo de dados utilizados pelo campo:
C: Caractere;
N: Número;
D: Data ou Data/Hora;
T: Token (não utilizado)
Descrição: descreve informações sobre o campo;
Tam.: tamanho do campo:

• Quando forem caracteres o tamanho define a quantidade máxima de caracteres que o texto poderá ter;

• Quando for numérico o tamanho pode ser representado das seguintes formas;

• Número inteiro, que define o total de dígitos existente no número. Exemplo: “15” significa que o número poderá ter, no máximo, 15 dígitos;

• Número fracionário, que define o total de dígitos e quantos deles serão designados para a parte fracionária. Exemplo: “15,2” significa que o número poderá ter, no máximo, 15 dígitos sendo 2 deles a da parte fracionária. A parte fracionária não é obrigatória quando assim definido;

• Quando for data, não haverá definição de tamanho.

7.2 Tipos Complexos

A seguir são detalhadas as tabelas de cada tipo composto e seus campos.

A tabela está dividida da seguinte forma:

Legenda da tabela:
(1) Nome do tipo complexo;
(2) Descrição do tipo complexo;
(3) Identifica se a sequência de campos fará parte de uma escolha (choice);
(4) Nome do campo que faz parte do tipo complexo;
(5) Tipo do campo, que pode ser simples ou complexo;
(6) Quantas vezes o campo se repete na estrutura de dados: a. Formato: “x-y” onde “x” é a quantidade mínima e “y” a quantidade máxima. Se a quantidade máxima for indefinida, será utilizado “N” no lugar do “y”;
(7) Descrição do campo.