Utilizar tabela Unificada – Antigo

Última atualização em: 31 de julho, 2014

 

1.1 Utilizar tabela Unificada

As tabelas unificadas foram criadas na medida em que o layout de integração teve um aumento significativo de complexidade, complexidade essa inserida pelas alterações decorrentes de novas integrações. Os campos que possuem uma tabela unificada, possuem na coluna “Observações” do layout de integração essa informação.

Devido a existência de integrações realizadas anterior a existência dessa tabela, a ativação dela é manual, e se dá ao alterar um parâmetro nos dados da empresa (Painel de Controle > Dados da Empresa):

Caso o campo “Utilizar tabela Unificada” esteja como Sim, o sistema irá utilizar os valores conforme a tabela. Se não for configurado (apareça “Selecione”) ou seja, configurado para não, o sistema enviará da maneira antiga (sem tabela, ou com informações específicas de cada padrão).

Integração com Padrões que utilizam arquivos – Antigo

Última atualização em: 31 de março, 2016

 

Alguns padrões adotados pelas prefeituras utilizam arquivos para a integração, e o fluxo de emissão fica um pouco diferente dos demais que utilizam a integração via Web Service. A seguir é detalhado um passo-a-posso desse fluxo:

     1. Enviando o RPS para o InvoiCy NFS-e
A primeira etapa é enviar o XML para o InvoiCy NFS-e. Este XML conterá os dados da NFS-e, da mesma forma como os outros padrões que se comunicam via web service. Não há diferenças na primeira etapa, basta enviar o XML para o web service de Recepção do RPS.

     2. Adquirindo o arquivo com o Lote de RPS da Prefeitura
Nos padrões que utilizam arquivo como integração será retornado duas tags extras <ArquivoTXT> e <ExtensaoArquivo>. A tag “ArquivoTXT” conterá o arquivo em Base64 que deverá ser decodificado e transformado em arquivo e a tag “ExtensaoArquivo” conterá a extensão do arquivo. Para informações de como decodificar o conteúdo da tag em arquivo ver o artigo Exemplo de decodificação de base64 para arquivo.

     3. Enviando o arquivo para a prefeitura
Para enviar o arquivo para a prefeitura é necessário acessar o Portal da NFSE da mesma. Dentro do portal haverá uma opção para importar o arquivo. A localização desta opção muda de padrão para padrão, por exemplo, no SigCORP TXT a opção está em NFS-e e depois Enviar Arquivo (Lote), conforme imagem abaixo:

img_sistema_integracao

Após o upload, a prefeitura irá validar, importar os RPSs e transforma-los em NFS-e.

     4. Obtendo o retorno da Prefeitura
Para completar o fluxo com o InvoiCy NFS-e e efetivar o RPS (ou cancelar, caso a prefeitura tenha essa opção), é necessário obter o arquivo de retorno da prefeitura, que conterá as NFS-e. Como exemplo, no SIGCorp TXT, basta ir em Movimento, selecionar o período, ir em Serviços Prestados / Ferramentas NF-e e clicar em Exportar Notas Emitidas, conforme imagem abaixo:

img_sistema_integracao_ii

     5. Enviando o retorno da prefeitura para o InvoiCy NFS-e
Para enviar o arquivo com as NFS-e para o InvoiCy NFS-e, utiliza-se o mesmo web service para o Envio do RPS. A diferença nesse caso é que o XML deve conter apenas o Cabeçalho e as tags <ArquivoTXT> e <ExtensaoArquivo>. A tag <ArquivoTXT> preenchida com o arquivo da prefeitura codificado em Base64 e a tag <ExtensaoArquivo> com a extensão do arquivo. O InvoiCy NFS-e irá realizar o processamento necessário para o padrão e retornar o status do mesmo

 

Notas Rejeitadas
Os padrões com arquivo não costumam ter notas rejeitadas. Isso se dá pelo fato de que a validação ocorre na prefeitura, o InvoiCy NFS-e apenas gera o arquivo a ser enviado para a prefeitura. Caso o RPS seja rejeitado na prefeitura, ele normalmente não é importado (pode variar de padrão para padrão), e o retorno da prefeitura não irá contemplar aquelas notas que foram rejeitadas pela prefeitura. Caso algum RPS no arquivo esteja inválido, pode-se corrigir o RPS e repetir os passos 1 a 3.

 

Cancelamento de notas fiscais
O cancelamento no InvoiCy NFS-e, se dá de 3 formas:

1. Quando uma nota é cancelada na prefeitura, deve-se repetir o procedimento n° 4, pois no retorno da prefeitura conterá o status da nota (cancelada ou efetivada).

2. Através do web service de Cancelamento, no qual a nota será marcada como cancelada apenas no InvoiCy NFS-e.

3. Através da opção Cancelar NFS-e via interface web do InvoiCy NFS-e, o qual também apenas irá marcar a nota como cancelada. Os itens 1 e 2 funcionam dessa maneira pois não há comunicação direta com a prefeitura.

Artigos Relacionados:

Exemplo de decodificação de base 64 para arquivo – Antigo

Última atualização em: 31 de março, 2016

 

Base64 é um método de codificação para transferência de arquivos. O InvoiCy faz uso desse método para retornar os arquivos XML e PDF via Web Service, no momento do envio, cancelamento, consulta, e demais requisições.

Você emissor ainda tem a possibilidade de escolher qual forma de retorno deseja receber, sendo que tanto para o arquivo XML como para PDF as opções são as seguintes: Base64, Link para download, Base64 e Link ou não retornar.

Ao escolher a opção ‘Link para download’ será retornado um link para efetuar o download do arquivo (XML e PDF), onde ao clicar no link será possível baixar e salvar os arquivos fisicamente para a sua máquina. Destacando que será permitido o download dos arquivos apenas se o documento já tenha sido persistido para a base de dados do InvoiCy.

Já ao optar pelo retorno em Base64, não será necessário efetuar download de nenhum arquivo. O próprio retorno do Web Service já irá conter o arquivo XML e PDF codificado para Base64, onde você emissor poderá copiar o conteúdo desse texto e decodificá-lo para gerar os arquivos PDF e XML. O retorno em Base64 não depende do processo de persistência do InvoiCy, onde mesmo sem estar persistido o documento será possível decodificar e visualizar o conteúdo do Base64 retornado.

Este é um exemplo de implementação em linguagem C# de decodificação de base64 para arquivo.

exemplo_decodificacao_base_64Exemplo de decodificação de base64 para arquivo

Cancelando uma NFS-e – Antigo

Última atualização em: 31 de julho, 2014

 

Neste artigo iremos demonstrar como realizar o cancelamento de NFS-e através do Web Service do InvoiCy.

A partir de agora, assumimos que você já leu o artigo Consultar uma NFS-e. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.

O Cancelamento de uma NFS-e é extremamente simples e constitui um processo adicional, embora usado com bastante frequência. Para que isso se torne possível, siga os seguintes passos:

1. Consumindo o Web Service
Primeiramente, você deve realizar o consumo do Web Service de Cancelamento de NFS-e – https://gnfse.gnfe.com.br/apnuc138.aspx?wsdl

2. Criar o XML para o envio
O XML de Cancelamento pode conter um ou mais NFS-e a serem canceladas. Os detalhes de como criar o XML e transmitir estão detalhados abaixo.

Para obter os Layouts de envio e retorno do XML de Cancelamento de NFS-e, faça o download do arquivo Cancelamento.zip. Nele você encontrará também o arquivo XSD e XML de exemplo.
O XML a ser enviado pode ser divido em duas partes: Cabeçalho (comum a todos os serviços – exceto no cadastro de prestador) e os dados do RPS/NFS-e (Tag <ListaRPS>). A Tag ListaRPS contém os dados do(os) RPS, e o cabeçalho contém os dados do emissor e a chave de comunicação. Para saber como gerar a Tag ListaRPS corretamente e como gerar a Chave de Comunicação, consulte o artigo Gerar um XML de Envio passo-a-passo.
Após finalizado, o documento XML deve ser inserido entre as TAGS <nfse:Entradaxml> </nfse:Entradaxml> do SOAP de envio. Veja abaixo um exemplo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar a geração do XML de integração, disponibilizamos o XML de envio, bem como um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. Maiores detalhes no artigo Validação de arquivos XML.

3. Realize a leitura do retorno do envio da NFS-e
Após o envio do XML, precisamos realizar a leitura do retorno do cancelamento de NFS-e. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do serviço de Cancelamento de apenas uma NFS-e, porém, é possível cancelar mais de uma numa única requisição.
O seu sistema deve ler o retorno, validando as informações conforme o layout de retorno. O retorno criará um grupo para cada NFS-e, contendo o número, série, situação, entre outros. Retornará também os erros, caso a prefeitura não permita o cancelamento.
Agora que você já cancelou uma NFS-e, podemos dar prosseguimento ao próximo passo.
Seu próximo passo é: Download do XML da NFS-e.

Artigos Relacionados:

Download do XML da NFS-e – Antigo

Última atualização em: 31 de março, 2016

 

Há duas formas de como fazer o download do XML da NFS-e, a primeira é via Sistema web e a segunda é via Web Service.

Download via Sistema web

Acessar o Sistema web e na listagem de notas da tela inicial clicar sobre o ícone download_xml (download XML) correspondente da nota. Após irá aparecer uma tela com várias opções de download, conforme imagem abaixo selecione a opção “NFS-e”.

download_xml
Nota: Por questões de segurança dos navegadores, os downloads só estão habilitados para conexão HTTPS.

Download via Web Service

A partir de agora, assumimos que você já leu o artigo Integrar com o InvoiCy NFS-e. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento desta etapa.
Para realizar o download via Web Service, primeiro é necessário realizar a integração, conforme os passos a seguir:

     1. Consumindo o Web Service
Primeiramente, você deve realizar o consumo do seguinte Web Service https://gnfse.gnfe.com.br/apnuc209.aspx?wsdl

     2. Gerar o XML de envio
Nessa etapa é gerado um XML contendo os parâmetros da solicitação, dados de identificação da empresa e segurança no cabeçalho e uma lista de RPS que se deseja fazer o download do XML. Os detalhes de como criar o XML e transmitir estão detalhados abaixo. Para obter os layouts de envio e retorno do XML de Download XML, faça o download do arquivo DownloadXML.zip. Nele você encontrará também o arquivo XSD e XML de exemplo. O XML a ser enviado pode ser divido em duas partes: Cabeçalho (comum a todos os serviços – exceto no cadastro de prestador) e os parâmetros para a consulta (Tag <FaixaConsulta>). Para saber como gerar os dados do cabeçalho, consulte o artigo Gerar um XML de Envio passo-a-passo. O documento XML deve ser convertido para texto, e inserido entre as TAGS <nfse:Entradaxml> </nfse:Entradaxml> do SOAP de envio. Veja abaixo um exemplo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar a geração do XML de integração, disponibilizamos o XML de envio, bem como um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. Maiores detalhes no artigo Validação de arquivos XML.

     3. Realizar a leitura do retorno
Após o envio do XML, precisamos realizar a leitura do retorno do processamento. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do serviço de Download XML de apenas um RPS requisitado.
O seu sistema deve ler o retorno, validando as informações conforme o layout de retorno. O retorno criará um grupo para cada RPS solicitado, contendo a série, o número e o XML da NFS-e em base64. Retornará também mensagens de erro caso ocorra. Para informações de como decodificar o conteúdo da tag <NfseXml> em arquivo XML ver o artigo Exemplo de decodificação de base64 para arquivo.

Seu próximo passo é: Gerar o Espelho do RPS e NFS-e.

Artigos Relacionados:

Consultando uma NFS-e – Antigo

Última atualização em: 31 de julho, 2014

 

Neste artigo iremos demonstrar como realizar a consulta de NFS-e através do Web Service do InvoiCy.

A partir de agora, assumimos que você já leu o artigo Emitir uma NFS-e. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.

A consulta de uma NFS-e é extremamente simples, embora seja vital para o processo, pois na consulta que o emissor pode verificar o status do envio dos RPS. Para que isso se torne possível, siga os seguintes passos:

1. Consumindo o Web Service
Primeiramente, você deve realizar o consumo do Web Service de Consulta de NFS-e – https://gnfse.gnfe.com.br/apnuc137.aspx?wsdl

2. Criar o XML para o envio
O XML de consulta pode conter um ou mais RPS para consulta. Os detalhes de como criar o XML e transmitir estão detalhados abaixo.

Para obter os layouts de envio e retorno do XML de Consulta de NFS-e, faça o download do arquivo Consulta.zip. Nele você encontrará também o arquivo XSD e XML de exemplo.

O XML a ser enviado pode ser divido em duas partes: Cabeçalho (comum a todos os serviços – exceto no cadastro de prestador) e os dados do RPS (Tag <ListaRPS>). A Tag ListaRPS contém os dados do(os) RPS, e o cabeçalho contém os dados do emissor e a chave de comunicação. Para saber como gerar a Tag ListaRPS corretamente e como gerar a Chave de Comunicação, consulte o artigo Gerar um XML de Envio passo-a-passo.

Após finalizado, o documento XML deve ser inserido entre as TAGS <nfse:Entradaxml> </nfse:Entradaxml> do SOAP de envio. Veja abaixo um exemplo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: ttp://www.w3schools.com/html/html_entities.asp.

Para facilitar a geração do XML de integração, disponibilizamos o XML de envio, bem como um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. Maiores detalhes no artigo Validação de arquivos XML.

3. Realize a leitura do retorno do envio da NFS-e
Após o envio do XML, precisamos realizar a leitura do retorno da consulta de NFS-e. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do serviço de Consulta de apenas uma NFS-e efetivada.

O seu sistema deve ler o retorno, validando as informações conforme o layout de retorno. O retorno criará um grupo para cada RPS, contendo o número, série, situação, entre outros. Retornará também o número da NFS-e e o código de verificação, caso o RPS tenha sido convertido em NFS-e.

Agora que você já consultou uma NFS-e, podemos dar prosseguimento ao próximo passo.

Seu próximo passo é: Cancelar uma NFS-e.

Artigos Relacionados:

Emitindo uma NFS-e – Antigo

Última atualização em: 31 de julho, 2014

 

Neste artigo iremos demonstrar como realizar a emissão de NFS-e através do Web Service do InvoiCy.

A partir de agora, assumimos que você já leu o artigo Cadastrar uma Empresa via Web Service. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.

Primeiramente, vamos introduzir o conceito de RPS. O RPS – Registro Provisório de Serviços – é um documento fiscal que é gerado na prestação do serviço, sendo que ele deve ser enviado à prefeitura e, caso esteja na estrutura correta e com os dados devidamente preenchidos, é efetivado e convertido em NFS-e.

Desta forma, o processo inicia com a geração do RPS, transmissão a prefeitura e posterior conversão em NFS-e. A emissão de uma NFS-e é relativamente simples em termos de processo, sendo a parte mais complexa os valores que devem ser enviados à prefeitura para que a mesma seja efetivada. Para que isso se torne possível, siga os seguintes passos:

     1. Consumindo o Web Service
Primeiramente, você deve realizar o consumo do Web Service de  Recepção de RPS – https://gnfse.gnfe.com.br/apnuc134.aspx?wsdl

     2. Criar os RPSs para o envio
Embora cada prefeitura possua um layout de integração distinto, você sempre vai enviar ao InvoiCy os dados para emissão numa estrutura única, que abrange todos os municípios integrados. Os detalhes de como criar o XML e transmitir estão detalhados abaixo.

Para obter os Layouts de envio e retorno do XML de Recepção de RPS, faça download do arquivo RecepcaoRPS.zip. Nele você encontrará também o arquivo XSD e XML de exemplo.

O XML a ser enviado pode ser divido em duas partes: Cabeçalho (comum a todos os serviços – exceto no cadastro de prestador) e os dados do RPS (Tag <Lista>). A Tag Lista contém os dados do(os) RPS, e o cabeçalho contém os dados do emissor e a chave de comunicação. Para saber como gerar a Tag Lista corretamente e como gerar a Chave de Comunicação, consulte o artigo Gerar um XML de Envio passo-a-passo.

Após finalizado, o documento XML deve ser inserido entre as TAGS <nfse:Entradaxml> </nfse:Entradaxml> do SOAP de envio. Veja abaixo um exemplo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar a geração do XML de integração, disponibilizamos o XML de envio, bem como um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. Maiores detalhes no artigo Validação de arquivos XML.

 3. Realize a leitura do retorno do envio da NFS-e
Após o envio do XML, precisamos realizar a leitura do retorno da Recepção de RPS. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do serviço de Recepção de RPS de apenas um RPS enviado. O seu sistema deve ler o retorno, validando as informações conforme o layout de retorno. O retorno criará um grupo para cada RPS, contendo o número, série, situação, entre outros. Retornará também o número da NFS-e e o código de verificação, caso o RPS tenha sido convertido em NFS-e.

Agora que você já emitiu uma NFS-e, podemos dar prosseguimento ao próximo passo.
Seu próximo passo é: Consultar uma NFS-e.

Artigos Relacionados:

Gerar Espelho do RPS e NFS-e – Antigo

Última atualização em: 04 de maio, 2015

Há duas formas de gerar o Espelho do RPS e NFS-e, a primeira é via Sistema web e a segunda é via Web Service.

Nota: Enquanto a nota não estiver efetivada, o espelho sempre será impresso como RPS com avisos de que o documento não é válido como comprovante. A partir do momento em que a nota estiver efetivada, o sistema passará a imprimir a NFS-e, desde que no cadastro da empresa esteja marcada como SIM a opção “Imprime NFS-e se efetivada”.

O canhoto da nota é impresso no mesmo documento, contendo uma linha tracejada para corte. No cadastro da empresa existe a opção “Imprime Canhoto” com os valores Cabeçalho, Rodapé e Opcional, descritas abaixo:

  • Cabeçalho: o canhoto sempre será impresso no topo do documento, ou seja, acima dos dados da nota.
  • Rodapé: o canhoto sempre será impresso abaixo do documento, ou seja, depois de impressos os dados da nota.
  • Opcional: o canhoto será impresso no rodapé do documento desde que não ocorra quebra de página devido unicamente a presença do canhoto. Estas situações irão depender da quantidade de linhas do campo discriminação do serviço e o canhoto poderá retornar caso a nota em si já ocorra quebra de página.

A quantidade de linhas no campo discriminação do serviço que fará ou não com que o canhoto seja impresso depende do modelo de espelho.

NFS-e: O canhoto será impresso na mesma página do documento quando o campo discriminação do serviço tiver até 13 linhas. Entre 14 e 20 linhas o canhoto será oculto, pois ocasionaria quebra de página com apenas parte do canhoto. A partir de 21 linhas os dados da nota por si só já ocasionam quebra de página, disponibilizando espaço para que o canhoto possa ser impresso novamente.

RPS: Até 6 linhas na discriminação do serviço imprime o canhoto na mesma página. De 7 a 16 linhas o canhoto é oculto. A partir de 17 linhas os dados da nota provocam quebra de página, então imprime o canhoto novamente.

Gerar via Sistema web

Acessar o Sistema web e na listagem de notas da tela inicial, clicar sobre uma nota, irá abrir a tela de Detalhes do RPS, abaixo da mesma em Ações clicar no ícone espelho (Espelho RPS). Será gerado um PDF contendo os dados do RPS ou NFS-e conforme figura abaixo:

RPSEspelho RPS

Gerar via Web Service

A partir de agora, assumimos que você já leu o artigo Integrar com o InvoiCy NFS-e. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento desta etapa.

Para gerar via Web Service, primeiro é necessário realizar a integração, conforme os passos a seguir:

1. Consumindo o Web Service

Primeiramente, você deve realizar o consumo do seguinte Web Service https://gnfse.gnfe.com.br/aws_espelhorps.aspx?wsdl

2. Gerar o XML de envio

Nessa etapa é gerado um XML contendo os parâmetros da solicitação, dados de identificação da empresa e segurança no cabeçalho e uma lista de RPS que se deseja gerar o Espelho RPS. Os detalhes de como criar o XML e transmitir estão detalhados abaixo.

O XML a ser enviado pode ser divido em duas partes: Cabeçalho (comum a todos os serviços – exceto no cadastro de prestador) e os parâmetros para a consulta (Tag <ListaRPS>). Para saber como gerar os dados do cabeçalho, consulte o artigo Gerar um XML de Envio passo-a-passo.

O documento XML deve ser convertido para texto, e inserido entre as TAGS <nfse:Entradaxml> </nfse:Entradaxml> do SOAP de envio. Veja abaixo um exemplo:

Exemplo

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar a geração do XML de integração, disponibilizamos o XML de envio, bem como um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. Maiores detalhes no artigo Validação de arquivos XML.

3. Realizar a leitura do retorno


Após o envio do XML, precisamos realizar a leitura do retorno do processamento. O retorno recebido segue a seguinte estrutura SOAP:

ModeloSOAP

A estrutura SOAP acima demonstra o retorno do serviço de Espelho RPS de apenas um RPS requisitado.

O seu sistema deve ler o retorno, validando as informações conforme o layout de retorno. O retorno criará uma única tag (<EspelhoRPS>) contendo o PDF do Espelho RPS em base64. O arquivo PDF retornado conterá um espelho em cada página, na ordem passada no XML de envio. Retornará também mensagens de erro caso ocorra. Para informações de como decodificar o conteúdo da tag <EspelhoRPS> em arquivo PDF ver o artigo Exemplo de decodificação de base64 para arquivo.

Artigos Relacionados:

Gerar um XML de Envio passo-a-passo – Antigo

Última atualização em: 01 de agosto, 2014

 

Segurança dos Web Services

O InvoiCy NFS-e trabalha com um sistema de segurança em cada web service, trata-se de uma chave de segurança de 128 bits.

Cada nova empresa cadastrada no sistema recebe uma chave de acesso que, no momento de envio de algum XML será concatenada com o conteúdo do XML e criptografada em MD5, gerando a CK (chave de comunicação) que será enviada dentro da tag “<EmpCK>”. Para mais informações sobre a chave de acesso consulte o artigo Verificando a chave de acesso da empresa.

Cada cliente do InvoiCy NFS-e recebe uma PK (chave de parceiro) que deve ser enviada em todos os XML dentro da tag “<EmpPK>” , essa chave é a mesma usada para solicitar licenças e fará parte do processo de segurança do InvoiCy NFS-e.
A chave de parceiro é gerada por nosso Sistema de Gestão no momento que a sua empresa é cadastrada como nosso parceiro. A mesma será enviada por e-mail e utilizada para controlar as empresas de clientes finais que utilizarão licenças adquiridas pela sua empresa.

Exemplo do cabeçalho de um XML contendo a chave de comunicação e a chave de parceiro.

cabecalho_xmlCabeçalho com CK e PK

Para gerar a CK concatena-se a chave de acesso com o XML linearizado (remover quebras de linhas e espaços entre as tags). Nesse processo o cabeçalho do XML não é usado, apenas o conteúdo após a tag “</Cabecalho>”. Segue o exemplo para cada web service:

  • Recepção RPS é chave de acesso + <Lista>… </Lista> (sempre com todo o conteúdo da tag)
  • Consulta, Cancelamento e Download Espelho RPS é chave de acesso + <ListaRPS>…</ListaRPS>
  • Download XML é chave de acesso + <FaixaConsulta>… </FaixaConsulta>
  • Cadastro do prestador não utiliza a CK.

Após calcular o hash MD5 dessa string e o resultado será a CK. No caso de dúvidas ver o artigo Como gerar o código Hash MD5.

Gerar um XML passo-a-passo

De uma forma simplificada, a empresa precisa seguir os passos abaixo para criar um XML válido:

1. Gerar o XML a ser comunicado (sem o cabeçalho);

2. Linearizar o XML (remover quebras de linhas e espaços entre as tags);

3. Gerar a CK;

4. Montar o cabeçalho e inserir após o mesmo o XML gerado nos passos 1 e 2.

5. Todo esse XML deve ser convertido para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp. Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática.

6. Substituir os caracteres especiais/símbolos pela Entity number correspondente, por exemplo: “ç = ç”, “Ç = Ç”. Para mais informações consultar o artigo Entity number.

7. Incluir esse XML dentro da tag “EntradaXML” do SOAP.
Exemplo prático

Para facilitar o entendimento, segue um exemplo prático da criação de um XML:

1. Chave de acesso: JnL6wcTDt+hT42gROCYho6F4VTMCx0

2. XML de Recepção linearizado:

3. Chave de acesso e XML concatenado para geração da CK:

4. CK (Hash MD5) gerado sobre a string concatenada no passo 3: dd247a15c1e4fb3241f7e6f9de9cc38a

5. Cabeçalho gerado e concatenado com o XML:

Observe que a CK gerada foi incluída na tag <EmpCK>.

6. XML convertido para texto:

7. XML com os caracteres especiais/símbolos substituídos pela Entity number:

Observe a substituição destacada em vermelho na imagem e abaixo:
exemplo

 

8. XML inserido no pacote SOAP e pronto para envio ao InvoiCy NFS-e: