Emissão de NFS-e

A NFS-e (Nota Fiscal de Serviço Eletrônica) é o documento fiscal para prestação de serviços, tributada por ISS. Use POST /v1/service-invoices. Se a operação envolve produtos, veja Emissão de NF-e ou Emissão de NFC-e.

A emissão de NFS-e também é assíncrona — a resposta 2xx confirma apenas que a nota foi aceita. Veja Síncrono vs assíncrono e Ciclo de vida da nota.

NFS-e é o modelo mais heterogêneo dos três: cada município emite por um provedor próprio, com seu layout, seus códigos fiscais e, às vezes, sua autenticação. Trate esta página como um guia geral e consulte o que o seu município exige antes de emitir.

Exemplo de criação

cURL

curl -X POST https://sandbox-api.spedy.com.br/v1/service-invoices \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "servico-45678",
    "effectiveDate": "2026-08-03T10:00:00Z",
    "description": "Consultoria em tecnologia da informação",
    "federalServiceCode": "1.06",
    "receiver": {
      "name": "Cliente Exemplo Ltda",
      "federalTaxNumber": "00000000000191",
      "email": "financeiro@clienteexemplo.com.br",
      "address": {
        "street": "Rua Exemplo",
        "number": "100",
        "district": "Centro",
        "postalCode": "01001000",
        "city": { "name": "São Paulo", "state": "SP" }
      }
    },
    "total": {
      "invoiceAmount": 1000.0,
      "issRate": 5
    }
  }'

description (discriminação dos serviços) e total são os únicos campos formalmente obrigatórios pelo schema. Quais códigos fiscais o provedor do município envia à prefeitura (federalServiceCode, cityServiceCode, cnaeCode, nbsCode) varia — a consulta abaixo informa quais são e devolve um corpo de exemplo já no formato aceito pelo município.

Os valores de tributação deste exemplo (base, alíquota e valor do ISS) têm fins didáticos e não substituem a orientação de um contador. A alíquota de ISS e o enquadramento do serviço dependem do município e da natureza da operação — valide com o seu contador ou responsável fiscal antes de emitir em produção.

O que o seu município exige

Antes de emitir, consulte as Configurações de emissão por município da cidade da empresa emissora, informando o código IBGE do município:

cURL

curl https://api.spedy.com.br/v1/service-invoices/cities/3550308/settings

Resposta (resumida)

{
  "code": 3550308,
  "name": "São Paulo",
  "state": "SP",
  "providers": [
    {
      "code": "paulistana",
      "name": "Paulistana",
      "taxRegimes": ["simplesNacional", "simplesNacionalExcessoSublimite", "regimeNormal"],
      "issueType": "normal",
      "options": {
        "rps": true,
        "series": true,
        "batchNumber": true,
        "federalServiceCode": true,
        "cityServiceCode": true,
        "cnaeCode": false,
        "nbsCode": true,
        "authentication": "certificate",
        "requiresDigitalCertificate": true,
        "supportsTaxReform": true,
        "supportsIntermediary": true
      },
      "example": {
        "payload": {
          "description": "Servico de exemplo para teste de integracao",
          "cityServiceCode": "05762",
          "nbsCode": "1.2204.90.00",
          "taxationType": "taxationInMunicipality",
          "rpsNumber": 1,
          "rpsSeries": "1",
          "receiver": { "...": "..." },
          "total": { "invoiceAmount": 100.0, "issRate": 2.0 }
        }
      }
    },
    {
      "code": "nacional",
      "name": "Emissor Nacional",
      "taxRegimes": ["simplesNacionalMEI"],
      "issueType": "annfs",
      "options": { "...": "..." },
      "example": { "...": "..." }
    }
  ]
}

A resposta traz todos os provedores que valem no município. Municípios que adotaram o Emissor Nacional para parte dos regimes tributários têm mais de um, e alguns provedores oferecem ainda um canal alternativo. O que ler em cada provedor:

Campo	O que diz
`taxRegimes`	Regimes tributários que emitem por esse provedor. Escolha o provedor cujo `taxRegimes` contém o `taxRegime` da empresa.
`issueType`	Método de emissão a configurar na empresa, em `serviceInvoice.issueType` (veja abaixo).
`options.federalServiceCode`, `cityServiceCode`, `cnaeCode`, `nbsCode`, `nationalTaxationCode`	Quais códigos fiscais o provedor envia à prefeitura. Um código com `false` é aceito na requisição, mas não tem efeito nesse município.
`options.rps`, `series`, `batchNumber`, `requiresNumberInSequence`	Como o provedor numera as notas (RPS/DPS, série, lote).
`options.authentication`, `requiresDigitalCertificate`	Como o provedor autentica: `certificate`, `userName` ou `token`.
`options.supportsTaxReform`, `supportsIntermediary`	Se o provedor aceita os campos de IBS/CBS (`ibsCbs`) e o `intermediary` do serviço.
`example.payload`	Corpo de requisição com os códigos fiscais de uma nota autorizada pelo mesmo provedor (`example` vem nulo quando ainda não há exemplo publicado). Use-o como ponto de partida, trocando pelos dados do seu serviço.

Se o município não estiver integrado, a consulta responde 404 — a Spedy não consegue emitir NFS-e para ele. Para navegar pelos municípios e ver essas mesmas informações sem código, use a página Municípios integrados; para listar ou buscar municípios pela API (por nome, UF ou código IBGE), use Cidades integradas.

RPS, DPS e numeração

Dois conceitos aparecem na maioria dos provedores:

RPS (Recibo Provisório de Serviços) — número provisório emitido antes da nota definitiva, usado pelos provedores municipais tradicionais enquanto o lote é processado.
DPS (Declaração de Prestação de Serviços) — o documento equivalente no Ambiente Nacional da NFS-e, o padrão que várias prefeituras vêm adotando no lugar de seus sistemas próprios.

Na API da Spedy, rpsNumber e rpsSeries representam tanto o RPS quanto a DPS; batchNumber identifica o lote, quando o provedor envia em lote. Se omitidos, a Spedy usa o próximo número, a série e o próximo lote configurados na empresa (serviceInvoice.nextNumber, series e nextBatchNumber). Quais desses o seu provedor usa está em options.rps, options.series e options.batchNumber; nos provedores que não usam RPS/DPS (options.rps falso), o número enviado à prefeitura é o da própria nota, em number.

Método de emissão e autenticação do provedor

O campo issueType (nas configurações da empresa, bloco serviceInvoice) define para qual sistema a nota é enviada. Configure o valor que a consulta por município indica no issueType do provedor escolhido:

Valor	Significado
`normal`	Web service do provedor do município — o padrão.
`annfs`	API do Ambiente Nacional da NFS-e, usada pelos municípios que migraram para o Ambiente Nacional.
`alt`	Canal alternativo do provedor municipal, quando ele oferece mais de um.

O valor vale para todas as notas de serviço da empresa — não é informado nota a nota. Além do certificado digital, alguns provedores exigem uma credencial própria, cadastrada junto à prefeitura. options.authentication diz qual é o caso, e a credencial é configurada na empresa, não enviada por nota:

`options.authentication`	O que configurar em `serviceInvoice`
`certificate`	Nada além do certificado digital A1 da empresa.
`userName`	`userName` e `password` — usuário e senha cadastrados na prefeitura.
`token`	`password` com o token de acesso (ou chave de API) fornecido pela prefeitura.

O campo authNumber é obrigatório apenas em dois provedores: corresponde à chave privada no Sigep e ao número da AEDF no Softplan.

Tributação de serviço (ISS)

O bloco total carrega a base de cálculo e as alíquotas do serviço, incluindo issBaseTax, issRate, issAmount e as flags de retenção (issWithheld, além de irWithheld, pisWithheld, cofinsWithheld, inssWithheld, csllWithheld). O campo taxationType define a natureza da tributação:

`taxationType`	Significado
`taxationInMunicipality`	Tributado no município / operação tributável.
`taxationOutsideMunicipality`	Tributado fora do município.
`exemption`	Isento.
`immune`	Imune.
`suspendedByCourt` / `suspendedByAdministrativeProcedure`	Suspenso por decisão judicial ou administrativa.
`exportation`	Exportação de serviço.
`nonIncidence`	Não incidência.

O local de apuração do ISS (taxLocation) define de quem é a competência: município da empresa, do cliente ou da prestação do serviço (companyMunicipality, customerMunicipality, serviceProvisionMunicipality) — a regra correta depende da natureza do serviço (Lei Complementar 116/03) e varia por município. O taxLocation não deve ser confundido com o campo location: este é a cidade onde o serviço foi prestado (code IBGE, name, state), informado quando a prestação ocorre em município diferente do da empresa. taxLocation escolhe a competência; location diz qual é a cidade da prestação.

Operações relacionadas

Operação	Endpoint
Listar notas	`GET /v1/service-invoices`
Obter a nota (por ID)	`GET /v1/service-invoices/{id}`
Baixar PDF (DANFSE)	`GET /v1/service-invoices/{id}/pdf`
Baixar XML	`GET /v1/service-invoices/{id}/xml`
Consultar diretamente no provedor municipal (reconciliar)	`POST /v1/service-invoices/{id}/check-status`
Reenviar e-mail ao tomador	`POST /v1/service-invoices/{id}/resend-email`

NFS-e não tem endpoint de carta de correção nem de inutilização — esses dois recursos existem apenas para product-invoices na API da Spedy hoje. Para corrigir uma NFS-e já emitida, a via depende do provedor municipal: normalmente cancelamento (quando o prazo permite) seguido de nova emissão. Veja Cancelamento, correção e inutilização.

Próximos passos

Provedores, configurações e exemplo de requisição por cidade: Municípios integrados
Configurar serviceInvoice (série, issueType, credenciais do provedor): Configuração inicial
Estados possíveis da nota: Ciclo de vida da nota
Cancelamento: Cancelamento, correção e inutilização

Fundamentos

Emissão

Operações fiscais

NF-e recebidas

NFS-e tomadas

Emissão de NFS-e

Exemplo de criação

O que o seu município exige

RPS, DPS e numeração

Método de emissão e autenticação do provedor

Tributação de serviço (ISS)

Operações relacionadas

Próximos passos

​Exemplo de criação

​O que o seu município exige

​RPS, DPS e numeração

​Método de emissão e autenticação do provedor

​Tributação de serviço (ISS)

​Operações relacionadas

​Próximos passos

Exemplo de criação

O que o seu município exige

RPS, DPS e numeração

Método de emissão e autenticação do provedor

Tributação de serviço (ISS)

Operações relacionadas

Próximos passos