--- title: "Primeiros Passos para integração de nota fiscal de serviço - NFE.io | Docs" description: "Veja os Primeiros Passos para integrar seu sistema com nossa API e começar a emitir notas fiscais eletrônicas (NFS-e), de forma automatizada." source_url: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos last_updated: 2026-05-26 --- # 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)**. :::info[Estrutura nova de gerenciamento de empresa] A partir da [unificação da API de Contribuintes (2026.1)](/docs/release-notes/2026-1-unificacao-api-contribuintes), 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](/docs/documentacao/gerenciamento-empresas/visao-geral) 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?](/docs/documentacao/conceitos/notas-fiscais) ### Ao final desse tutorial, você será capaz de: [1. Cadastrar uma empresa](#1-criar-uma-empresa)\ [2. Fazer upload de um certificado digital](#2-enviar-certificado-digital)\ [3. Criar uma inscrição municipal](#3-criar-uma-inscrição-municipal)\ [4. Emitir uma nota fiscal de serviço](#4-emitir-uma-nota-fiscal-de-serviço) ### Próximos passos [1. Consultar uma nota fiscal de serviço emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-id-get)\ [2. Consultar o XML de uma nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-xml)\ [3. Consultar o PDF da nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-pdf) ## 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](/docs/prefeituras-integradas/)) ## 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](https://nfe.io/). **Veja mais sobre a** [Documentação da API de NFSe](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1) Você pode realizar a importação da URL no Postman para ter todos os exemplos de requisição: ```json 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](/docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman) - - - ## Primeiros passos Antes de tudo, você precisará realizar um cadastro na nossa plataforma [app.nfe.io](https://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](/docs/documentacao/nossa-plataforma/chaves-de-autenticacao) > **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. | Recurso | Testes (`Development`) | Produção (`Production`) | |---|---|---| | **Inscrição Municipal** | Obrigatória, com `Environment: "Development"` | Obrigatória, com `Environment: "Production"` | | **Certificado Digital** | ✅ **Opcional** | ⚠️ **Obrigatório** | | **Trânsito da nota** | Servidores NFE.io que simulam a prefeitura | Prefeitura real | | **Validade fiscal** | Sem validade fiscal | Com 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. :::info[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](/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos). ::: - - - ## 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:** ```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)](/docs/documentacao/gerenciamento-empresas/api-empresas). - - - ## 2. Enviar certificado digital :::tip Pular se estiver testando Esta etapa é **opcional em ambiente de Testes** (veja [Ambiente: Testes ou Produção](#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)](/docs/documentacao/gerenciamento-empresas/api-certificados). - - - ## 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:** ```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`) :::tip 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)](/docs/documentacao/gerenciamento-empresas/api-inscricoes-municipais). - - - ## 4. Emitir uma nota fiscal de serviço **Endpoint:**\ `POST: https://api.nfe.io/v1/companies/{companyId}/serviceinvoices` :::info[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. :::tip 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](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/calculo-automatico-impostos) para detalhes e para entender quando o cálculo manual se aplica. ::: **Exemplo mínimo de payload:** ```json { "borrower": { "type": "LegalEntity", "name": "Cliente Exemplo", "federalTaxNumber": "12345678000199", "email": "cliente@exemplo.com", "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](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-id-get)\ [Consultar o XML de uma nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-xml)\ [Consultar o PDF da nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-pdf) ## 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](/docs/documentacao/nota-fiscal-servico-eletronica/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](#utilizando-o-ambiente-de-testes)** para fazer a integração e só depois mudar para o **[Ambiente de Produção](#mudando-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](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos#como-emitir-nota-fiscal-de-serviço-nfs-e) 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](/docs/documentacao/webhooks/conceitos), 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](#ambiente-testes-ou-produção). ### Módulos disponíveis 1. **Escolha da linguagem**: Oferecemos bibliotecas em: * [Node.js](/docs/desenvolvedores/bibliotecas/nodejs) * [PHP](/docs/desenvolvedores/bibliotecas/php) * [Ruby](/docs/desenvolvedores/bibliotecas/ruby) Para outras linguagens, use nossa [Referência da API](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1). ### Mudando para o ambiente de produção Após testar com sucesso, siga os passos abaixo: 1. Verifique os dados ao [criar sua empresa](/docs/documentacao/nossa-plataforma/criar-empresa) 2. Certifique-se de que está credenciado na prefeitura para emissão de nota fiscal ([como credenciar](/docs/documentacao/nota-fiscal-servico-eletronica/documentacao-nota-fiscal-servico-eletronica-credenciamento-prefeitura)) 3. Faça o [upload do certificado digital](/docs/documentacao/nossa-plataforma/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"**.