3. Manual de Integração 0.9 - 23/02/2023

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.

8 SERVIÇOS

A seguir estão os serviços relacionados disponíveis, conforme descritos no item 3.1, no WebService e seus XML Schema. O XML Schema define a estrutura e formatação do arquivo XML que conterá os dados a serem trafegados. Esses documentos serão enviados de forma textual (como uma string) como
parâmetros do serviço oferecido pelo Web Service, como descrito em 4. As tabelas que detalham cada XML Schema estão divididas da seguinte forma:

Legenda da tabela:

(1) Elemento
(2) Número identificador do campo, quando este contiver subitens;
(3) Nome do campo;
(4) Nome do tipo do campo que pode ser do tipo primitivo, simples ou complexo;
(5) Indica qual é o campo pai, para definição da hierarquia;
(6) Quantas vezes o campo se repete na estrutura de dados: a. Formato: “z-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) Descreve alguma observação pertinente;
(8) Formato de grupo, utilizado para definição de uma escolha (ver próximo item);
(9) Identifica os campos ou grupos que farão parte de uma escolha (choice).

8.1 Recepção e Processamento de Lote de RPS (Gerar NFS-e)

Esse serviço será executado, pelo o método gerarNfse, passando a mensagem XML como parâmetro com a estrutura definida na tabela que segue.

Em resposta a chamada do serviço será devolvida a estrutura definida na tabela a seguir.

O lote será processado posteriormente, gerando a nota fiscal em caso de conformidade e sendo o seu resultado disponibilizado para consulta (tanto o lote quanto as notas).

8.2 Consulta de Lote de RPS

Esse serviço será executado pelo método buscarLote, passando a mensagem XML como parâmetro com a estrutura definida na tabela que segue.

Em resposta a chamada do serviço será devolvida a estrutura definida na tabela a seguir.

8.3 Consulta de NFS-e

Esse serviço será executado pelo método buscarNfse, passando a mensagem XML como parâmetro com a estrutura definida na tabela que segue. Em resposta a chamada do serviço será devolvida a estrutura definida na tabela a seguir.