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

Enviando a nota fiscal para o servidor

  1. O primeiro passo é obter um conector;
  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. Provavelemente, 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. 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 municipio (Letras) – Código do IBGE;
    7. Código do municipio de incidência (se for diferente).
  7. Adicione os totais da NFS-e

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);
  5. Se o lote ainda não foi processado você deve consultar novamente depois de alguns segundos (30 a 90 segundos).
  6. Faça um loop 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 seguite 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

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