---
title: "Emitir NFS-e (v3)"
method: POST
path: "/v3/nfse"
tags: ["NFS-e"]
---

# Emitir NFS-e (v3)

`POST /v3/nfse`

## Request

- Base URL: `https://api.safe2pay.com.br`
- URL: `https://api.safe2pay.com.br/v3/nfse`
- Auth: API key in header `X-API-KEY`

Emite uma NFS-e no padrão Nacional a partir dos dados enviados na requisição, sem vínculo com transação de pagamento.

O prestador é sempre o titular da chave `X-API-KEY` que autenticou a chamada: não existe campo para emitir em nome de terceiro, e uma subconta de marketplace emite com a chave dela própria.

A emissão é assíncrona. O `202 Accepted` significa **pedido aceito e enfileirado**, não nota emitida: não há número de NFS-e, protocolo nem URLs nessa resposta. O desfecho chega exclusivamente no `callbackUrl` informado no pedido, documentado em Callbacks.

Não há sandbox: NFS-e é documento fiscal real e toda nota emitida existe de verdade na prefeitura. O cancelamento é feito hoje pelo painel Safe2Pay.

**Idempotência.** `idempotencyKey` é obrigatória e a mesma chave nunca gera uma segunda nota. Em `400`, `403`, `412`, `422`, `500` ou `502`, repita com a **mesma** chave. Trocar a chave para tentar de novo significa duas notas fiscais reais na prefeitura.

**Convenções.** Nomes em camelCase; decimais como número JSON com ponto e duas casas (`1000.00`); datas em `YYYY-MM-DD`; booleanos aceitam somente os literais `true` e `false` (`0`, `1`, `2`, string ou `null` geram `400`).

**Pré-requisitos**, todos configurados no painel Safe2Pay e verificados nesta ordem, com `412` no primeiro que faltar: serviço de NFS-e habilitado, configuração fiscal, certificado digital A1 e inscrição municipal.

O guia completo, com fluxo ponta a ponta, emissão para optantes do Simples Nacional, catálogo de erros, retentativa do callback, boas práticas e glossário, está em [Emitir NFS-e (v3): guia de integração](https://developers.safe2pay.com.br/reference/nfse-v3-guia).

## Request body

- object
  - `callbackUrl` string, uri, required: Webhook que recebe o desfecho da nota. É o único canal de retorno: o 202 não traz a nota. Precisa ser URI absoluta válida e não vazia. A API aceita `http://`, mas use HTTPS: o callback carrega dados da nota e não tem assinatura.
  - `idempotencyKey` string, required: Chave única do pedido, escolhida por você. Reenviar a mesma chave nunca gera segunda nota. Escopo: o prestador. Use um valor estável derivado do seu próprio pedido, nunca timestamp ou GUID gerado no envio.
  - `rpsIdentifier` object, required: Identificação do RPS que dá origem à NFS-e. Se o objeto for omitido, o erro reportado é `rpsIdentifier.series`.
    - `series` string, required: Série do RPS, definida pelo prestador junto à prefeitura. Não pode ser vazia. O número do RPS é atribuído pela Safe2Pay a cada emissão.
  - `operationType` 1 | 2 | 3 | 4 | 5 | 6, required: Natureza da operação do prestador perante o ISS. Deve ser coerente com `service.issEnforceability`. Zero ou ausente é recusado com 422. 1 = Tributação no Município: o ISS é devido ao município do prestador (caso mais comum) 2 = Tributação fora do Município: o ISS é devido a outro município 3 = Isenção: a lei municipal dispensa o ISS para este serviço 4 = Imune: a Constituição impede a cobrança (templos, partidos, entidades assistenciais) 5 = Exigibilidade Suspensa por Decisão Judicial 6 = Exigibilidade Suspensa por Processo Administrativo
  - `serviceDate` string, date, required: Data de competência do serviço (fato gerador), em `YYYY-MM-DD`. Não pode estar no futuro, avaliado por data no fuso de Brasília. A data de emissão do RPS é o instante do processamento, não este campo.
  - `isCulturalSponsor` boolean: Prestador é incentivador cultural (benefício de lei de incentivo à cultura). Na dúvida, `false`.
  - `specialTaxRegime` 0 | 1 | 2 | 3 | 4 | 5 | 6: Regime especial de tributação do prestador. 0 = Nenhum: prestador comum (padrão quando omitido) 1 = Ato Cooperado: serviço prestado por cooperativa a seus cooperados 2 = Estimativa: o município fixa um ISS estimado por período 3 = Microempresa Municipal: regime simplificado próprio da prefeitura 4 = Notário ou Registrador: cartórios 5 = Profissional Autônomo: pessoa física com ISS fixo anual 6 = Sociedade de Profissionais: sociedade uniprofissional, ISS por profissional
  - `isSimplesNacional` boolean: Optante pelo Simples Nacional. O tratamento fiscal do Simples é determinado pelo **regime tributário cadastrado na configuração fiscal do prestador**; este campo informa a condição no RPS. Para optantes ME/EPP, a alíquota de ISS não é enviada à prefeitura: informe a alíquota efetiva do Simples em `service.values.rateSimplesNacional`.
  - `meiLimitIndicator` integer: Indicador de limite do MEI. Opcional e sem valor padrão: quando omitido, não é enviado. O valor informado é repassado como veio na transmissão da nota; não validamos faixa nem coerência.
  - `simplesNacionalLimitIndicator` integer: Indicador de limite do Simples Nacional. Opcional e sem valor padrão: quando omitido, não é enviado. O valor informado é repassado como veio na transmissão da nota; não validamos faixa nem coerência.
  - `hasTaxIncentive` boolean: Prestador goza de incentivo fiscal municipal que reduz ou dispensa o ISS. Na dúvida, `false`.
  - `isFixedIss` boolean: Prestador sujeito a ISS fixo: valor periódico (autônomo, sociedade de profissionais), não percentual sobre a nota. Somente `true` e `false`: `0` ou `1` geram 400.
  - `service` object, required: Dados do serviço: valores, códigos tributários, local da prestação e tomador. Se ausente, a validação dos campos filhos é interrompida, mas os erros já acumulados na raiz permanecem na resposta.
    - `values` object, required: Valores e alíquotas da nota. A API valida apenas `amount > 0`; a coerência aritmética entre os demais campos é do integrador.
      - `amount` number, double, required: Valor bruto dos serviços. Deve ser maior que zero. É o único campo de valores que a API valida.
      - `amountNet` number, double: Valor líquido da NFS-e (o que sobra ao prestador após retenções). Repassado **sem recálculo**: informe o líquido correto.
      - `amountDeductions` number, double: Deduções legais da base de cálculo (ex.: materiais na construção civil). Entra no recálculo da base.
      - `amountPis` number, double: Valor do PIS. Se `0`, a Safe2Pay calcula `(amount - amountDeductions) × ratePis / 100`; se maior que zero, prevalece o informado.
      - `amountCofins` number, double: Valor da COFINS. Se `0`, a Safe2Pay calcula `(amount - amountDeductions) × rateCofins / 100`; se maior que zero, prevalece o informado.
      - `amountInss` number, double: INSS retido. Repassado sem cálculo.
      - `amountIr` number, double: IR retido. Repassado sem cálculo.
      - `amountCsll` number, double: CSLL retida. Repassado sem cálculo.
      - `amountIss` number, double: Valor do ISS da nota. O tributo municipal é calculado como `amountIss` quando maior que zero, senão `base × rateIss / 100`. Ignorado quando o prestador é optante do Simples Nacional na modalidade ME/EPP.
      - `amountIssWithheld` number, double: ISS retido na fonte, quando `service.isIssWithheld` é `true`. Repassado sem cálculo.
      - `amountOtherWithholdings` number, double: Outras retenções. Repassado sem cálculo.
      - `amountTaxBase` number, double: Base de cálculo do ISS. **Aceito e sobrescrito**: a Safe2Pay grava `amount - amountDeductions` arredondado a duas casas. Informe coerente com essa fórmula ou omita.
      - `rateIss` number, double: Alíquota do ISS em percentual (`2.00` = 2%). Usada quando `amountIss` é `0`. Ignorado quando o prestador é optante do Simples Nacional na modalidade ME/EPP.
      - `rateSimplesNacional` number, double: Alíquota efetiva do Simples Nacional, usada no cálculo. Repassada sem cálculo. Não confunda com `totalTaxRateSimplesNacional`, que é o percentual total aproximado dos tributos para a Lei da Transparência.
      - `totalTaxRateSimplesNacional` number, double: Percentual total aproximado dos tributos pela alíquota do Simples Nacional, para a Lei da Transparência (art. 1º da Lei 12.741/2012). Não é a alíquota usada no cálculo da nota: essa é `rateSimplesNacional`. Opcional e sem valor padrão: quando omitido, não é enviado. Não validamos faixa nem coerência.
      - `ratePis` number, double: Alíquota do PIS em percentual. Usada quando `amountPis` é `0`.
      - `rateCofins` number, double: Alíquota da COFINS em percentual. Usada quando `amountCofins` é `0`.
    - `isIssWithheld` boolean: ISS retido na fonte pelo tomador ou intermediário. Quando `true`, informe `values.amountIssWithheld` e `withholdingAgent` e desconte de `values.amountNet`. Quando `false`, `amountIssWithheld` deve ser `0.00`.
    - `withholdingAgent` 0 | 1 | 2: Responsável pela retenção do ISS. 0 ou ausente = Não informado. Use quando `isIssWithheld` é `false` 1 = Tomador: o cliente retém o ISS e repassa à prefeitura 2 = Intermediário: uma terceira parte da operação faz a retenção
    - `issEnforceability` 1 | 2 | 3 | 4 | 5 | 6 | 7, required: Exigibilidade do ISS nesta nota. Deve ser coerente com `operationType` (ex.: `operationType` 3 combina com `issEnforceability` 3). Zero ou ausente é recusado com 422. 1 = Exigível: o ISS é devido normalmente 2 = Não incidência: o fato não é serviço tributável pelo ISS 3 = Isenção: serviço tributável, dispensado por lei municipal 4 = Exportação: serviço exportado, sem ISS (LC 116, art. 2º) 5 = Imunidade: vedação constitucional 6 = Exigibilidade Suspensa por Decisão Judicial 7 = Exigibilidade Suspensa por Processo Administrativo
    - `description` string: Discriminação do serviço: o texto impresso na nota.
    - `serviceListItem` string: Item da lista de serviços da LC 116/2003. Não validado pela API: definido pela contabilidade do prestador.
    - `nationalTaxCode` string: Código de tributação nacional da NFS-e Nacional, 6 dígitos. Vai como `cTribNac` na DPS. Não validado pela API.
    - `municipalTaxCode` string: Código de tributação do município do prestador (tabela da prefeitura). Não validado pela API.
    - `nbsCode` string: Código NBS, 9 dígitos. Não validado pela API.
    - `municipalityCode` string: Código IBGE (7 dígitos) do município onde o serviço foi prestado. É **este** campo que vai à prefeitura como município de prestação; `serviceAddress.municipalityCode` é ignorado. Não validado pela API.
    - `incidenceMunicipalityCode` string: Código IBGE (7 dígitos) do município de incidência do ISS. Não validado pela API.
    - `serviceAddress` object: Endereço do local da prestação. Opcional e não validado; se ausente, todos os campos de local de prestação vão vazios.
      - `zipCode` string: CEP, 8 dígitos sem hífen. A API não normaliza.
      - `stateCode` string: UF, 2 letras.
      - `cityName` string: Cidade do local da prestação.
      - `district` string: Bairro.
      - `street` string: Logradouro.
      - `number` string: Número.
      - `complement` string: Complemento.
      - `countryName` string: **Aceito e ignorado nesta versão**: não é usado na emissão.
      - `countryCode` string: **Aceito e ignorado nesta versão**: não é usado na emissão.
      - `municipalityCode` string: **Aceito e ignorado nesta versão**: o município de prestação considerado é `service.municipalityCode`.
    - `serviceRecipient` object, required: Tomador do serviço, quem recebe a nota. Se ausente, a validação dos campos filhos é interrompida, mas os erros já acumulados permanecem na resposta.
      - `name` string, required: Nome (CPF) ou razão social (CNPJ) do tomador. Não pode ser vazio.
      - `identity` string, required: CPF ou CNPJ do tomador. O tipo é deduzido do tamanho: 11 dígitos = CPF, 14 = CNPJ; qualquer outro tamanho é 422. **Envie somente dígitos**: um documento com máscara é recusado ou segue pontuado para a prefeitura.
      - `email` string, email, required: E-mail do tomador: é para este endereço que a nota é enviada. A API exige apenas a presença de um `@` com texto antes e depois; a SEFIN recusa e-mail inválido com E0247. Valide o formato completo do seu lado.
      - `address` object, required: Endereço do tomador. A API exige apenas `number`, mas a SEFIN avalia o endereço nacional inteiro: CEP, logradouro, bairro, cidade, UF e código IBGE precisam existir e ser coerentes entre si. O E0240 (CEP que não pertence ao município) é a rejeição mais frequente em produção e chega pelo callback, depois do 202.
        - `number` string, required: Número do endereço. Não pode ser vazio. Não use para "S/N, fundos, bloco B".
        - `street` string: Logradouro. Não validado pela API; exigido pela SEFIN (E0240).
        - `district` string: Bairro. Não validado pela API; exigido pela SEFIN (E0240).
        - `zipCode` string: CEP, 8 dígitos sem hífen. Não validado pela API; a SEFIN recusa CEP inexistente ou que não pertença ao `municipalityCode` (E0240).
        - `cityName` string: Nome do município do tomador. A API não exige, mas a validação fiscal recusa vazio. Informe sempre, mesmo com `municipalityCode`.
        - `stateCode` string: UF do tomador. Necessário junto com `cityName` quando `municipalityCode` é omitido. Informe sempre.
        - `municipalityCode` string: Código IBGE do município, 7 dígitos. Com 7 dígitos sempre prevalece sobre `cityName` + `stateCode`. Com qualquer outro tamanho é ignorado sem erro próprio e a API resolve por nome exato; se não achar exatamente um município, 422. Recomenda-se sempre informar com 7 dígitos.
        - `countryName` string: Nome do país. Não validado.
        - `countryCode` string: Código BACEN do país; `1058` = Brasil. Se informado, 2 a 4 caracteres.
        - `complement` string: **Aceito e ignorado nesta versão**: não é usado na emissão.

## Response `202`

Pedido de emissão aceito e enfileirado. A nota ainda não existe: não há número de NFS-e, protocolo nem URLs aqui. O desfecho chega no callbackUrl.

- object
  - `data` object
    - `id` string, uuid: Identificador do pedido de emissão, gerado a cada POST aceito. É a chave de correlação com o campo `Identificador` do callback. Guarde o par `id` + `idempotencyKey`: o callback não traz a chave.
    - `status` string: Situação do pedido no instante do aceite. A única string possível no 202 é `Aguardando processamento`.
    - `idempotencyKey` string: Eco da chave enviada. É o único dado do pedido que volta: a resposta não ecoa nome, documento, e-mail nem endereço do tomador.
  - `traceId` string: Identificador da requisição na Safe2Pay. Informe ao abrir chamado.

## Other responses

- `400`: JSON inválido, corpo vazio ou valor que o conversor não consegue converter para o tipo do campo. Nenhuma regra de negócio é avaliada. Corrija o JSON e repita com a mesma idempotencyKey.
- `403`: Falha de credencial. A API não usa 401 e não envia WWW-Authenticate. Um 403 nunca enfileira nada: corrija a chave e repita com a mesma idempotencyKey.
- `412`: A conta não pode emitir. Verificado antes do payload, um único erro por vez. Regularize no painel Safe2Pay e repita com a mesma idempotencyKey.
- `422`: Payload aceito, mas inválido. A validação acumula todos os erros de campo de uma vez; documento e município do tomador vêm isolados, depois; a recusa na validação fiscal vem com name nfse.issuer. Corrija tudo o que está listado e repita com a mesma idempotencyKey.
- `500`: Exceção não prevista após a autenticação. Aguarde e repita com a mesma idempotencyKey; guarde o traceId para abrir chamado.
- `502`: O serviço de emissão de NFS-e da Safe2Pay não respondeu a tempo. Não é erro do payload: repita em alguns minutos sem alterar payload nem chave.

---

[API](https://skmtc.dev/safe2pay/apis/nfs-e.md) - [All operations](https://skmtc.dev/safe2pay/apis/nfs-e/llms.txt) - [OpenAPI document](https://skmtc.dev/safe2pay/apis/nfs-e/revisions/a17d1b7f1d6d?raw)