A emissão de NFS-e pode ser um processo complicado devido à multiplicidade de layouts de integração,
há diferentes necessidades de cada município, diferente fornecedor do sistema de NFS-e
e a inexistência de uma padronização.
Existe um projeto de um modelo de integração, com especificação de layout de XML's, especificação de como compor uma solicitação de serviço da web e a descrição da interface que fornecida pelo provedor (WSDL),
modelo de comunicação (HTTPS com certificado digital ICP-Brasil) orientado pela ABRASF (Associação Brasileira das Secretarias de Finanças das Capitais),
para ser seguido pelos municípios e fornecedores de software. Este modelo definiu somente a orientação dos dados do xml, deixando de padronizar as interfaces de comunicação.
No mercado, alguns fornecedores de sistemas já tinham seu modelo próprio de integração antes da publicação do modelo ABRASF.
Outros fornecedores seguiram o padrão ABRASF, mas com diferenças nos namespaces dos XML's personalizando a aplicação, utilizaram uma das muitas
versões ABRASF (1.00, 1.04, 1.07, 2.00, 2.01, 2.02) para dados e aplicaram sua própria autenticação (p. ex. uns seguem o padrão com autenticação por certificado digital, outros utilizam usuário e senha).
Na prática, mesmo os fornecedores que "seguem" o modelo ABRASF necessitam de sua própria implementação, o que torna um caos o desenvolvimento.
Dentre os diferentes modelos existentes nos municípios, podemos citar algumas soluções de fornecedores: WebISS, Betha, GINFES, ISSNet, Thema,
Abaco, Tiplan, DSF, ou modelos próprios, por exemplo, São Paulo, Curitiba, Rio de Janeiro, Belo Horizonte (compartilhou para POA) entre outros.
Estima-se haver mais de 270 soluções de ISSQN pulverizadas no país. Apenas 20 soluções com cobertura de 30 ou mais municípios tendem a
oferecer um modelo Abrasf mais estável, mas ainda assim, com algum tipo de personalização na implementação.
O Nfse Easy oferece as empresas uma plataforma para desenvolver uma única integração para emissão de NFS-e. Não é necessário conhecer o layout de cada município,
nem se preocupar com a comunicação em cada cidade, esse processo é feito pelo Nfse Easy.
Em outras palavras, é o Nfse Easy que faz a ponte entre os sistemas dos contribuintes e qualquer município que disponibilize a integração com a NFS-e.
O modelo de integração Nfse Easy utiliza um modelo NACIONAL de dados de entrada em formato TXT ou JSON e contém 3 componentes:
Web Services: Os Web Services são a interface que será mais frequentemente utilizada pelo sistema de gestão para a comunicação com o software emissor de NFS-e (este software).
Windows Service: O serviço do windows é o responsável por processar os documentos (enviá-los a PM, consultá-los e cancelá-los).
Interfaces Web: A Interface Web fornece uma forma prática de visualização de empresas cadastradas e documentos.
2. Vamos Começar!
Você precisará cadastrar um login e senha para aproveitar todos os benefícios desta extraordinária ferramenta. No ambiente de homologação, você pode usar:
Nota
Para testes você pode utilizar os dados da BENEFIX
LOGIN : "nfse"
SENHA : "benefix"
2.1 Meu Usuário
Efetue o registro na Interface WEB para obter um usuário e senha, que também será utilizado como autenticação para os Web Services
Após criação do usuário, o próximo passo é cadastrar a empresa, que pode ser feito tanto pela Interface WEB quanto
por Web Service. Clique aqui para descrição dos serviços disponíveis para Emitente.
Com suas credênciais devidamente criadas, sua aplicação já poderá utilizar os Serviços descritos no Web Service
NfseEasyService - Serviço da Web (endereço de homologação da Benefix).
3. Web Services
Os serviços web são independentes de plataformas e de linguagem, foram desenvolvidos para a
construção de aplicativos que se comunicam usando protocolos web padrão e formatos de dados como HTTP, SOAP e XML,
estes utilizados também nas soluções Mercantil (NF-e) e Varejo (NFC-e).
Os serviços web foram desenvolvidos e disponíveis em WCF, sendo descritos também em ASP.NET (.aspx) a partir do WCF, para serem consumidos de
acordo com sua escolha e facilidades da tecnologia, suportando o protocolo http ou https.
Fornecimento de API para a construção de serviços RESTful padronizados, baseados em OData V4 no .NET, somente em outros produtos Benefix usando tecnologia Microsoft RESTier.
Os métodos disponíveis em ambiente de homologação ou produção estão publicados e podem ser consultados nos endereços (.asmx) ou (.svc).
O WSDL é uma notação XML para descrever um serviço da web. Uma definição WSDL descreve o serviço, especifica como
acessá-lo e quais as operações ou métodos disponíveis são suportados. O WSDL 1.2 foi renomeada para 2.0 e aceita
todos os métodos de requisição HTTP (não apenas GET e POST).
Para acessar o WSDL dos seriços disponíveis, adione "?wsdl" ao final da URL. O serviço WCF (.svc) também permite
acessar um arquivo único adicionando "?singleWsdl" ao final da URL.
<xs:documentation>1 Nao Recebido (nao enviado) 2 Nao Processado 3 Processado com Erro 4 Processado com Sucesso 9 Descartado (ocorre apos varias tentativas de envio fracassadas)</xs:documentation>
O Web Service sempre retornará uma estrutura com o elemento raiz <RetNfseEasyWs>.
O Modelo padrão de retorno da chamada com os elementos básicos em formato resumido é apresentado
abaixo e será discutido nas próximas seções.
Elemento raiz <RetNfseEasyWs>
O Web Service sempre retornará uma estrutura RetNfseEasyWs com o elemento
filho WebService e,
dependendo da operação com Emitente ou Documento Rps, o elemento
filho Emitente ou Documento.
A estrutura de qualquer chamado disponível, SEMPRE terá o seguinte formato.
4.1 Detalhes do Elemento <WebService>
O retorno do chamada do serviço sempre terá uma a estrutura WebService.
Se executar a operação e não houver erros na chamada, retornará "Sucesso", mesmo que um documento processado
seja rejeitado ou, a atualização de um emitente não possa ser executada.
Esta estrutura é relacionada a chamada do WebService e não ao processamento de documentos ou dados de emitentes.
Resposta de uma operação com sucesso!
Note que uma resposta de SUCESSO significa que o WS respondeu a operação e processou corretamente, retornado o código,
descrição e detalhe~, mesmo que tenha uma solicitação de importação ou cancelamento que possam ter alguma rejeição.
Código:Códigos da operação do processamento do Web Service NFS-e Easy, não tem relação com o Município.
Descrição:Em uma chamada de Web Service, além do código, segue a descrição da ação, facilitando o entendimento.
Detalhe:Quando ocorrer algum problema de comunicação com o Web Service, será informado em mais detalhes os erros.
Abaixo, uma visão com mais detalhes do elemento Emitente e Documento, que serão discutidos nas próximas seções.
4.2 Detalhes do Elemento <Emitente>
A resposta terá um 'Status do Emitente' e quando solicitados os dados em uma consulta, os mesmos serão retornados em um formato XML codificado em Base64, exemplificados na seção 7.2.
O emitente poderá realizar algumas tarefas, como enviar os dados pelo WS para criar o emitente (CNPJ), alterar o status ou até mesmo atualizar os dados cadastrais ou certificado digital.
4.3 Detalhes do Elemento <Documento>
O elemento documento sempre será formado pelos elementos descritos no item Retorno Web Service.
SearchKey:
Chave de pesquisa formado por um número aleatório + cnpj + num rps
XmlDoc:
Documento XML retornado pelo Município, pode conter um RPS convertido em NFS-e ou mensagens de erros, retornado em formato Base64
ConsultaLote:
Elemento que contem estrutura de dados do lote enviado, detalhado na sequência
ConsultaRps:
Elemento que contem estrutura de dados do rps enviado, detalhado na sequência
ConsultaStatusCancelamento:
Elemento que contem informação sobre o Status de um Cancelemento solicitado
Um retorno XML com o elemento DOCUMENTO, deverá ter um dos elementos de Consulta presente (lote, rps ou cancelamento).
5. Detalhes do elemento Documento
Será apresentado o detalhamento do elemento da Consulta de um elemento Documento, resumidamente,
apresenta a consulta de um Lote (autorizado ou rejeitado) ou da consulta do processamento de uma
solicitação de cancelamento. Nas próximas seções, discutiremos cada uma destas respostas de consulta.
5.1 Consulta Documentos
Os elementos TentativaEnvio e TentativaConsulta da imagem abaixo, são configurados no sistema para determinar a quantidade máxima de tentativas de envio e consulta que o sistema poderá realizar automaticamente no Município.
Ao atingir este limite, o sistema modifica a situação do documento, deixando-o em situação de "bloqueio", pois se tiver um erro no Município ou no retorno, a consulta deve em determinado tempo, gerar uma ação de sucesso ou erro de consulta.*
TentativasEnvio:
Após uma determinada quantidade de tentativas de envio sem sucesso, o lote é automaticamente descartado. O número de tentativas de envio permite identificar que o sistema está em funcionamento e tentando concluir a operação, pois o Município ou Link Internet podem estar com problemas.
TentativasConsulta:
Após uma determinada quantidade de tentativas de consulta sem sucesso, o lote é automaticamente descartado. O número de tentativas de consulta permite identificar que o sistema está em funcionamento e tentando concluir a operação, pois o Município ou Link Internet podem estar com problemas.
ListaNfse:
Lista de documentos NFse, consultar Manual de Integração Abrasf, segue mesmo modelo de retorno.
ListaMensagem:
Lista de Erros ou Alertas, consultar Manual de Integração Abrasf, segue mesmo modelo de retorno. Ou quando ocorrer algum problema de comunicação com o Município, será informado em mais detalhes os erros da transação, com: Código, Mensagem e Correção
5.1.1 Lista Nfse
Os campos ListaNfse descrevem os dados das NFS-e geradas, caso tenha enviado um Lote com um RPS, terá uma lista com uma única NFS-e.
Numero:número da nfse gerada pelo Município
CodigoVerificacao:código de verificação da nfse quando existir
DataEmissao:data de emissão da nfse
DataCancelamento:data de cancelamento se existir
CodigoCancelamento:mesmo código fornecido na chamada do cancelamento e que identifica o motivo do cancelamento
IdentificacaoRpsidentifica os dados do RPS que gerou a NFS-e, composto por "Numero", "Serie" e "Tipo"
LinkPdf:Quando o Município fornecer um Link, este será retornado dentro da ListaNfse.
Observe que o retorno é XML, logo, se o Município utiliza caracteres especiais, este será Codificado em Html, logo, deverá ser tratado para poder utilizar.
HtmlEncoded no LinkPdf
DE: http://nfps-e.pmf.sc.gov.br/consulta-frontend/#!/consulta?cod=3C7CD91EAD20406D&cmc=1234567
Campos ListaMensagem geralmente informam um condição de erro de um ou mais dados do RPS
Codigo:código de erro gerado pelo Município
Mensagem:descrição do erro gerado pelo Município, quando existir
Correcaoquando existir, orienta na correção do erro
IdentificacaoRpsopcional, se existir, identifica os dados do RPS que gerou os erros, composto por "Numero", "Serie" e "Tipo"
Detalhes dos Campos ListaNfse e ListaMensagem
5.2 Consulta Cancelamento
A ConsultaCancelamento SOMENTE retorna dados da NFS-e, nunca de um lote pela Searchkey, pois podem haver várias Nfse
pertence ao elemento Documento.
Possui informações sobre a Situação do Cancelamento de uma NFSe se existir ou ListaMensagemRetorno retornados pelo Município.
Retornará dados da Nfse Cancelada, se existir.
Erros ou Alertas serão retornados na ListaMensagem que contém uma ou mais mensagens no campo Mensagem.
Nota
O XML do retorno do Cancelamento ou da ListaMensagemRetorno do Cancelamento estará codificada em Base64 dentro do Elemento DOCUMENTO na Tag <XmlDoc>
6. Códigos e Status Retornados
Esta seção descreve os CÓDIGOS e STATUS retornados no elemento Documento e no elemento WebService relacionados ao estado de processamento destes.
Códigos Retorno WS
Nesta seção, serão apresentados os códigos retornados pelo elemento RetNfseEasyWs/WebService/Codigo (fig.1),
códigos no elemento RetNfseEasyWs/Consulta/SituacaoLote (fig.2), e na sequência do resumo do status da NFS-e no
elemento RetNfseEasyWs/Consulta/ListaNfse/Nfse/Status (fig.3), descritos nos tópicos na sequência.
Todos os códigos retornados nas consultas do Web Service estão inseridos nos retornos das consultas do Web Service em formato XML, descrito no arquivo de XML Schema Definition
Elemento Situacao do LOTE na tag <RetNfseEasyWs/Documento/Consulta/SituacaoLote>.
O Código da Situação reflete o status do processamento do Lote a ser encaminhado ao Município, em processamento
ou já processado pelo mesmo, os detalhes da estrutura foram apresentadas na seção 5.1.
1
Não Recebido (Não Enviado)
2
Não Processado
3
Processado com Erro
4
Processado com Sucesso
5
Aguardando Processamento (Documento sem retorno da prefeitura no envio, será feita tentativa de consulta pelo RPS)
9
Descartado (ocorre após várias tentativas de envio fracassadas)
Códigos 1, 2, 3 e 4 são mantidos iguais aos Status da Abrasf, facilitando o entendimento.
Nota
Observe o exemplo abaixo, note que este retorno possui uma tag NFS-e <Nfse> .... <Nfse>, este é o retorno padrão sempre que o documento for processado com sucesso.
<XmlDoc>PENvbXBOZnNlPg0K...[XML em BASE64]...Db21wTmZzZT4=</XmlDoc>
<Consulta>
<SituacaoLote>4</SituacaoLote>
<ListaNfse>
<Nfse>
<Numero>201400000000022</Numero>
<CodigoVerificacao>K2C9-TKKH</CodigoVerificacao>
<DataEmissao>04/08/2014 19:02:49</DataEmissao>
<Status>1</Status>
</Nfse>
</ListaNfse>
</Consulta>
</Documento>
</RetNfseEasyWs>
6.3 Códigos de processamento do Serviço Web
Os códigos apresentados nesta seção, são os códigos utilizados pelo Serviço Web NFS-e Easy®, estarão sempre dentro do
elemento <RetNfseEasyWs>/<WebService>.
Referem-se ao status do processamento do método. Ver detalhes do elemento <WebService> em 4.1
É importante compreender que estes códigos não são os códigos de erro ou alerta retornados do serviço do município na tag <Mensagem>.
0
Operação realizada com sucesso
1
Usuário e senha inválidos
2
CNPJ não encontrado na base de dados
3
Município não encontrado na base de dados da aplicação dos Web Services. Confirme o CódigoIbge ou acione o suporte
4
Certificado digital emitente inválido. Atualize o mesmo
5
Lote TXT está em formato inválido
6
XML dos dados do emitente inválido
7
Falha de validação em algum dos campo dos dados do emitente. Favor corrigir
Emitente suspenso, somente operações de consulta autorizadas
12
NFS-e não encontrada por chave de busca
13
Lote XML está em formato inválido
14
Lote não encontrado por chave de busca
15
NFS-e já se encontra cancelada
16
Usuário não possui autorização para o CNPJ e não é Administrador
17
Erro inesperado, verifique o log
18
NFS-e não está cancelada
19
Certificado não possui a cadeia completa, exporte com toda a cadeia para processar corretamente
20
Certificado Vencido, atualize seu certificado antes de emitir NFS-e
21
Certificado Nulo ou inexistente - falha de conversão PFX - Tipo X509
22
Emitente bloqueado para alteração, não é possível atualizar os dados
23
Parâmetro CNPJ não informado
24
Erro nos dados do TXT
25
Erro ao criar licença da empresa
26
Erro na chamada do Webservice
27
Número inicial não é um inteiro
28
Número final não é um inteiro
29
Número inicial é maior que o número final
30
Ano não é um inteiro
31
Série não é um inteiro
32
Justificativa está em branco
33
Emitente não encontrado
34
Erro ao inutilizar notas
35
Município não possui inutilização de notas
36
Nenhum evento localizado. Tente mais tarde novamente
37
Erro ao acessar a rede com um protocolo conectável ou Serviço Município não disponível
38
Usuário EXCLUSIVO para testes ambiente Homologacao, bloqueado para qualquer alteração, não é possível atualizar os dados
39
Falha na carga do certificado, verifique se é um certificado válido com chave privada (*.pfx) e em formado Base64.
40
Falha na carga do certificado, recebido certificado sem a chave privada. Ao exportar, selecione exportar Chave Privada. Não envie arquivo .crt ou .cer (chave pública), usar somente .pfx (chave privada) em Base64.
41
Usuário não encontrado.
42
A chave de pesquisa (SearchKey) não pertence ao Cnpj informado.
43
Erro nos parametros informados na chamada do Webservice.
44
NFS-e não está cancelada. Pode ter ocorrido uma falha na solicitação do Cancelamento, verifique no portal do Município.
45
O processamento da requisição está em andamento, aguarde alguns instantes e tente novamente.
Observe o exemplo de dois retornos, um de sucesso e outro com um código de erro, a tag Codigo dentro da tag WebService
Clique aqui para mais informações sobre estrutura de dados e utilização do serviço.
7.2.2 Atualização Cadastral do Emitente
A atualização das informações do emitente é realizada através do método GerenciarEmitente(...),
permite atualizar qualquer informação do emitente, exceto o CNPJ.
Indique o emitente a ser atualizado, através do campo <Cnpj>, e indique o campo que será atualizado.
O exemplo a seguir realiza a atualização do endereço de e-mail do emitente:
Os dados a serem enviados
<?xml version="1.0" encoding="utf-8"?>
<DadosEmitente>
<Cnpj>06039615000108</Cnpj>
<Email>contato@e-benefix.com.br</Email>
</DadosEmitente>
O exemplo a seguir realiza a atualização do status do emitente, definindo-o como bloqueado:
Os dados a serem enviados
<?xml version="1.0" encoding="utf-8"?>
<DadosEmitente>
<Cnpj>06039615000108</Cnpj>
<StatusEmitente>Bloqueado</StatusEmitente>
</DadosEmitente>
Nota
Os campos telefone e e-mail não são obrigatórios, no entanto quando informados, deverão estar em formato válido.
LOGOTIPO: preferencialmente 96px e tamanho menor que 20KB (Imagem PNG em BASE64)
A tag <RetornarDadosEmitente> é utilizado para solicitar ao serviço os dados do emitente, os valores permitidos são true ou false, quando a tag não for informada, por definição será false. Os dados do emitente serão retornados em formato base64.
Clique aqui para mais informações sobre estrutura de dados e utilização do serviço.
<DetalheCertificado>CN=BENEFIX SISTEMAS E GESTAO DE NEGOCIOS LTDA:06039615000108, OU=presencial, OU=34038808000180, OU=RFB e-CNPJ A1, OU=Secretaria da Receita Federal do Brasil - RFB, L=NITEROI, S=PR, O=ICP-Brasil, C=BR</DetalheCertificado>
Caso o certificado não esteja cadastrado, não retornará a tag <ValidadeCertificado>, já a tag <DetalheCertificado> retornará a mensagem "O Certificado não é válido". Observe o exemplo abaixo.
<DetalheCertificado>O Certificado não é válido</DetalheCertificado>
</Emitente>
</RetNfseEasyWs>
7.2.3 Consultar Emitente
A consulta dos dados do emitente também é realizada através do método
Emitente, utiliza-se o cnpj como identificador e a tag
<RetornarDadosEmitente> com valor true, exemplo:
<RetornarDadosEmitente>true</RetornarDadosEmitente>
O formato da resposta do serviço é padrão, observe abaixo que os dados do emitente está sendo retornado em formato base64 na tag <XmlEmitente>.
<DetalheCertificado>CN=BENEFIX SISTEMAS E GESTAO DE NEGOCIOS LTDA:06039615000108, OU=presencial, OU=34038808000180, OU=RFB e-CNPJ A1, OU=Secretaria da Receita Federal do Brasil - RFB, L=NITEROI, S=PR, O=ICP-Brasil, C=BR</DetalheCertificado>
Clique aqui para ver a assinatura do método de consulta
7.3 Importar Lote RPS
O método SolicitarImportacaoLoteRps recebe a chamada para importar de um lote de RPS a partir do TXT enviado ou JSON quando disponibilizado.
O sistema da Benefix® realiza a conversão do TXT em XML e envia para o serviço do Município.
Nota
Recomenda-se que use um RPS por LOTE, pois se um RPS for rejeitado, todo o LOTE será rejeitado. Para evitar transtornos, execute sempre 1 LOTE com 1 RPS. Em Municípios com tempo de processamento muito alto, envio de vários RPS em um Lote é recomendado, mesmo com o risco de rejeitar os documentos por um erro em um RPS.
Consulta documentos pela chave ou chave e número de RPS
Nota
A partir de Julho de 2018 o método de consulta retorna o elemento "LinkPdf" para cada RPS/NFS-e. Este elemento contém o link do PDF da prefeitura, quando existe, ou o endereço com um PDF padrão da Benefix®.
Note que o número do RPS é opcional, ao consultar somente pela chave (sem informar o parâmetro numRps) o retorno é do lote e todos os seus RPS's. Caso o parâmetro numRps também seja preenchido, o retorno é do lote com somente o Rps solicitado.
7.4.1 Exemplo de Consulta de Lote com apenas um RPS
Exemplo do retorno de uma CONSULTA de um Lote com um RPS importado e autorizado
<Mensagem>O número do lote do contribuinte informado já existe.</Mensagem>
<Correcao>Lote do contribuinte: 2008, Protocolo: 00000000000000000000000000000000000000000000370612o</Correcao>
</Mensagem>
</ListaMensagem>
</Consulta>
</Documento>
</RetNfseEasyWs>
Nota
O elemento <XmlDoc> contém os dados retornados pelo Município, o mesmo é codificado em Base64. Neste exemplo, decodificando o XML obtém-se o XML original do Municipio com o erro reportado
<Mensagem>O número do lote do contribuinte informado já existe.</Mensagem>
<Correcao>Lote do contribuinte: 2008, Protocolo: 00000000000000000000000000000000000000000000370612.</Correcao>
</MensagemRetorno>
</ListaMensagemRetorno>
</EnviarLoteRpsResposta>
7.5 Solicitar Cancelamento de NFS-e
O Método SolicitarCancelamentoNfseGenerico() utilizado para realizar o cancelamento de uma NFS-e, é concluído em duas etapas, SOLICITAÇÃO (Um Pedido de Cancelamento) e CONSULTA RESPOSTA CANCELAMENTO (Consulta se o cancelamento foi aprovado pelo município)
Nota
Este serviço é ASSÍNCRONO, ele insere o pedido do Cancelamento na fila de processamento, neste momento, ainda NÃO está cancelada. Será necessário realizar uma consulta do status deste processamento para receber o resultado se autorizado ou rejeitado
<Descricao>Operacao realizada com sucesso</Descricao>
<Detalhe>Agendado o pedido de cancelamento em 05/05/2021 14:14:24,
neste momento ainda nao esta cancelada.
Consulte a Resposta do pedido em poucos minutos.
</Detalhe>
</WebService>
</RetNfseEasyWs>
7.5.2 ConsultarStatusCancelamento (Consultar a Resposta do Pedido Cancelamento)
Consulta a resposta da solicitação de um pedido de cancelamento de uma NFS-e
Ao solicitar um pedido de cancelamento, o pedido é inserido em uma fila de processamento pelo "serviço" do sistema NFS-e Easy Web, portanto, o sitema Cliente (ERP) deverá consultar o status do Lote (XML com NFS-e e Cancelamento no envelope), mas se não exisitir o cancelamento por algum motivo, somente consultando o Status poderá saber os motivos da rejeição ou erro de cancelamento.
As especificações dos nomes de argumentos (ex: cnpj:, conteudoLoteTxt:, usuario: e senha:) não são obrigatório em C#, inserido para deixar mais clara a sintaxe.
