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 prefeitura define seu próprio layout, regras de validação e, às vezes, autenticação. Os campos e o comportamento descritos aqui variam por provedor municipal — trate esta página como um guia geral, não como a especificação exata do seu município.

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. Na prática, cada provedor municipal costuma exigir também cnaeCode, federalServiceCode (código da lista de serviço da LC 116/03) ou cityServiceCode — confirme com GET /v1/service-invoices/cities e com as regras do seu município antes de emitir em produção.

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.

DPS, RPS e a variação por prefeitura

Diferente de NF-e/NFC-e, que seguem um layout único definido pela SEFAZ nacional, a NFS-e historicamente foi implementada município a município, cada um com seu próprio provedor de emissão (Ginfes, Webiss, Betha, ISSNet, entre outros). Dois conceitos aparecem na maioria dos provedores:

RPS (Recibo Provisório de Serviços) — número provisório emitido antes da nota definitiva, usado por provedores tradicionais como comprovante interino 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 mais novo, que várias prefeituras vêm adotando para substituir seus sistemas próprios).

Na API da Spedy, os campos rpsNumber e rpsSeries representam tanto o RPS quanto o DPS — o que eles significam depende do provedor do município. O batchNumber identifica o lote, quando o provedor trabalha com envio em lote. Qual formato seu município usa depende do provedor configurado para a empresa.

Descobrindo se seu município é suportado

Antes de emitir, confirme que a cidade da sua empresa (ou da prestação do serviço) está integrada:

GET /v1/service-invoices/cities

Filtre por code (código IBGE do município), state ou filterText (busca por nome). Cada cidade retornada traz:

Campo	Conteúdo
`code`, `name`, `state`	Identificação do município.
`provider`	O provedor municipal usado para emitir NFS-e nessa cidade.
`nationalServiceInvoiceRegimes`	Regimes do Ambiente Nacional suportados para o município, quando aplicável.

cURL

curl -G https://sandbox-api.spedy.com.br/v1/service-invoices/cities \
  -H "X-Api-Key: sua-chave-de-api" \
  --data-urlencode "filterText=São Paulo"

Se o município não aparecer na resposta, ele ainda não está integrado — a Spedy não consegue emitir NFS-e para ele.

Ambiente Nacional e autenticação do provedor

O campo issueType (nas configurações da empresa, bloco serviceInvoice) define a forma de emissão da NFS-e:

Valor	Significado
`annfs`	Ambiente Nacional da NFS-e — o padrão federal, usado pelos municípios que já migraram para ele.
`website`	Emissão pelo website/sistema próprio do provedor municipal.
`alt`	Ambiente alternativo do provedor, quando ele oferece mais de um canal de emissão.

Muitos provedores municipais exigem, além do certificado digital da empresa, uma autenticação própria — login e senha (ou token) cadastrados junto à prefeitura ou ao provedor. Isso é configurado, não enviado por nota:

Configuração (`serviceInvoice`)	Uso
`userName` / `password`	Credencial de acesso ao provedor. Dependendo do provedor, `password` pode representar a senha propriamente dita, um token de autenticação ou uma chave de API.
`authNumber`	Número de autenticação do provedor — corresponde à chave privada no Sigep ou ao número da AEDF no Softplan. Obrigatório apenas para esses provedores específicos.

Nem todo município exige userName/password/authNumber — alguns autenticam só pelo certificado digital da empresa. Consulte o retorno de GET /v1/service-invoices/cities e a documentação do provedor da sua cidade para saber o que é necessário.

Tributação de serviço (ISS)

O bloco total (ServiceInvoiceTotalDto) 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 (objeto CitySimpleDto — 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

Estados possíveis da nota: Ciclo de vida da nota
Configurar serviceInvoice (série, issueType, credenciais do provedor): Configuração inicial
Cancelamento: Cancelamento, correção e inutilização

Fundamentos

Emissão

Operações fiscais

Emissão de NFS-e

Exemplo de criação

DPS, RPS e a variação por prefeitura

Descobrindo se seu município é suportado

Ambiente Nacional e autenticação do provedor

Tributação de serviço (ISS)

Operações relacionadas

Próximos passos

​Exemplo de criação

​DPS, RPS e a variação por prefeitura

​Descobrindo se seu município é suportado

​Ambiente Nacional e autenticação do provedor

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

​Operações relacionadas

​Próximos passos

Exemplo de criação

DPS, RPS e a variação por prefeitura

Descobrindo se seu município é suportado

Ambiente Nacional e autenticação do provedor

Tributação de serviço (ISS)

Operações relacionadas

Próximos passos