Guia rápido de uso de Web Services do NFS-e Easy

Transcrição

1 Guia rápido de uso de Web Services do NFS-e Easy NFS-e Easy V Produto: Guia rápido de uso de Web Services do NFS-e Easy V3.0.5 Release date: Mai,

2 Sumário 1. Introdução Requisitos e Compatibilidade NFS-e Easy Funcionamento do Web Service NFS-e Easy Retornos possíveis das chamadas Características de funcionamento dos sistemas nas prefeituras Descrição dos Web Services Disponíveis Web Services disponíveis Método EnviarCertificado Método EnviarRps Método ConsultarLote Método CancelarNfse Método Echo Descrição das mensagens de Retorno convertidas em Texto... Erro! Indicador não definido. Nomenclatura do documento Esta imagem significa que existe uma informação explicando uma característica do sistema, funcionalidade ou norma quanto à emissão da Nota Fiscal Eletrônica. Ao visualizar esta imagem, fique atento, pois descreve uma ação ou característica que dependendo do analista programar e/ou implementar para obter os melhores resultados. 2

3 1. Introdução A solução NFS-e Easy é uma solução robusta que atende diversos sistemas de Municípios compatíveis ou não com o ABRASF. Para obter maiores informações de requisitos e compatibilidade do Easy e característica de funcionamento de NFS-e nos Municípios e soluções disponíveis, consulte o guia PL NFS-e Easy - Apresentacao NFS-e Easy V3.0.pdf. 2. Requisitos e Compatibilidade NFS-e Easy O uso de Web Services requer o uso do certificado digital Tipo A1, somente. Caso tenha o certificado A3, não poderá utilizar neste modelo. O sistema para Web Services pode ser utilizado por qualquer linguagem de programação do ambiente Windows 32 como Delphi 5/6/7 e posteriores, VB 6.0, VBA, VFP 8.0/9.0, C++, ASP, ambiente.net como C#, VB.NET, Delphi.NET, ASP.NET entre outros, linguagem Java, PHP, entre outros. Não existem restrições quanto ao ambiente onde roda o sistema do Cliente, suportando aplicações em Windows, Linux e outros. A emissão será efetuada sempre pela Web. O sistema poderá emitir os RPS normalmente e encaminhar no momento da emissão ou no prazo estipulado pelo Município para emissão da NFS-e. 3

4 3. Funcionamento do Web Service NFS-e Easy A chamada dos Web Services é disponibilizada através de um Data Center. O método recebe como entrada um documento formato TXT (ver PL NFS-e Easy - Manual de conversão de dados TXT para XML NFS-e Easy V2.0.pdf ). O método ao receber o documento, converte em XML, assina com o certificado digital e executa a comunicação diretamente com o portal do Município, estabelecendo o canal seguro em conjunto com o Servidor da PM, retornando o resultado ao sistema de gestão em um formato TXT. O processo de emissão é simples: 1. Envio do Certificado: i. Para o ERP executar a chamada, deverá encaminhar o certificado digital usando o método EnviarCertificado. ii. O certificado digital e a senha ficarão armazenados no repositório no Data Center; 2. Envio de um Lote de RPS i. Sistema executa método EnviarRps encaminhando o lote de RPS; 3. Consultar a situação do Lote i. Este método somente é utilizado se o método de envio retornar um protocolo ii. A aplicação periodicamente ou por ação de um usuário (alguns Municípios demoram 20 a 30s, outros processam de 5 em 5 minutos...), executa o método ConsultaLoteTxt; 3.1 Retornos possíveis das chamadas a) A chamada a estes métodos poderá retornar um TXT como resultado contendo: i. Mensagens de erro ou alerta ii. Resumo das NFS-e do lote iii. Protocolo de entrega Quando o certificado estiver faltando, inválido ou vencido, a chamada de Envio retornará um alerta identificando esta situação. 4

5 3.2 Características de funcionamento dos sistemas nas prefeituras a. Modelo Síncrono: i. A chamada de Envio do Lote retorna o resumo da NFS-e (processada com sucesso) ou mensagem de erro / alerta; Suportado na ABRASF V2.0 e Municípios como São Paulo, por exemplo. b. Modelo Assíncrono: i. A chamada de Envio do Lote retorna um protocolo ou mensagem de erro/alerta; Suportado na ABRASF V1.0, 1.4, 1.7. Ambos os Modelos: O sistema deve estar preparado para qualquer modelo, pois podem ocorrer numa mesma Prefeitura. Há Prefeituras que limitam a quantidade de RPS s ou o tamanho da mensagem num mesmo Lote. Exemplos: o Lotes com até 5 RPS s são processados imediatamente, enquanto os demais são agendados para processamento fora do expediente o Não são aceitos Lotes (XML assinado) com mais de 512 Kb Município encaminha ao TOMADOR o link da NFS-e aprovada, que poderá gerar a NFS-e em formato PDF ou XML, dependendo do Município. Sistema de gestão não precisa se preocupar com guarda de XML ou geração de PDF, pois é suportado pelo Município. i. Os dados da NFS-e estão disponíveis no portal do Município. ii. Não é gerada uma NFS-e em PDF, pois em alguns Municípios, é proibido o envido de documentos PDF que não sejam gerados pelo mesmo. iii. Não existe obrigação acessória para guarda do XML, logo, o mesmo é descartado e não retorna na chamada do Web Service. 5

6 4. Descrição dos Web Services Disponíveis Os métodos disponíveis são discutidos na sequencia. O endereço do Web Service será disponibilizado pela Benefix (URL) em homologação, aplicando a URN /nfsews/nfseeasyws.asmx ; Exemplo endereço ambiente de testes: Note que os nomes dos Métodos são os mesmos para os endereços com retorno TXT ou XML Na aplicação, deverá utilizar o WS mapeamento estático, evitando que a todo momento o sistema de gestão faça a comunicação com o WS para baixar o WSDL. Este Guia apresenta as interfaces para os retornos em formato TEXTO, convertento o XML recebido da chamada em uma saida texto padrão. Caso queira encaminhar os documentos e manipular o protocolo recebido em formato XML, deverá usar outro Web Service (NfseEasyWsXml.asmx), que não fará a conversão para o formato texto, exibido neste guia. 6

7 Ambos têm funcionalidades idênticas, a diferença será o retorno do método, que será ou um formato padrão texto (neste guia) ou o retorno XML do processamento do WS do Município e que não possuem um formato padrão, mesmo quando se tratando de ABRASF. Outros Métodos poderão ser disponibilizados. Caso tenha alguma necessidade específica, consulte previamente a Benefix. Recomendamos encaminhar lotes de RPS individuais para simplificar a emissão. No modelo municipal, a recusa de um documento, invalida todo o lote, diferentemente do modelo do projeto NF-e Nacional, que processa os documentos individualmente. 4.1 Web Services disponíveis CancelarNfse : Permite cancelar uma NFS-e. ConsultarLote: Permite consultar o Lote enviado e ter a resposta do seu processamento. Echo: Metodo para testar se a Interface do Município está implantada. EnviarCertificado: Processo de envio do certificado para a aplicação. EnviarRps: WS utilizado para enviar o lote gerado pelo ERP. Na sequência, serão apresentados os métodos com mais detalhes. 7

8 4.2 Método EnviarCertificado Recebe o CONTEÚDO do certificado (.pfx), salvo com a chave privada e conteúdo estendido (cadeia de certificados intermediários e raiz salvas no certificado quando exportado), em formato Base64. Parâmetros: Sendo: <ambiente>string</ambiente> <token>string</token> <cnpj>string</cnpj> <base64certificado>string</base64certificado> <senha>string</senha> TOKEN: autorização do uso do Web Service fornecido pela Benefix; CNPJ: o cnpj do emitente do Rps; BASE64CERFIFICADO: arquivo PFX com a cadeia de certificados e exportado com a chave privada, convertida como Base64 para encaminhar via WS; SENHA: do certificado digital; Retornos: <EnviarCertificadoResult>int</EnviarCertificadoResult> <retmsg>string</retmsg> O método retornará um valor inteiro POSITIVO quando Sucesso na operação ou NEGATIVO com descrição da mensagem se ocorrer algum erro ou certificado for inválido. Exemplo em C# para conversão de um arquivo PFX lido em disco para base64: /* Caminho em disco do Certificado Tipo Pfx Exportado com Chave Privada */... string m_path; if (File.Exists(m_path)) { byte[] bytes = System.IO.File.ReadAllBytes(m_path); string base64string = System.Convert.ToBase64String(bytes, 0, bytes.length) return (base64string); } else {... /* Ação caso não encontre o certificado */ } 8

9 4.3 Método EnviarRps Recebe o CONTEÚDO do arquivo de lote de RPS em formato TXT conforme modelo de estrutura do Guia PL NFS-e Easy - Manual de conversão de dados TXT para XML NFS-e Easy V2.0.pdf Parâmetros: <ambiente>string</ambiente> <token>string</token> <codibgemunicipio>string</codibgemunicipio> <cnpj>string</cnpj> <rps>string</rps> TOKEN: autorização do uso do Web Service fornecido pela Benefix; CODIBGEMUNICIPIO: Código do Município onde será emitida a NFS-e CNPJ: o cnpj do emitente do Rps; RPS: Rps em formato TXT em acordo com o documento PL NFS-e Easy - Manual de conversão de dados TXT para XML NFS-e Easy V2.0.pdf Retornos: <EnviarRpsResult>int</EnviarRpsResult> <retmsg>string</retmsg> O método retornará um valor inteiro POSITIVO quando Sucesso na operação ou NEGATIVO para erro com descrição da mensagem se ocorrer algum erro ou certificado for inválido. Mensagens de Retorno (retmsg) do método Mensagem Processada (SUCESSO); Mensagem em Processamento; Mensagem de Erro ou Alerta; Mensagens de retorno descritas e exemplificadas na seção 2 do PL NFS-e Easy - Manual de Retornos TXT (Abrasf)V3.0.pdf. 9

10 4.4 Método ConsultarLote Nos Municípios que não possuem suporte para os WS SÍNCRONOS, será retornado um protocolo através do método EnviarRps para o cliente. Ao executar a consulta do LOTE, o mesmo pode estar em processamento ou ter sido concluído. Se aprovado, recebe o numero da NFS-e, caso constrário, as mensagens de Alerta e Erro. Parâmetros: <ambiente>string</ambiente> <token>string</token> <codibgemunicipio>string</codibgemunicipio> <cnpj>string</cnpj> <inscricaoemissor>string</inscricaoemissor> <protocolo>string</protocolo> TOKEN: autorização do uso do Web Service fornecido pela Benefix; CODIBGEMUNICIPIO: Código do Município onde será emitida a NFS-e INSCRICAOEMISSOR: a Insc. Municipal do Emitente (PRESTADOR); PROTOCOLO: número do protocolo retornado pelo método EnviarRps; Retornos: <ConsultarLoteTxtResult>int</ConsultarLoteTxtResult> <retmsg>string</retmsg> O método retornará um valor inteiro POSITIVO quando Sucesso na operação ou NEGATIVO para erro com descrição da mensagem se ocorrer algum erro ou certificado for inválido. Mensagens de Retorno (retmsg) do método, ver seções: Mensagem Processada (SUCESSO); Mensagem de Erro; Mensagem de Consulta de situação; Mensagens de retorno descritas e exemplificadas na seção 2 do PL NFS-e Easy - Manual de Retornos TXT (Abrasf)V3.0.pdf. 10

11 4.5 Método CancelarNfse Recebe um documento XML de entrada e retorna um XML identado para apresentação em tela, por exemplo. É utilizado este método para registrar as respostas das secretarias via Web Services quando em modo DEBUG para facilitar a compreensão e análise do retorno. Parâmetros: <ambiente>string</ambiente> <token>string</token> <codibgemunicipio>string</codibgemunicipio> <cnpj>string</cnpj> <inscricaoemissor>string</inscricaoemissor> <numnfse>string</numnfse> <codcancelamento>string</codcancelamento> TOKEN: autorização do uso do Web Service fornecido pela Benefix; CODIBGEMUNICIPIO: Código do Município onde será emitida a NFS-e CNPJ: o cnpj do emitente do Rps; INSCRICAOEMISSOR: a Insc. Municipal do Emitente (PRESTADOR); NUMNFSE: número da NFS-e que deseja cancelar; CODCANCELAMENTO: Segundo o Manual ABRASF, não é fornecido à descrição do cancelamento, mas um código. Consulte o Manual ou o Município com os códigos de cancelamento disponíveis; Retornos: <ConsultarLoteTxtResult>int</ConsultarLoteTxtResult> <retmsg>string</retmsg> O método retornará um valor inteiro POSITIVO quando Sucesso na operação ou NEGATIVO para erro com descrição da mensagem se ocorrer algum erro ou certificado for inválido. Mensagens de Retorno (retmsg) do método, ver seções: Mensagem de Cancelamento; Mensagem de Erro; Mensagens de retorno descritas e exemplificadas na seção 2 do PL NFS-e Easy - Manual de Retornos TXT (Abrasf)V3.0.pdf. 11

12 4.6 Método Echo Recebe um documento XML de entrada e retorna um XML identado para apresentação em tela, por exemplo. É utilizado este método para registrar as respostas das secretarias via Web Services quando em modo DEBUG para facilitar a compreensão e análise do retorno. Parâmetros: <ambiente>string</ambiente> <codibgemunicipio>string</codibgemunicipio> <textoecho>string</textoecho> AMBIENTE: poderá ser [Homologação Produção] (com ou sem acento gráfico); CODIBGEMUNICIPIO: Código do Município onde será emitida a NFS-e TEXTOECHO: o texto de teste encaminhado para teste de echo; Retornos: <EchoResult>string</EchoResult> Este é o único método que não retorna um valor inteiro, somente a mensagem de echo, com ou sem erro. Exemplo de retorno ECHO em TXT Foram inseridas quebras de linha para melhor apresentação do texto. Exemplo de retorno ECHO em XML Foram inseridas quebras de linha para melhor apresentação do texto. 12

13 Exemplo ECHO em uma chamada de WS via http, notem que é uma stream retornada ao seu método em uma variável tipo string, em texto ou xml. Abaixo, exemplo do retorno sem formatação. Observe que a informação <string> define o tipo e não será retornado ao parâmetro de retorno da mensagem ao seu método, somente o conteúdo da mesma. 13

14 5. Mensagens de Retorno Xml convertidas em Texto Consulte a seção 2 do PL NFS-e Easy - Manual de Retornos TXT (Abrasf)V3.0.pdf. Neste guia existe a definição das mensagens de retorno e exemplos em diversos sistemas. Caso deseje mais informações, favor contatar: Benefix Sistemas e Gestão de Negócios Ltda. +55 (21) / +55 (41) (21) [email protected] URL: 14