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

Integração NFe - DocumentaçãoInfelizmente 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.