Pular para o conteúdo principal
Ver como Markdown

Integração Nota Fiscal de Serviço - NFSe

Nesse documento você entenderá os primeiros passos para fazer a integração da Nota Fiscal de Serviço Eletrônica (NFSe).

Estrutura nova de gerenciamento de empresa

A partir da unificação da API de Contribuintes (2026.1), habilitar uma empresa para emitir NFS-e exige três recursos combinados: a própria Empresa (/v2/companies), o Certificado Digital (/v2/companies/{id}/certificates) e a Inscrição Municipal (/v2/companies/{id}/municipaltaxes). Veja a visão geral do Gerenciamento de Empresas para entender a estrutura completa.

A Nota Fiscal de Serviço Eletrônica é um documento digital fiscal utilizado para registrar a prestação de serviços de uma empresa, conforme as regras da prefeitura do município onde o serviço foi prestado.

Saiba mais: O que é nota fiscal eletrônica?

Ao final desse tutorial, você será capaz de:​

1. Cadastrar uma empresa
2. Fazer upload de um certificado digital
3. Criar uma inscrição municipal
4. Emitir uma nota fiscal de serviço

Próximos passos​

1. Consultar uma nota fiscal de serviço emitida
2. Consultar o XML de uma nota fiscal emitida
3. Consultar o PDF da nota fiscal emitida

Requisitos​

  • Empresa com CNPJ e CNAE de prestação de serviços
  • Certificado digital A1 (arquivo .pfx)
  • Integração via API REST, via Meio de Pagamento ou Planilha
  • Verificar se a prefeitura é atendida pela NFE.io (lista de prefeituras)

Tutorial​

A partir deste momento, faremos uma explicação de como realizar a integração da Nota Fiscal de Serviço com a API da NFE.io.

Veja mais sobre a Documentação da API de NFSe

Você pode realizar a importação da URL no Postman para ter todos os exemplos de requisição:

https://www.postman.com/nfe-io/workspace/nfe-io-public-api-demos/collection/29654924-09b8c724-7d9a-4735-93a3-518cc135989d?action=share&creator=29654924&active-environment=29463388-d0c59007-e68a-45c8-8fb8-16b53cb58c11

Tutorial de como importar a URL no Postman Clique aqui

Primeiros passos​

Antes de tudo, você precisará realizar um cadastro na nossa plataforma app.nfe.io e pegar a chave de autorização da API.

Devemos atentar para copiar a autorização referente a "Nota Fiscal"

Veja como pegar a chave de autorização: Autenticação

Lembre-se: A chave deve ser adicionada em cada requisição na aba "Headers" com o campo Authorization.

Ambiente: Testes ou Produção​

A NFE.io oferece dois ambientes para emissão de NFS-e. O ambiente é configurado na Inscrição Municipal (campo Environment), não na empresa — uma mesma empresa pode ter IMs de cidades diferentes, cada uma com seu próprio ambiente.

RecursoTestes (Development)Produção (Production)
Inscrição MunicipalObrigatória, com Environment: "Development"Obrigatória, com Environment: "Production"
Certificado Digital✅ Opcional⚠️ Obrigatório
Trânsito da notaServidores NFE.io que simulam a prefeituraPrefeitura real
Validade fiscalSem validade fiscalCom validade fiscal

Por que o certificado é opcional em testes na NFS-e?​

O ambiente de Testes da NFE.io para NFS-e roda em servidores que simulam o comportamento das prefeituras — a nota não trafega para a prefeitura real, então não há transmissão que exija assinatura digital ICP-Brasil. Isso permite testar a integração de ponta a ponta antes mesmo de adquirir um certificado.

Em Produção, a nota é enviada para a prefeitura real, que exige assinatura digital. Por isso o certificado vira obrigatório.

Diferente de NF-e e NFC-e

Para NF-e e NFC-e, o certificado digital é obrigatório mesmo em homologação, porque o ambiente de homologação da SEFAZ é o ambiente real do órgão (apenas marcado como teste) e exige assinatura digital. Veja a cadência para esses documentos em Primeiros Passos — NF-e.

1. Criar uma empresa​

Cadastra a empresa emissora na plataforma NFE.io. A empresa é o recurso central: o certificado e a inscrição municipal serão vinculados a ela nas próximas etapas.

Endpoint:
POST: https://api.nfse.io/v2/companies

Exemplo de JSON:

{
  "Company": {
    "Name": "RAZAO SOCIAL DA EMPRESA",
    "FederalTaxNumber": "12345678000199",
    "TaxRegime": "SimplesNacional",
    "Address": {
      "State": "SP",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo"
      },
      "District": "Centro",
      "Street": "Av. Exemplo",
      "Number": "100",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}

Será retornado o Id que representa o companyId, usado nas próximas requisições.

Referência completa: API de Empresas (v2).

2. Enviar certificado digital​

Pular se estiver testando

Esta etapa é opcional em ambiente de Testes (veja Ambiente: Testes ou Produção). Se você só quer validar a integração antes de ir para produção, pode seguir para a Etapa 3 sem enviar o certificado e voltar aqui depois.

Faz o upload do certificado A1 ICP-Brasil que será usado para assinar digitalmente as notas em Produção.

Endpoint:
POST: https://api.nfse.io/v2/companies/{companyId}/certificates

Você deve enviar o arquivo .pfx e a senha no corpo da requisição. Após o envio, o sistema informará a validade, status e dados do certificado.

Segurança: Os dados são criptografados e armazenados com segurança na plataforma da NFE.io.

Referência completa: API de Certificados (v2).

3. Criar uma inscrição municipal​

Vincula à empresa os dados de Inscrição Municipal que você obteve junto à prefeitura. Sem essa inscrição, a NFE.io não tem como emitir a NFS-e em nome da empresa.

Endpoint:
POST: https://api.nfse.io/v2/companies/{companyId}/municipaltaxes

Exemplo de JSON:

{
  "MunicipalTax": {
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP"
    },
    "TaxNumber": "876543",
    "Environment": "Production",
    "RpsSerialNumber": "IO"
  }
}

Campos obrigatórios:

  • City.Code — código IBGE de 7 dígitos
  • City.Name / City.State — nome e UF da cidade
  • Environment — Development para testes (servidor NFE.io simulando prefeitura, sem validade fiscal) ou Production para emitir notas válidas
  • RpsSerialNumber — série do RPS (ex.: IO, A1, 1)
Comece pelo ambiente de testes

Use Environment: "Development" enquanto valida a integração — não é preciso certificado digital nesse ambiente. Quando estiver pronto para emitir notas reais, atualize a IM para Environment: "Production" e faça o upload do certificado.

Se a sua prefeitura exige credenciais de acesso ao webservice (login/senha ou token), envie também LoginName, LoginPassword e/ou AuthIssueValue.

A resposta inclui o campo FiscalStatus, que indica se a NFE.io tem integração homologada com a prefeitura daquela cidade.

Referência completa: API de Inscrições Municipais (v2).

4. Emitir uma nota fiscal de serviço​

Endpoint:
POST: https://api.nfe.io/v1/companies/{companyId}/serviceinvoices

Emissão segue na API v1

A emissão de NFS-e ainda é servida pela API v1 (api.nfe.io/v1/...) e continuará funcionando normalmente durante a transição. O gerenciamento de empresa (etapas 1–3 acima) já é feito pela API v2 de Contribuintes (api.nfse.io/v2/...).

Campos principais:

  • Descrição do serviço (description)
  • Código do serviço (cityServiceCode)
  • Valor total do serviço (servicesAmount)
  • Dados do tomador (borrower: CNPJ ou CPF, nome, endereço)

Consulte a prefeitura para confirmar o código de serviço correto.

Cálculo automático de impostos

Por padrão, a NFE.io faz o cálculo automático dos impostos com base no cityServiceCode informado — você não precisa enviar issRate, issAmount ou outras retenções. Veja Cálculo Automático de Impostos para detalhes e para entender quando o cálculo manual se aplica.

Exemplo mínimo de payload:

{
  "borrower": {
    "type": "LegalEntity",
    "name": "Cliente Exemplo",
    "federalTaxNumber": "12345678000199",
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01001000",
      "street": "Rua Cliente",
      "number": "200",
      "district": "Centro",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Consultoria em tecnologia",
  "servicesAmount": 1000.00
}

O processamento é assíncrono. Após envio bem-sucedido, você receberá um id que representa o id único da nota atribuído pela NFE.io. Acompanhe o status por consulta de nota.

Próximos passos​

Consultar uma nota fiscal de serviço emitida
Consultar o XML de uma nota fiscal emitida
Consultar o PDF da nota fiscal emitida
Consultar o XML do evento de cancelamento (Ambiente Nacional)

XML do evento de cancelamento (Ambiente Nacional)

Para notas emitidas no Ambiente Nacional (ADN), o cancelamento gera o evento e110001, cujo XML pode ser baixado em GET /v1/companies/{company_id}/serviceinvoices/{id}/cancellation-xml. O endpoint está disponível apenas para notas canceladas do Ambiente Nacional — provedores de layout municipal/ABRASF não possuem evento de cancelamento próprio e retornam 404.

Informações adicionais​

Primeiros passos para integrar com nossa API de forma simples​

Integre seu sistema com a nossa API para começar a emitir notas fiscais de forma automatizada. Em caso de dúvida em algum conceito utilizado aqui, visite nossa Página de Conceitos e saiba tudo que você precisa para emitir Nota Fiscal de Serviço Eletrônica (NFS-e).

Recomendamos que você use nosso Ambiente de Testes para fazer a integração e só depois mudar para o Ambiente de Produção. Assim você pode tirar suas dúvidas e evitar equívocos quando mudar para produção.

Caso você não seja um desenvolvedor ou sua empresa não possua uma equipe de TI, nós disponibilizamos outras formas de automatizar suas emissões, clique aqui e veja as outras possibilidades disponíveis.

Integração a partir de um meio de pagamento​

A emissão automatizada de NFS-e depende da integração com o meio de pagamento usado por você. O meio de pagamento deve ter uma API por onde serão disponibilizadas as informações sobre os pagamentos que foram realizados.

Alguns meios de pagamento disponibilizam Webhooks para monitoramento dos pagamentos. Uma das opções de integrar com a nossa API é através desses Webhooks, que informarão sempre que um pagamento for realizado.

Outra opção é, de tempos em tempos, consultar a API do seu meio de pagamento para coletar os dados dos pagamentos que foram realizados.

Tendo os dados do pagamento, é só adicionar as informações pertinentes ao serviço prestado e enviar para nossa API, que emitirá a nota calculando os impostos automaticamente.

Observação: A maioria dos meios de pagamento não disponibilizam todas as informações necessárias para que a nota seja emitida. Ou seja, sua solução terá que agregar as informações faltantes com as informações cedidas pelo seu meio de pagamento.

Utilizando o Ambiente de Testes​

Uma das vantagens da nossa API é que você pode testá-la gratuitamente, assim você pode garantir que a nossa solução atenda às suas demandas.

Abaixo temos um passo a passo para utilização do nosso Ambiente de Testes:

Observação: Para testar a API de NFS-e você precisa apenas de uma Inscrição Municipal configurada com Environment: "Development". Certificado Digital e Inscrição Estadual não são necessários no ambiente de testes da NFS-e (Inscrição Estadual nunca é exigida para NFS-e). Veja a matriz completa em Ambiente: Testes ou Produção.

Módulos disponíveis​

  1. Escolha da linguagem: Oferecemos bibliotecas em:

Para outras linguagens, use nossa Referência da API.

Mudando para o ambiente de produção​

Após testar com sucesso, siga os passos abaixo:

  1. Verifique os dados ao criar sua empresa
  2. Certifique-se de que está credenciado na prefeitura para emissão de nota fiscal (como credenciar)
  3. Faça o upload do certificado digital
  4. Entre em contato com a equipe comercial para gerar sua fatura.
  5. Após o pagamento, vá até a aba "EMPRESAS", clique em "ALTERAR EMPRESA".
  6. Mude o ambiente de testes para produção na seção "Ambiente".

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.