SAsafe2pay
NFS-e

Emitir NFS-e (v3)

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.

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

Request body

callbackUrlstring 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.

idempotencyKeystring 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.

operationType1 | 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

serviceDatestring 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.

isCulturalSponsorboolean

Prestador é incentivador cultural (benefício de lei de incentivo à cultura). Na dúvida, false.

specialTaxRegime0 | 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

isSimplesNacionalboolean

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.

meiLimitIndicatorinteger

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.

simplesNacionalLimitIndicatorinteger

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.

hasTaxIncentiveboolean

Prestador goza de incentivo fiscal municipal que reduz ou dispensa o ISS. Na dúvida, false.

isFixedIssboolean

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.

Example request

{
  "callbackUrl": "https://webhooks.exemplo.com.br/nfse/retorno",
  "idempotencyKey": "pedido-2026-08-000123",
  "rpsIdentifier": {
    "series": "1"
  },
  "operationType": 1,
  "serviceDate": "2026-08-31",
  "service": {
    "values": {
      "amount": 1000,
      "amountNet": 913.5,
      "amountPis": 6.5,
      "amountCofins": 30,
      "amountIss": 50,
      "amountIssWithheld": 50,
      "amountTaxBase": 1000,
      "rateIss": 5,
      "totalTaxRateSimplesNacional": 15.5,
      "ratePis": 0.65,
      "rateCofins": 3
    },
    "isIssWithheld": true,
    "withholdingAgent": 1,
    "issEnforceability": 1,
    "description": "Serviços de odontologia ocupacional prestados em agosto de 2026: avaliações periódicas dos colaboradores. Pedido interno 000123.",
    "serviceListItem": "04.12",
    "nationalTaxCode": "041201",
    "municipalTaxCode": "0412",
    "nbsCode": "123456789",
    "municipalityCode": "4314902",
    "incidenceMunicipalityCode": "4314902",
    "serviceAddress": {
      "zipCode": "90020000",
      "stateCode": "RS",
      "cityName": "Porto Alegre",
      "district": "Centro Histórico",
      "street": "Av. Borges de Medeiros",
      "number": "1501",
      "complement": "Sala 301"
    },
    "serviceRecipient": {
      "name": "Empresa Exemplo LTDA",
      "identity": "11222333000181",
      "email": "financeiro@exemplo.com.br",
      "address": {
        "number": "1501",
        "street": "Av. Borges de Medeiros",
        "district": "Centro Histórico",
        "zipCode": "90020000",
        "cityName": "Porto Alegre",
        "stateCode": "RS",
        "municipalityCode": "4314902",
        "countryName": "Brasil",
        "countryCode": "1058"
      }
    }
  }
}

Response

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.

traceIdstring

Identificador da requisição na Safe2Pay. Informe ao abrir chamado.

Changes

No recorded changes to this operation across all 1 revision of this API.