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:

Nota Fiscal Complementar: o que é e como fazer essa NF-e?
Nota Fiscal
João Vallim

Nota fiscal complementar: o que é e em quais casos usar

A Nota Fiscal Complementar é um documento utilizado para auxiliar a uma Nota Fiscal emitida que possui erros ou necessita de ajustes de informações.

No entanto, seja para corrigir valores, impostos ou produtos, a NF Complementar, por vezes, causa dúvidas quanto ao seu preenchimento e sua utilidade.

Acompanhe o artigo de hoje e saiba mais sobre como emitir esse documento, como utilizá-lo e outras informações relevantes para evitar confusões.

Leia mais »
CST
Nota Fiscal
Welker Zigante

CST: saiba o que é o Código de Situação Tributária e qual usar!

O termo CST (Código de Situação Tributária) gera muitas dúvidas sobre como aplicá-lo aos negócios. Devido à variedade de siglas, termos e códigos ligados à tributação empresarial, não é difícil que confusões aconteçam.

Por isso, entender o que é o CST e saber qual código usar em cada situação é fundamental para garantir uma gestão otimizada da emissão de notas e outros documentos fiscais.

Acompanhe o nosso artigo de hoje e esclareça suas dúvidas.
Boa leitura!

Leia mais »
nota-tecnica-2015-002
Nota Fiscal
Ludmila Ferreira

Nota Técnica 2015.002: Web Service de distribuição de DF-e

A Nota Técnica 2015.002, publicada em 11 de fevereiro de 2015, trata de alterações relacionadas ao âmbito do Sistema Público de Escrituração Digital (SPED) e da Nota Fiscal Eletrônica (NF-e).

Na prática, foram alteradas regras e erros foram corrigidos no lançamento das diversas versões da Nota Técnica, como abordaremos a seguir.

Leia mais »