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).

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. 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://api.postman.com/collections/29654924-09b8c724-7d9a-4735-93a3-518cc135989d?access_key=PMAT-01JXMNQ71BY8PVESY1PD1KM1PW

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.

---

1. Criar uma empresa

Endpoint:
POST: https://api.nfe.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, que deve ser utilizado nas próximas requisições.

---

2. Enviar certificado digital

Endpoint:
POST: https://api.nfe.io/v2/companies/{companyId}/certificate

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.

---

3. Emitir uma nota fiscal de serviço

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

Campos principais:

• Descrição do serviço
• Código do serviço (cityServiceCode)
• Alíquota de ISS (issRate)
• Dados do tomador (CNPJ ou CPF, endereço, nome)

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

Exemplo mínimo de payload:

{
  "description": "Consultoria em tecnologia",
  "cityServiceCode": "101",
  "issRate": 5.0,
  "borrower": {
    "federalTaxNumber": "12345678909",
    "name": "Cliente Exemplo",
    "email": "cliente@exemplo.com",
    "address": {
      "street": "Rua Cliente",
      "number": "200",
      "district": "Centro",
      "city": {
        "code": "3550308",
        "name": "São Paulo",
        "country": "BRA"
      },
      "state": "SP",
      "postalCode": "01001000"
    }
  }
}

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

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 nossa API você não precisa ter um Certificado Digital, Inscrição Municipal e nem mesmo uma Inscrição Estadual.

Módulos disponíveis

1. Escolha da linguagem: Oferecemos bibliotecas em:
   • Node.js
   • PHP
   • Ruby

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".