> ## Documentation Index > Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Emissão de NFS-e > Como emitir Notas Fiscais de Serviço Eletrônicas (NFS-e) pela API da Spedy. 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](/pages/guides/emissao-nfe) ou [Emissão de NFC-e](/pages/guides/emissao-nfce). 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](/pages/guides/sincrono-vs-assincrono) e [Ciclo de vida da nota](/pages/guides/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 ```bash cURL theme={null} 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. | ```bash cURL theme={null} 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](/pages/guides/configuracao-inicial), 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](/pages/guides/cancelamento-correcao-inutilizacao). ## Próximos passos * Estados possíveis da nota: [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota) * Configurar `serviceInvoice` (série, `issueType`, credenciais do provedor): [Configuração inicial](/pages/guides/configuracao-inicial) * Cancelamento: [Cancelamento, correção e inutilização](/pages/guides/cancelamento-correcao-inutilizacao)