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

Formato compatível com PlugNotas

O JSON de emissão espelha o layout do PlugNotas (layout RTC007/1.01). Se você está migrando do PlugNotas, os nomes de campos, a estrutura aninhada e as unidades são as mesmas — na prática você reaproveita o mesmo body. As três convenções centrais:

• servico é um ARRAY — uma nota pode ter vários itens, cada um com sua própria tributação (iss, retencao, apuracaoPropria, reforma, valor).
• Dinheiro em REAIS DECIMAIS (number, no máximo 2 casas) — 660.64, não centavos inteiros. Não existe mais sufixo *Centavos.
• Alíquotas em PERCENTUAL (number) — 3 = 3%, 0.65 = 0,65%. Não existe mais basis points.

Cálculo automático de impostos

Este é o ponto que mais simplifica a integração: você manda só a alíquota de cada imposto e a Notare calcula o valor. O campo valor de cada imposto (ISS, PIS, COFINS, CSLL, IBS, CBS…) é opcional.

• Quando você omite valor, a Notare calcula: valor = baseCalculo × aliquota / 100, com arredondamento fiscal (2 casas, half-up). A base padrão de cada imposto é o valor do serviço (ajustado por deduções/descontos quando aplicável).
• Quando você informa valor e aliquota e os dois divergem, a Notare usa o valor calculado e devolve um aviso em avisos[] apontando o campo. Não bloqueia a emissão.
• Você pode sobrescrever a base de um imposto específico com baseCalculo (em reais) dentro do bloco do imposto.

Na prática: informe só a aliquota e deixe a Notare calcular. Isso evita divergências de arredondamento entre o seu ERP e o XML fiscal — e é o que torna a migração de quem vem do PlugNotas praticamente um copiar-e-colar.

Request body

prestadorobjectObrigatório

Prestador (emitente fiscal). Deve estar cadastrado como Empresa no tenant da API key.

cpfCnpjstringObrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos) do prestador.

• 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: 11 ou 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

servicoarrayObrigatório

Array de itens de serviço. Pelo menos um item. Cada item carrega sua própria tributação (iss, retencao, apuracaoPropria, reforma, valor). Os campos abaixo descrevem um item do array.

codigostringObrigatório

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

Formato: item LC 116Exemplo: 10701

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

codigoTributacaostring

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). (antes: codigoTributacaoMunicipal)

Tamanho: 0 – 20

discriminacaostringObrigatório

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

Tamanho: 1 – 2000

cnaestringRecomendado

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

Formato: 7 dígitos

municipioIncidenciastring

Município competente para o ISS, quando diferente do de prestação.

Formato: IBGE 7 dígitos

codigoServicoNacionalstring

DPS — código de serviço nacional (cTribNac). Sistema Nacional.

Formato: 6 dígitos

codigoNbsstring

DPS — código NBS (Nomenclatura Brasileira de Serviços).

Formato: 9 dígitos

valorobjectObrigatório

Valores deste item, em reais decimais (number, máx. 2 casas).

serviconumberObrigatório

Valor bruto do serviço em reais. R$ 660,64 → 660.64. (antes: valorServicosCentavos: 66064)

Exemplo: 660.64

baseCalculonumber

Base de cálculo do ISS em reais. Default = servico − deducoes − descontoIncondicionado.

descontoIncondicionadonumber

Desconto incondicionado em reais. Reduz a base de cálculo.

descontoCondicionadonumber

Desconto condicionado em reais.

recebidonumber

Valor efetivamente recebido em reais, quando difere do serviço.

deducoesnumber | object

Deduções permitidas (LC 116 itens 7.05, 1.05 etc.) em reais. Aceita um number simples ou um objeto detalhado ({ valor, percentual, documentos[] }). (antes: valorDeducoesCentavos)

issobjectObrigatório

Tributação do ISS deste item. Informe a aliquota; o valor é opcional (calculado).

aliquotanumberObrigatório

Alíquota do ISS em percentual. 3% → 3. Faixa típica municipal: 2 a 5. (antes: aliquotaIssBp: 300)

Tamanho: 0 – 100Exemplo: 3 (= 3%)

valornumber

Valor do ISS em reais. Opcional — quando omitido, a Notare calcula baseCalculo × aliquota / 100.

tipoTributacaointeger

Situação tributária do ISS (numérico, alinha com o XML): 1=tributável no município, 2=fora, 3=isenção, 4=imune, 5=exig. suspensa judicial, 6=exig. suspensa adm., 7=tributável fora do município.

Tamanho: 1 – 9

exigibilidadeinteger

Exigibilidade do ISS (numérico): 1=exigível, 2=não incidência, etc.

Tamanho: 1 – 9

retidoboolean

true quando o tomador (geralmente órgão público) é responsável por reter e recolher o ISS.

Default: false

tipoImunidadeinteger

Tipo de imunidade conforme tabela DPS, quando aplicável.

Tamanho: 1 – 4

retencaoobject

Impostos federais retidos na fonte pelo tomador. Cada bloco recebe só a aliquota (em percentual); o valor é calculado se omitido. Todos opcionais.

pisobject

{ "aliquota": 0.65 } — PIS retido. valor opcional.

cofinsobject

{ "aliquota": 3 } — COFINS retido. valor opcional.

csllobject

{ "aliquota": 1 } — CSLL retido. valor opcional.

inssobject

INSS retido. valor opcional.

irrfobject

IRRF retido. valor opcional.

cppobject

CPP retido. valor opcional.

outrasnumber

Outras retenções federais (valor em reais).

apuracaoPropriaobject

PIS/COFINS apurados e recolhidos pelo próprio prestador (regime não-cumulativo) — não retidos pelo tomador.

cstPisCofinsstring

CST de PIS/COFINS.

Formato: 2 dígitosExemplo: 01

baseCalculoPisCofinsnumber

Base de cálculo PIS/COFINS em reais. Default = valor do serviço.

Exemplo: 1000

pisobject

{ "aliquota": 1.65 } — PIS próprio. valor opcional.

cofinsobject

{ "aliquota": 7.6 } — COFINS próprio. valor opcional.

reformaobject

Bloco IBS/CBS/IS deste item — ver Reforma Tributária pra detalhamento completo de campos e CST. Alíquotas em percentual. (antes: reformaTributaria)

informacoesComplementaresstring

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

Tamanho: 0 – 2000

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

razaoSocialstringRecomendado

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

Tamanho: 0 – 200

consumidorFinalboolean

Marca o tomador como consumidor final. Afeta cálculo de impostos em alguns cenários. (antes ficava no nível raiz do request; agora vive apenas dentro de tomador)

Default: false

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

tipoLogradourostring

Tipo do logradouro (Rua, Av, Rod). Opcional.

Tamanho: 0 – 30

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

tipoBairrostring

Tipo do bairro. Opcional.

Tamanho: 0 – 30

bairrostringObrigatório

Tamanho: 0 – 100

codigoCidadestringObrigatório

Código IBGE do município do tomador. (antes: municipioIbge)

Formato: IBGE 7 dígitos

descricaoCidadestring

Nome do município. Opcional.

Tamanho: 0 – 120

estadostringObrigatório

UF do tomador. (antes: uf)

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

Exemplo de request

POST /nfse

{
  "idIntegracao": "OS-30046339",
  "prestador": {
    "cpfCnpj": "82653726000198"
  },
  "tomador": {
    "cpfCnpj": "77856995003218",
    "razaoSocial": "Cliente Exemplo LTDA",
    "consumidorFinal": false,
    "email": "financeiro@cliente.com",
    "endereco": {
      "logradouro": "Av. Brasil",
      "numero": "1000",
      "bairro": "Centro",
      "codigoCidade": "4104808",
      "estado": "PR",
      "cep": "85801000"
    }
  },
  "servico": [
    {
      "codigo": "10701",
      "codigoTributacao": "10701",
      "discriminacao": "Consultoria em desenvolvimento de software",
      "municipioPrestacao": "4104808",
      "cnae": "6202300",
      "valor": {
        "servico": 660.64
      },
      "iss": {
        "tipoTributacao": 1,
        "exigibilidade": 1,
        "aliquota": 3,
        "retido": false
      },
      "retencao": {
        "pis": { "aliquota": 0.65 },
        "cofins": { "aliquota": 3 },
        "csll": { "aliquota": 1 }
      }
    }
  ]
}

Cálculo automático

Repare que nenhum imposto traz valor — só a aliquota. A Notare calcula o ISS, o PIS, a COFINS e a CSLL a partir do valor do serviço (R$ 660,64). Mande só as alíquotas. Veja Cálculo automático de impostos.

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