Emitir NFS-e

Cria uma nova NFS-e. A operação é assíncrona por padrão — devolve 202 Accepted e dispara um webhook quando o status final estiver disponível.

POST/v1/nfse🔒 Bearer Token

Idempotência

Reenviar a mesma idIntegracao no mesmo tenant não cria nota duplicada — devolve a existente (com seu status atual). Isso garante segurança em retries do seu ERP.

Request body

prestadorCnpjstringObrigatório

CNPJ do prestador emissor. Deve estar cadastrado como Empresa no tenant da API key.

Apenas dígitos (sem máscara XX.XXX.XXX/XXXX-XX)
Validação: algoritmo de DV ICP-Brasil
A empresa precisa ter certificado A1 ativo vinculado

Formato: 14 dígitosExemplo: 82653726000198

idIntegracaostringRecomendado

Identificador externo do seu ERP. Fortemente recomendado.

Habilita:

Idempotência — reenvio devolve a nota existente em vez de criar duplicada
Reconciliação no seu ERP sem guardar o id UUID da Notare
Filtro rápido no portal e em webhooks

Restrições:

Sem espaços nas pontas
Único por tenant (não precisa ser único globalmente)
Persiste no webhook payload

Tamanho: 1 – 64Exemplo: OS-30046339

servicoobjectObrigatório

Bloco do serviço prestado.

municipioPrestacaostringObrigatório

Código IBGE do município de prestação. A Notare resolve automaticamente o roteamento — você não escolhe webservice nem padrão.

Formato: IBGE 7 dígitosExemplo: 4104808

itemListaServicostringObrigatório

Item da Lista de Serviços da LC 116/2003. Aceita formato com pontos (1.07.01) ou só números (10701) — a Notare normaliza.

Exemplo: 10701

cnaestringRecomendado

CNAE do prestador. Recomendado pois é exigido por diversos municípios.

Formato: 7 dígitos

codigoTributacaoMunicipalstring

Código local de tributação do município. Notare deriva automaticamente quando possível; informe se o município exigir explicitamente (varia por cidade).

descricaostringObrigatório

Descrição livre do serviço prestado. Aparece no DANFSe e nas consultas. Pode incluir referências de OS, projeto, contrato.

Tamanho: 1 – 2000

valorServicosCentavosintegerObrigatório

Valor bruto dos serviços em centavos. R$ 100,00 → 10000. Nunca use float.

Exemplo: 66064 (R$ 660,64)

valorDeducoesCentavosinteger

Deduções permitidas (LC 116 itens 7.05, 1.05 etc.) em centavos. Subtraído da base de cálculo do ISS quando a situação tributária permitir.

Default: 0

aliquotaIssBpintegerObrigatório

Alíquota do ISS em basis points. 3% = 300. Faixa típica municipal: 200 (2%) a 500 (5%).

Tamanho: 0 – 10000Exemplo: 300 (3,00%)

issRetidoPeloTomadorboolean

true quando o tomador (geralmente órgão público) é responsável por reter e recolher o ISS. Implica situação tributária específica nos provedores.

Default: false

exigibilidadeIssenum

Hipótese de exigibilidade do ISS. Use exportacao para serviços a tomador no exterior — fora do campo de incidência por regra geral.

Default: exigivelValores: exigivel, nao_incidencia, isencao, exportacao, imunidade, suspensa_judicial, suspensa_administrativa

naturezaOperacaoenum

Natureza da operação. Define onde o ISS é devido. Default inferido de municipioPrestacao vs prestadorCnpj.municipioSede.

Valores: tributacao_no_municipio, tributacao_fora_municipio, isencao, imune, exigibilidade_suspensa_decisao_judicial, exigibilidade_suspensa_procedimento_administrativo

informacoesComplementaresstring

Texto livre adicional impresso no DANFSe. Comum: dados de contrato, nota fiscal correlata, mensagem ao tomador.

Tamanho: 0 – 2000

reformaTributariaobject

Bloco IBS/CBS/IS — ver Reforma Tributária pra detalhamento completo de campos e CST.

tomadorobjectObrigatório

Bloco do tomador (cliente).

cpfCnpjstringRecomendado

CPF (PF) ou CNPJ (PJ). Pode ser omitido apenas em "tomador não identificado" (varejo). Sem máscara.

Formato: 11 ou 14 dígitos

nifEstrangeirostring

NIF/Tax ID quando tomador é estrangeiro. Use no lugar do cpfCnpj em exportação de serviços.

Tamanho: 0 – 40

razaoSocialstringObrigatório

Nome completo (PF) ou razão social (PJ).

Tamanho: 0 – 200

inscricaoMunicipalstring

IM do tomador. Necessária se ele estiver sujeito a retenção de ISS no município.

Tamanho: 0 – 50

emailstring

Email do tomador. Alguns municípios enviam o PDF/XML pelo email cadastrado.

Formato: RFC 5322Tamanho: 0 – 200

enderecoobjectObrigatório

Endereço completo do tomador (obrigatório quando PJ).

logradourostringObrigatório

Rua, Av, Rod, etc.

Tamanho: 0 – 200

numerostringObrigatório

Use "S/N" quando sem número.

Tamanho: 0 – 20

complementostring

Sala, andar, bloco.

Tamanho: 0 – 100

bairrostringObrigatório

Tamanho: 0 – 100

municipioIbgestringObrigatório

Código IBGE do município do tomador.

Formato: IBGE 7 dígitos

ufstringObrigatório

Formato: UF 2 letras

cepstringObrigatório

Formato: 8 dígitos sem máscara

codigoPaisstring

Código país BACEN. 1058 = Brasil.

Default: 1058Tamanho: 0 – 4

rpsobject

Identificação opcional do RPS. Recomendado deixar a Notare alocar — evita conflitos de sequência.

numerostring

Força um número específico. Use só se você gerencia a sequência externa.

seriestring

Série do RPS.

Default: da config da empresa

tipoenum

Default: rpsValores: rps, nota_conjugada_misto, cupom

dataEmissaostring

Data/hora de emissão do RPS.

Formato: ISO 8601Default: agora

competenciastring

Mês/ano de competência fiscal.

Formato: YYYY-MMDefault: mês atual

opcoesobject

Modificadores de processamento.

modoSincronoboolean

true faz a API aguardar a resposta final (até 30s). Default assíncrono devolve 202 e dispara webhook quando estiver pronto.

Default: false

webhookUrlstring

Sobrescreve a URL de webhook do tenant apenas para esta emissão.

Formato: URL HTTPS

prioridadeenum

Reservado para planos Scale/Enterprise. Default normal é suficiente em 99% dos casos.

Default: normalValores: normal, alta

consumidorFinalboolean

Marca o tomador como consumidor final. Afeta cálculo de impostos em alguns cenários.

Default: false

Exemplo de request

POST /v1/nfse
{
  "prestadorCnpj": "82653726000198",
  "idIntegracao": "OS-30046339",
  "servico": {
    "municipioPrestacao": "4104808",
    "itemListaServico": "10701",
    "cnae": "6202300",
    "descricao": "Consultoria em desenvolvimento de software",
    "valorServicosCentavos": 66064,
    "aliquotaIssBp": 300,
    "exigibilidadeIss": "exigivel"
  },
  "tomador": {
    "cpfCnpj": "77856995003218",
    "razaoSocial": "Cliente Exemplo LTDA",
    "endereco": {
      "logradouro": "Av. Brasil",
      "numero": "1000",
      "bairro": "Centro",
      "municipioIbge": "4104808",
      "uf": "PR",
      "cep": "85801000"
    },
    "email": "financeiro@cliente.com"
  }
}

Response

202 Accepted
{
  "id": "5fcb9e1d-28e1-4e45-bde9-8e957c835b27",
  "status": "processando",
  "numero": null,
  "chaveAcesso": null,
  "numeroRps": "201",
  "serieRps": "8",
  "meta": {
    "trilho": "municipal",
    "municipio": { "ibge": "4104808", "nome": "Cascavel" },
    "tempoProcessamento": "120ms",
    "tentativas": 1
  },
  "urls": { "pdf": null, "xml": null },
  "scoreConfianca": 95,
  "avisos": [],
  "erros": []
}

Campos do response

idstring

Identificador único da NFS-e no Notare.

Formato: UUID v4

statusenum

Estado atual. Veja a tabela de transições abaixo.

Valores: processando, autorizada, rejeitada, cancelada, substituida, falha_temporaria, falha_definitiva

numerostring

Número fiscal atribuído pela prefeitura. null enquanto não autorizada.

chaveAcessostring

Chave de acesso da NFS-e (formato varia por município/padrão). null enquanto não autorizada.

numeroRpsstring

Número do RPS gerado.

serieRpsstring

Série do RPS usada.

urlsobject

pdfstring

URL pra baixar o DANFSe (PDF). Disponível quando autorizada.

xmlstring

URL pra baixar o XML autorizado. Disponível quando autorizada.

scoreConfiancainteger

Score heurístico pré-emissão. ≥ 90 = alta confiança · 70–89 = atenção · < 70 = revise antes de produção.

Formato: 0-100

avisosarray

Lista de avisos não bloqueantes (campos ausentes recomendados, alíquotas atípicas).

errosarray

Em rejeitada: lista de erros estruturados com campo, codigo, mensagem.

Estados possíveis

Estado	Significado	Transições saída
`processando`	Em fila ou aguardando resposta	→ `autorizada` · `rejeitada` · `falha_temporaria`
`autorizada`	NFS-e gerada com sucesso	→ `cancelada` · `substituida`
`rejeitada`	Validação falhou (`erros[]` lista os campos)	terminal
`cancelada`	Cancelamento confirmado	terminal
`substituida`	Substituída por outra NFS-e	terminal
`falha_temporaria`	Erro transitório — retentável	→ `processando` · `falha_definitiva`
`falha_definitiva`	Esgotou retries automáticos	terminal

Idempotência​

Request body​

Exemplo de request​

Response​

Campos do response​

Estados possíveis​

Idempotência

Request body

Exemplo de request

Response

Campos do response

Estados possíveis