API v3 para emissão de Nota Fiscal de Serviço Eletrônica (NFSe)

Egon Hilgenstieler

Vem aí a nova versão da nossa API para emissão de Nota Fiscal de Serviço Eletrônica.

Conteúdo

Infelizmente as prefeituras não adotam um padrão único para emissão de Nota Fiscal de Serviço Eletrônica (NFSe).

Apesar de existir uma recomendação da ABRASF, cada cidade é livre para decidir o padrão que achar melhor, tornando difícil o trabalho de quem precisa fazer a integração de seu cidade com múltiplas cidades.

Para contornar este problema, estamos desenvolvendo a versão 3 de nossa API para emissão de NFSe, que tentará ser o mais homogênea possível, atendendo ao maior número de cidades com um mínimo de mudanças. Abaixo descrevemos o formato de comunicação desta API. A API irá utilizar o padrão REST de comunicação via HTTP, as 3 chamadas possíveis da API são exemplificadas abaixo:

  • POST /nfse?ref=REFERENCIA&token=TOKEN – Submete uma nova NFSe para autorização
  • GET /nfse/REFERENCIA?token=TOKEN – Recupera informações sobre a NFSe
  • DELETE /nfse/REFERENCIA?token=TOKEN  – Cancela uma NFSe

Onde REFERENCIA é a referência do objeto do sistema original (por exemplo, o identificador do banco de dados) e TOKEN é o token de acesso fornecido na contratação do sistema. O token é utilizado para identificar a empresa prestadora do serviço.

Submissão de NFSe

A submissão de uma NFSe irá conter no seu corpo um arquivo YAML descrevendo os dados da nota. Todos os campos são descritos abaixo e as diferenças entre as cidades comentadas. Os campos denotados com (*) são obrigatórios.

  • data_emissao (*): Data/hora de emissão da NFSe. Alguns municípios como São Paulo não utilizam hora e ela será descartada caso seja fornecida.
  • status: Status da NFS-e, informar 1 – Normal ou 2 – Cancelado. (Valor padrão: 1).
  • natureza_operacao (*): Natureza da operação. Informar um dos códigos abaixo. Campo ignorado para o município de São Paulo. 1 – Tributação no município 2 – Tributação fora do município 3 – Isenção 4 – Imune 5 – Exigibilidade suspensa por decisão judicial 6 – Exigibilidade suspensa por procedimento administrativo (Valor padrão: 1)
  • regime_especial_tributacao: Informar o código de identificação do regime especial de tributação conforme abaixo. Campo ignorado para o município de São Paulo. 1 – Microempresa municipal 2 – Estimativa 3 – Sociedade de profissionais 4 – Cooperativa 5 – MEI – Simples Nacional 6 – ME EPP – Simples Nacional
  • optante_simples_nacional(*): Informar verdadeiro ou falso se a empresa for optante pelo Simples Nacional. Campo ignorado pelo município de São Paulo.
  • incentivador_cultural: Informe verdadeiro ou falso. Valor padrão: falso. Campo ignorado para o município de São Paulo.
  • tributacao_rps: Usado apenas pelo município de São Paulo. Informe o tipo de tributação: T – Operação normal (tributação conforme documento emitido); I – Operação isenta ou não tributável, executadas no Município de São Paulo; F – Operação isenta ou não tributável pelo Município de São Paulo, executada em outro Município; J – ISS Suspenso por Decisão Judicial (neste caso, informar no campo Discriminação dos Serviços, o número do processo judicial na 1a. instância). (Valor padrão “T”)
  • servico:
    • valor_servicos(*): Valor dos serviços.
    • valor_deducoes: Valor das deduções.
    • valor_pis: Valor do PIS.
    • valor_cofins: Valor do COFINS.
    • valor_inss: Valor do INSS.
    • valor_ir: Valor do IS.
    • valor_csll: Valor do CSLL
    • iss_retido(*): Informar verdadeiro ou falso se o ISS foi retido.
    • valor_iss: Valor do ISS. Campo ignorado pelo município de São Paulo.
    • valor_iss_retido: Valor do ISS Retido. Campo ignorado pelo município de São Paulo.
    • outras_retencoes: Valor de outras retenções.  Campo ignorado pelo município de São Paulo.
    • base_calculo: Base de cálculo do ISS, valor padrão igual ao valor_servicos. Campo ignorado pelo município de São Paulo.
    • aliquota: Aliquota do ISS.
    • desconto_incondicionado: Valor do desconto incondicionado. Campo ignorado pelo município de São Paulo.
    • desconto_condicionado: Valor do desconto incondicionado. Campo ignorado pelo município de São Paulo.
    • item_lista_servico(*): informar o código da lista de serviços, de acordo com a Lei Complementar 116/2003. Utilize outra tabela para o município de São Paulo.
    • codigo_cnae: Informar o código CNAE. Campo ignorado pelo município de São Paulo.
    • codigo_tributario_municipio: Informar o código tributário de acordo com a tabela de cada município (não há um padrão). Campo ignorado pelo município de São Paulo.
    • discriminacao(*): Discriminação dos serviços.
    • codigo_municipio(*): Informar o código IBGE do município de prestação do serviço.
  • prestador:
    • cnpj(*): CNPJ do prestador de serviços.
    • codigo_municipio(*): Código IBGE do município do prestador (consulte lista aqui)
    • inscricao_municipal: Inscrição municipal do prestador de serviços.
  • tomador:
    • cpf(*): CPF do tomador, se aplicável.
    • cnpj(*): CNPJ do tomador, se aplicável.
    • inscricao_municipal: Inscrição municipal do tomador
    • razao_social: Razão social ou nome do tomador
    • endereco:
      • logradouro: Nome do logradouro.
      • tipo_logradouro: Tipo do logradouro. Usado apenas para o município de São Paulo. Valor padrão: os 3 primeiros caracteres do logradouro.
      • numero: Número do endereço.
      • complemento: Complemento do endereço.
      • bairro: Bairro
      • codigo_municipio: código IBGE do município.
      • uf: UF do endereço.
      • cep: CEP do endereço.
    • telefone: Telefone do tomador. Campo ignorado para o município de São Paulo.
    • email: Email do tomador.
  • intermediario (esta seção é ignorada pelo município de São Paulo)
    • razao_social: Razão social do intermediário do serviço.
    • cpf: CPF  do intermediário do serviço, se aplicável.
    • cnpj: CNPJ  do intermediário do serviço, se aplicável.
    • inscricao_municipal: Inscrição municipal  do intermediário do serviço, se aplicável.
  • codigo_obra: Código da obra quando construção civil. Este campo é ignorado pelo município de São Paulo.
  • art: Código ART quando construção civil. Este campo é ignorado pelo município de São Paulo.

Exemplo de um arquivo YAML:

data_emissao: 2013-05-31T12:00:00-03:00
incentivador_cultural: false
natureza_operacao: "1"
optante_simples_nacional: false
prestador: 
 cnpj: 06901848000133
 inscricao_municipal: 080204613599
 codigo_municipio: 4106902
servico: 
 aliquota: 0.05
 base_calculo: 200.0
 discriminacao: "Servico de hospedagem de sites"
 iss_retido: "2"
 item_lista_servico: "801"
 valor_iss: 10.0
 valor_liquido: 200.0
 valor_servicos: 200.0
status: "1"
tomador: 
 cpf: 03055054912
 endereco: 
   bairro: Centro
   cep: "80000000"
   codigo_municipio: "4106902"
   logradouro: "Rua Emiliano Perneta"
   numero: "845"
   uf: PR
 razao_social: "Egon Hilgenstieler"

Consulte o suporte técnico para possíveis exceções no seu município.

Consulta

Após a emissão, a consulta da situação do processamento poderá ser feita em um segundo momento para obter as informações da NFSe gerada ou dos erros de processamento. O retorno é também em formato YAML. Parâmetros:

  • token: O token secreto de sua empresa
  • ref: Número da referência

Exemplo de chamada e retorno:

GET /nfse/<REFERECIA>?token=<seu_token>
uri: https://nfe.prefeitura.sp.gov.br/contribuinte/notaprint.aspx?inscricao=112312&nf=14&verificacao=P2UJ4QGT
codigo_verificacao: P2UJ4QGT
data_emissao: 2012-08-12 03:00:00 Z
numero: "14"
status: autorizado

Retorno: HTTP status 200 (Ok) ou HTTP status 404 (Not Found) se não encontrada NFSe associada a referência Campos de retorno:

  • uri: Endereço disponibilizado pela prefeitura para visualização da NFSe
  • codigo_verificacao: Código de verificação da NFSe
  • data_emissao: Data de emissão
  • numero: Número da NFSe
  • status: “autorizado” se a NFSe foi emitida com sucesso ou “erro_autorizacao” caso contrário
  • erros: Array de mensagens de erro caso a nota fiscal não tenha sido emitida com sucesso.

Cancelamento

Uma nota pode ser cancelada após autorizada. O processo de cancelamento também é assíncrono e requer a justificativa do cancelamento como parâmetro. O cancelamento pode ser rejeitado dependendo das regras de prazo de cancelamento de cada prefeitura.

Parâmetros:

  • token: O token secreto de sua empresa
  • ref: Número da referência
  • justificativa: Justificativa do cancelamento (valor padrão: “Dados incorretos”)

Exemplo de chamada e retorno:

DELETE /nfse/<REFERECIA>?token=<seu_token>&justificativa=Erro+nos+dados+do+tomador

Retorno: HTTP status 200 (Ok) ou HTTP status 404 (Not Found) se não encontrada NFSe associada a referência

Após solicitado o cancelamento, você deverá consultar o status da nota novamente usando a operação de consulta, que poderá retornar o status “autorizado”, se o cancelamento ainda não foi autorizado, “erro_cancelamento” se houve um erro no cancelamento (a nota continuará autorizada) ou “cancelado” se o cancelamento foi efetivado com sucesso. Exemplo:

uri: https://nfe.prefeitura.sp.gov.br/contribuinte/notaprint.aspx?inscricao=112312&nf=14&verificacao=P2UJ4QGT
codigo_verificacao: P2UJ4QGT
data_emissao: 2012-08-12 03:00:00 Z
numero: "14"
status: cancelado

Quer integrar seu sistema para emissão de NF-e? Clique aqui, acesse nossa documentação e saiba tudo o que você para fazer a integração do seu sistema com a nossa API.

Egon Hilgenstieler

Egon Hilgenstieler

CTO e cofundador do Focus NFe, desenvolvedor, professor de yoga e praticante de meditação. Enquanto não está programando, procura a resposta para a vida, para o universo e para tudo mais.

Inscreva-se em nossa newsletter​

Receba nossos conteúdos exclusivos em primeira mão.

Explore outros conteúdos:

calculadora sob uma mesa com papéis com anotações.
Nota Fiscal
Welker Zigante

O que é DIFAL do ICMS? Entenda como funciona e quem paga!

O termo Diferencial de Alíquota (DIFAL) se refere ao recolhimento do ICMS (Imposto sobre Circulação de Mercadorias e Serviços) e busca promover equidade tributária entre os estados brasileiros.

Empreendedores como proprietários de e-commerces que realizam compras fora do estado e vendem para consumidores finais, precisam considerar as variações nas alíquotas do ICMS entre os estados.

Logo, dada a complexidade dessa legislação, compreender o que é e como funciona o DIFAL pode ser desafiador, especialmente devido às diferentes alíquotas e leis em cada um dos 26 estados e no Distrito Federal relacionadas ao ICMS e aos produtos e serviços tributados.

Acompanhe o nosso post de hoje e compreenda melhor esse processo.

Leia mais »
/nota-tecnica-2016-003
Nota Fiscal
Junior Muniz

Nota Técnica 2016.003: confira a nova tabela de NCM!

A Nota Técnica 2016.003, publicada em dezembro de 2016, é um documento fundamental para a emissão da Nota Fiscal Eletrônica (NF-e). Ela define a tabela de Nomenclatura Comum do Mercosul (NCM) e as Unidades de Medidas Tributáveis (Utrib) a serem utilizadas na NF-e.

Desde que foi lançada, a Nota Técnica 2016.003 passou por diversas alterações, a fim de atualizar a tabela de NCM e Utrib conforme as mudanças da legislação e as necessidades do mercado.

A seguir, abordamos em detalhes todas essas mudanças nas diferentes versões da Nota Técnica e quais códigos foram incluídos e excluídos do documento.

Leia mais »