Emitir NFS-e (v3)

post

https://api.safe2pay.com.br/v3/nfse

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, catálogo de erros, retentativa do callback, boas práticas e glossário, está em Emitir NFS-e (v3): guia de integração.

Body Params

callbackUrl

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

length ≤ 64

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.

operationType

int32

enum

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

Allowed:

serviceDate

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

Defaults to false

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

specialTaxRegime

int32

enum

Defaults to 0

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

Allowed:

isSimplesNacional

boolean

Defaults to false

Prestador optante pelo Simples Nacional. Quando true, preencha service.values.rateSimplesNacional; quando false, o ISS é calculado por rateIss.

hasTaxIncentive

boolean

Defaults to false

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

isFixedIss

boolean

Defaults to false

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.

Responses

Callback

202Pedido 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.

400JSON 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.

403Falha 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.

412A conta não pode emitir. Verificado antes do payload, um único erro por vez. Regularize no painel Safe2Pay e repita com a mesma idempotencyKey.

422Payload 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.

500Exceção não prevista após a autenticação. Aguarde e repita com a mesma idempotencyKey; guarde o traceId para abrir chamado.

502O 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.