Blog

NFS-e – Instruções de emissão de NFS-e

A API de NFS-e é utilizada principalmente para emissão e cancelamento (se suportado pela prefeitura) de notas ficais de serviços, outras rotinas podem estar disponíveis.

Passos para emissão da NFS-e

Resumidamente a emissão da NFS-e segue os seguintes passos:

  1. Envio do Lote de RPS ou RPS individual para a prefeitura;
  2. Consulta a situação do lote ou RPS;
  3. Obter os detalhes da(s) NFS-e gerada(s), ou do(s) erro(s) crítica(s) retornados pelo servidor da prefeitura.

IMPORTANTE: Cada prefeitura tem total autonomia para implementar seus sistemas de emissão de NFS-e, apesar de existirem “padrões” muitas tem suas particularidades. É importante está familiarizado com os detalhes de cada cidade.

Enviando a nota fiscal para o servidor

  1. O primeiro passo é obter um conector, podendo ser com ou sem certificado e/ou senha, cada cidade tem seu padrão;
  2. Após criar um conector definimos o nome e CNPJ padrão do emissor usando a função “NFS-e: Definir o nome e documento do prestador“, passe o CNPJ somente com números, se traços ou pontos;
  3. Em seguida criamos um novo lote (“NFS-e: Criar novo lote“), passando:
    1. Conector – (Variante) variável retornada pela função de criar conector;
    2. Número do Lote – (Inteiro ou Letras) Corresponde a um número sequencial de envios de lotes para o servidor. Provavelmente, se tinha um sistema anterior será necessário continuar a sequencia de envios, mas nesses casos (normalmente) uma mensagem de erro indica qual será o próximo.
  4. Dentro de um Lote pode existir um ou mais RPS (de acordo com as especificações da prefeitura, preferencialmente envie uma por lote), para se criar um RPS dentro do lote será utilizada a função “NFS-e: Novo RPS“, passando:
    1. O Lote (retorno da função anterior) e o número do RPS;
    2. Número do RPS – Número sequencial de geração de RPS, a faixa a ser utilizada deve ser consultada junto à prefeitura;
    3. Série: (Letras) – Verificar junto à prefeitura.
    4. Tipo (Inteiro): “1” para NFS-e
  5. Utilizar a função “NFS-e: RPS definir dados básicos” para definir alguns detalhes de tributação. É importante informar corretamente se é do SIMPLES ou não. Além de regimes diferenciados de tributação (se houver).
    • Parâmetro 2: Data e hora de emissão da NFS-e. Importante, observe se a hora do Webrun está correta para evitar problemas com o horário do servidor da prefeitura. Muitos validam a hora. O mesmo vale pra o horário de verão.
    • Parâmetro 4: Regime especial da tributação (Inteiro)  – Informar se houver, observar os valores aceitos no manual da prefeitura.
    • Parâmetro 7: Situação – Usar 1 para Normal ou 2 para Cancelado.
  6. OPCIONAL: Se a nota for emitida em substituição de outra NFS-e você deve utilizar a função “NFS-e: RPS definir RPS substituído” passando os dados da nota substituída.
  7. Adicione informações sobre o serviço prestado (“NFS-e: RPS Dados do serviço“)
    1. RPS
    2. Item da lista de serviços (Letras)
      Item da lista de serviços que corresponde ao serviço da nota fiscal;
    3. CNAE
    4. Código Tributário (Letras) –
      Identificação da lei que dá sentido às cobranças (obter junto à prefeitura);
      Dica: Arrisque deixar em branco, caso não saiba;
    5. Discriminação (Letras) – A maioria das prefeituras aceita apenas um tipo serviço por NFS-e, utilize este campo para descrever todos os serviços de um mesmo tipo;
    6. Código município (Letras) – Código do IBGE;
    7. Código do município de incidência (se for diferente).
  8. Adicione os totais da NFS-e “NFS-e: RPS definir valores totais“;
  9. Adicione as alíquotas dos impostos com a função “NFS-e: RPS Definir Alíquotas Impostos“;
  10. Adicione os dados do tomador do serviço usando as funções “NFS-e: RPS definir identificação do Tomador” e “NFS-e: RPS definir endereço do Tomador“.
  11. Utilize a função “NFS-e: Obter XML do Lote de RPS” para pegar o XML do lote qeu será enviado.
  12. Envie o lote através da função “NFS-e: Enviar Lote de RPS” e o retorno será o XML de resposta da prefeitura.

Processando a resposta do servidor

  1. Utilize a função “NFS-e: Processar resposta do servidor” passando o XML devolvido no retorno do envio de lote, esta função transformará o resultado num mapeamento (Variante) com os campos abaixo;
  2. Obtenha o elemento “QTD_NFS“, observe se já foram retornas NFS-e (se o serviço for sincrono).
  3. Neste caso pule diretamente para a parte de leitura dos dados da NFS-e;
  4. Obtenha o “PROTOCOLO” e faça a consulta da situação do lote alguns segundos após (30 segundos ou mais em média) usando a função “NFS-e: Consultar situação do Lote de RPS“;
  5. Se o lote ainda não foi processado você deve consultar novamente depois de mais alguns segundos (30 a 90 segundos).
  6. Algumas prefeituras já retorna os dados da NFS-e na consulta da situação, outras só retornam os dados com a chamada da função “NFS-e: Consultar Lote de RPS“, neste caso, após o lote ser processado chame a função “NFS-e: Consultar Lote de RPS” para obter detalhes da resposta.

Leitura dos dados da NFS-e

  1. Com o retorno do envio do lote (“NFS-e: Enviar Lote de RPS“), consulta situação (“NFS-e: Consultar situação do Lote de RPS“) ou consultar lote (“NFS-e: Consultar Lote de RPS“), vai depender de cada prefeitura, você receberá os dados do RPS convertido em NFS-e, que pode ser retornado de forma individual (NFS-e único), ou em lote (normalmente limitado a 50 no máximo).
  2. Faça um loop, ou pegue o primeiro item se for NFS-e único e obtenha os dados de cada NFS-e retornada, nem todas as prefeituras retornam todos os dados abaixo:
    • NFSx_NUMERO (Letras);
    • NFSx_DH_EMISSAO (Data);
    • NFSx_CODIGO_VERIFICACAO (Letras);
    • NFSx_XML (Letras);
    • NFSx_RPS_NUMERO (Letras);
    • NFSx_RPS_SERIE (Letras);
    • NFSx_RPS_TIPO (Letras);
    • NFSx_SITUACAO (Letras) – Situação do RPS;
    • NFSx_LINK (Letras) – Link para download do PDF ou HTML da nota fiscal.

Em caso de erro

Quado há algum erro, ou mensagem de alerta as mesmas são retoradas a seguinte estrutura:

  • MENSAGENS_QTD (Inteiro) – Número de mensagens retornar, de aviso e/ou erro.
  • MENSAGENS_ERRO_QTD (Inteiro) – Quantidade de mensagens de erro;
  • MSGx_CODIGO (Letras) – Código da mensagem;
  • MSGx_MENSAGEM (Letras) – Descrição da mensagem.
  • MSGx_CORRECAO (Letras) – Texto descritivo da solução retornado pela prefeitura.

Dicas

Resumo de sequencia de chamada das funções

Esta é a sequencia básica de chamadas das funções, algumas delas são opcionais, a depender do município, ou do tipo de documento a ser emitido.

  1. NFS-e: Criar conexão;
  2. NFS-e: Definir parâmetro do conector;
  3. NFS-e: Definir o nome e documento do prestador;
  4. NFS-e: RPS definir dados do SIMPLES;
  5. NFS-e: Criar novo lote;
  6. NFS-e: Novo RPS;
  7. NFS-e: RPS definir dados básicos;
  8. NFS-e: RPS definir RPS substituído;
  9. NFS-e: RPS Dados do serviço;
  10. NFS-e: RPS adicionar Item;
  11. NFS-e: RPS definir valores totais;
  12. NFS-e: RPS Definir Alíquotas Impostos;
  13. NFS-e: RPS definir dados do Tomador (Depreciada);
  14. NFS-e: RPS definir dados do Tomador 2 (Depreciada);
  15. NFS-e: RPS definir identificação do Tomador;
  16. NFS-e: RPS definir endereço do Tomador;
  17. NFS-e: Obter XML do Lote de RPS;
  18. NFS-e: Enviar Lote de RPS;
  19. NFS-e: Consultar situação do Lote de RPS;
  20. NFS-e: Consultar Lote de RPS;
  21. NFS-e: Processar resposta do servidor.

Trabalhando com várias cidades

Utilize tantas funções quanto forem necessárias para atender o maior número de cidades, deixe a API ignorar os dados desnecessários. Ou seja, não se ocupe em criar um fluxo para cada cidade, e sim um grande fluxo com todos os dados. Assim para adicionar novas cidades somente o código do IBGE será alterado.

Validando os XMLs

Algumas validações são específicas da prefeitura (regras de negócio internas), outras são especificadas num arquivo de validação do XML, você pode testar o XML gerado através da função “NFS-e – Obter XML do Lote” e testar junto com XSD fornecido pela prefeitura em sites como esse:

http://www.utilities-online.info/xsdvalidation/

Leave a comment