Pular para o conteúdo
notemnotemDocumentação

Referência da API › Notas

Emitir nota

Envia a NFS-e ao governo e devolve a nota autorizada ou o motivo da recusa.

POST/api/v1/notas

Use para emitir uma nota fiscal de serviço por uma empresa que já está pronta para emitir (veja Consultar situação). A notem monta a nota com o serviço e o tomador cadastrados ou informados no pedido, envia ao governo e espera a resposta por até cerca de 20 segundos.

Antes de gerar o número da nota, a notem confere a empresa, o serviço, o tomador e os tributos. Se algo estiver errado, a resposta é 422 com o campo e o motivo, e nenhum número é usado. Por exemplo, o tomador não pode ter o mesmo CPF/CNPJ da empresa (E0202 — o CPF/CNPJ do tomador é igual ao da empresa emitente), e ISS retido pelo tomador exige CPF/CNPJ e endereço completo no Brasil (E0204 e E0237). Todas as recusas do governo, com o que fazer em cada uma, estão em Rejeições do governo.

O que esperar: 201 com a nota autorizada; 422 REJEITADO_GOVERNO quando o governo recusa, com o motivo original e uma explicação em português; 202 quando o governo não respondeu a tempo. No caso do 202, a nota fica em verificação, a notem descobre o resultado sozinha e avisa por webhook (nota.autorizada ou nota.rejeitada).

O cabeçalho Idempotency-Key é obrigatório e evita nota duplicada. Se a conexão cair e você não souber se a nota foi emitida, consulte a nota antes de tentar de novo. Repetir com a mesma Idempotency-Key é seguro: devolve a mesma nota, sem emitir outra. Nunca use uma chave nova para repetir o mesmo pedido. A chave fica ligada a essa nota para sempre; usá-la com outro conteúdo responde 409.

Se o único motivo da recusa for número já usado (E0014 — já existe uma nota da empresa com essa série e número), a notem tenta sozinha os números seguintes, até cinco vezes, e a nota mantém o mesmo ID.

Parâmetros

Idempotency-Keytextono cabeçalhoobrigatório
1 a 100 caracteres

Corpo da requisição

Os textos são ajustados antes da conferência (por exemplo, aspas e travessões viram equivalentes aceitos) e a nota usa o texto ajustado; caracteres sem equivalente, como emojis, retornam 422 com a mensagem "contém caracteres não aceitos pela NFS-e". Indique a empresa de uma única forma, o serviço de uma única forma e o tomador de no máximo uma forma. Com ISS retido pelo tomador, o tomador precisa de CPF/CNPJ e endereço completo no Brasil.

empresa_idtexto
UUID
empresa_id_externotexto
1 a 100 caracteres
id_externotexto ou null
Único por organização · até 100 caracteres
servico_idtexto
UUID
servico_id_externotexto
1 a 100 caracteres
competenciatexto
Não pode ser futura; padrão data atual em Brasília · data AAAA-MM-DD
descricaotexto
1 a 2000 caracteres
tomadorobjeto ou null
tomador.id_externotexto ou null
Único por empresa · até 100 caracteres
tomador.tipotextoobrigatório
Valores: pj, pf, estrangeiro
tomador.nometextoobrigatório
1 a 150 caracteres
tomador.documentotexto ou null
CPF (11 números) ou CNPJ (14 posições, numérico ou alfanumérico) com dígitos verificadores válidos; máscara e minúsculas são normalizadas · até 18 caracteres
tomador.niftexto ou null
até 40 caracteres
tomador.motivo_sem_niftexto ou null
Valores: dispensado, nao_exigido
tomador.emailtexto ou null
tomador.telefonetexto ou null
tomador.inscricao_municipaltexto ou null
até 15 caracteres
tomador.enderecoobjeto ou null
Nacional exige CEP/logradouro/número/bairro/IBGE. Exterior exige país/cidade/código postal/província/logradouro ou endereço livre/número/bairro. Complemento opcional.
tomador.endereco.ceptexto
Formato: ^[0-9]{8}$
tomador.endereco.codigo_municipiotexto
Formato: ^[0-9]{7}$
tomador.endereco.paistexto
Formato: ^[A-Z]{2}$
tomador.endereco.cidadetexto
tomador.endereco.codigo_postaltexto
tomador.endereco.estado_provincia_regiaotexto
tomador.endereco.logradourotexto
tomador.endereco.endereco_livretexto
tomador.endereco.numerotexto
tomador.endereco.bairrotexto
tomador.endereco.complementotexto ou null
tomador_idtexto
UUID
tomador_id_externotexto
até 100 caracteres
valoresobjetoobrigatório
valores.servicotextoobrigatório
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.desconto_incondicionadotexto
Zero não é enviado ao governo, que só aceita desconto maior que zero e menor que o valor do serviço. · Formato: ^\d+\.\d{2}$
valores.desconto_condicionadotexto
Zero não é enviado ao governo, que só aceita desconto maior que zero e menor que o valor do serviço. · Formato: ^\d+\.\d{2}$
retencao_isstexto ou null
Valores: nao_retido, retido_tomador, retido_intermediario
aliquota_iss_simplestexto ou null
local_prestacaoobjeto ou null
local_prestacao.codigo_municipiotexto
Formato: ^\d{7}$
informacoes_complementarestexto ou null
até 2000 caracteres

Respostas

201 Nota autorizada (incluindo repetição)

Campos da resposta
idtexto
UUID
id_externotexto ou null
origemtexto
externa = emitida por outro sistema ou pelo Portal Nacional; somente leitura (cancelar, solicitar análise e substituir respondem 409 CONFLITO) · Valores: notem, externa
empresa_idtexto
UUID
ambientetexto
Valores: homologacao, producao
situacaotexto
Valores: processando, em_verificacao, autorizada, rejeitada, cancelamento_em_analise, cancelada, substituida, cancelada_prefeitura
restricoeslista de texto
manifestacaoobjeto ou null
numerotexto ou null
chave_acessotexto ou null
50 posições; as 14 do CNPJ do emitente podem conter letras · Formato: ^[0-9]{9}[0-9A-Z]{14}[0-9]{27}$
serie_dpstexto
Série da DPS, a declaração que a notem envia ao governo para gerar a nota; atribuída pela notem
numero_dpstexto
Número da declaração enviada ao governo (DPS); não é o número da NFS-e, que está em numero
competenciatexto
data AAAA-MM-DD
emitida_emtexto
data e hora ISO 8601
autorizada_emtexto ou null
data e hora ISO 8601
tomadorobjeto ou null
tomador.idtexto
UUID
tomador.id_externotexto ou null
Único por empresa · até 100 caracteres
tomador.tipotexto
Valores: pj, pf, estrangeiro
tomador.nometexto
1 a 150 caracteres
tomador.documentotexto ou null
CPF (11 números) ou CNPJ (14 posições, numérico ou alfanumérico) com dígitos verificadores válidos; máscara e minúsculas são normalizadas · até 18 caracteres
tomador.niftexto ou null
até 40 caracteres
tomador.motivo_sem_niftexto ou null
Valores: dispensado, nao_exigido
tomador.emailtexto ou null
tomador.telefonetexto ou null
tomador.inscricao_municipaltexto ou null
até 15 caracteres
tomador.enderecoobjeto ou null
Nacional exige CEP/logradouro/número/bairro/IBGE. Exterior exige país/cidade/código postal/província/logradouro ou endereço livre/número/bairro. Complemento opcional.
tomador.endereco.ceptexto
Formato: ^[0-9]{8}$
tomador.endereco.codigo_municipiotexto
Formato: ^[0-9]{7}$
tomador.endereco.paistexto
Formato: ^[A-Z]{2}$
tomador.endereco.cidadetexto
tomador.endereco.codigo_postaltexto
tomador.endereco.estado_provincia_regiaotexto
tomador.endereco.logradourotexto
tomador.endereco.endereco_livretexto
tomador.endereco.numerotexto
tomador.endereco.bairrotexto
tomador.endereco.complementotexto ou null
tomador.criada_emtexto
data e hora ISO 8601
tomador.atualizada_emtexto
data e hora ISO 8601
servicoobjeto
servico.servico_idtexto
UUID
servico.codigo_servicotexto
servico.descricaotexto
valoresobjeto
valores.servicotexto
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.desconto_incondicionadotexto
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.desconto_condicionadotexto
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.base_calculotexto ou null
valores.aliquota_isstexto ou null
valores.valor_isstexto ou null
valores.valor_liquidotexto ou null
valores.iss_retidobooleano
local_prestacaoobjeto
ibs_cbsobjeto ou null
ibs_cbs.classificacaoobjeto
ibs_cbs.classificacao.csttexto ou null
ibs_cbs.classificacao.codigotexto ou null
ibs_cbs.indicador_operacaotexto ou null
ibs_cbs.consumidor_finalbooleano
ibs_cbs.localidade_incidenciaobjeto
ibs_cbs.localidade_incidencia.codigo_municipiotexto ou null
ibs_cbs.localidade_incidencia.nometexto ou null
ibs_cbs.percentual_redutortexto ou null
ibs_cbs.base_calculotexto ou null
ibs_cbs.ajuste_base_calculotexto ou null
ibs_cbs.ajuste_base_locacao_imoveistexto ou null
ibs_cbs.ibs_ufobjeto
ibs_cbs.ibs_uf.aliquotatexto ou null
ibs_cbs.ibs_uf.reducao_aliquotatexto ou null
ibs_cbs.ibs_uf.aliquota_efetivatexto ou null
ibs_cbs.ibs_uf.valortexto ou null
ibs_cbs.ibs_uf.diferimentotexto ou null
ibs_cbs.ibs_municipalobjeto
ibs_cbs.ibs_municipal.aliquotatexto ou null
ibs_cbs.ibs_municipal.reducao_aliquotatexto ou null
ibs_cbs.ibs_municipal.aliquota_efetivatexto ou null
ibs_cbs.ibs_municipal.valortexto ou null
ibs_cbs.ibs_municipal.diferimentotexto ou null
ibs_cbs.cbsobjeto
ibs_cbs.cbs.aliquotatexto ou null
ibs_cbs.cbs.reducao_aliquotatexto ou null
ibs_cbs.cbs.aliquota_efetivatexto ou null
ibs_cbs.cbs.valortexto ou null
ibs_cbs.cbs.diferimentotexto ou null
ibs_cbs.valor_total_ibstexto ou null
ibs_cbs.valor_total_ibs_cbstexto ou null
vIBSTot + vCBS
ibs_cbs.valor_total_notatexto ou null
vTotNF (valor líquido + IBS/CBS)
ibs_cbs.credito_presumido_ibsobjeto ou null
ibs_cbs.credito_presumido_ibs.percentualtexto ou null
ibs_cbs.credito_presumido_ibs.valortexto ou null
ibs_cbs.credito_presumido_cbsobjeto ou null
ibs_cbs.credito_presumido_cbs.percentualtexto ou null
ibs_cbs.credito_presumido_cbs.valortexto ou null
ibs_cbs.receita_bruta_simplestexto ou null
ibs_cbs.versao_calculadoratexto ou null
erros_governolista de objeto
substitui_nota_idtexto ou null
UUID
substituida_por_nota_idtexto ou null
UUID
operacao_pendenteobjeto ou null
Pedido aguardando confirmação do governo; null quando não houver
operacao_pendente.tipotexto
Valores: cancelamento, analise_cancelamento
operacao_pendente.estadotexto
Valores: em_verificacao
operacao_pendente.desdetexto ou null
data e hora ISO 8601
cancelamentoobjeto ou null
Último pedido de cancelamento ou análise fiscal; null quando nunca houve
cancelamento.tipotexto
Valores: cancelamento, analise_cancelamento
cancelamento.motivotexto
Valores: erro_emissao, servico_nao_prestado, outros
cancelamento.justificativatexto
cancelamento.solicitado_emtexto ou null
data e hora ISO 8601
cancelamento.registrado_emtexto ou null
data e hora ISO 8601
cancelamento.situacaotexto
Valores: em_verificacao, cancelado, em_analise, recusado, nao_registrado, nao_enviado
cancelamento.pode_solicitar_analisebooleano
cancelamento.registrado_fora_da_notembooleano
cancelamento.erros_governolista de objeto
linksobjeto
links.xmltexto
endereço (URL)
links.pdftexto
endereço (URL)
links.consulta_publicatexto ou null
criada_emtexto
data e hora ISO 8601
atualizada_emtexto
data e hora ISO 8601

202 Nota em processamento ou verificação automática

Campos da resposta
idtexto
UUID
id_externotexto ou null
origemtexto
externa = emitida por outro sistema ou pelo Portal Nacional; somente leitura (cancelar, solicitar análise e substituir respondem 409 CONFLITO) · Valores: notem, externa
empresa_idtexto
UUID
ambientetexto
Valores: homologacao, producao
situacaotexto
Valores: processando, em_verificacao, autorizada, rejeitada, cancelamento_em_analise, cancelada, substituida, cancelada_prefeitura
restricoeslista de texto
manifestacaoobjeto ou null
numerotexto ou null
chave_acessotexto ou null
50 posições; as 14 do CNPJ do emitente podem conter letras · Formato: ^[0-9]{9}[0-9A-Z]{14}[0-9]{27}$
serie_dpstexto
Série da DPS, a declaração que a notem envia ao governo para gerar a nota; atribuída pela notem
numero_dpstexto
Número da declaração enviada ao governo (DPS); não é o número da NFS-e, que está em numero
competenciatexto
data AAAA-MM-DD
emitida_emtexto
data e hora ISO 8601
autorizada_emtexto ou null
data e hora ISO 8601
tomadorobjeto ou null
tomador.idtexto
UUID
tomador.id_externotexto ou null
Único por empresa · até 100 caracteres
tomador.tipotexto
Valores: pj, pf, estrangeiro
tomador.nometexto
1 a 150 caracteres
tomador.documentotexto ou null
CPF (11 números) ou CNPJ (14 posições, numérico ou alfanumérico) com dígitos verificadores válidos; máscara e minúsculas são normalizadas · até 18 caracteres
tomador.niftexto ou null
até 40 caracteres
tomador.motivo_sem_niftexto ou null
Valores: dispensado, nao_exigido
tomador.emailtexto ou null
tomador.telefonetexto ou null
tomador.inscricao_municipaltexto ou null
até 15 caracteres
tomador.enderecoobjeto ou null
Nacional exige CEP/logradouro/número/bairro/IBGE. Exterior exige país/cidade/código postal/província/logradouro ou endereço livre/número/bairro. Complemento opcional.
tomador.endereco.ceptexto
Formato: ^[0-9]{8}$
tomador.endereco.codigo_municipiotexto
Formato: ^[0-9]{7}$
tomador.endereco.paistexto
Formato: ^[A-Z]{2}$
tomador.endereco.cidadetexto
tomador.endereco.codigo_postaltexto
tomador.endereco.estado_provincia_regiaotexto
tomador.endereco.logradourotexto
tomador.endereco.endereco_livretexto
tomador.endereco.numerotexto
tomador.endereco.bairrotexto
tomador.endereco.complementotexto ou null
tomador.criada_emtexto
data e hora ISO 8601
tomador.atualizada_emtexto
data e hora ISO 8601
servicoobjeto
servico.servico_idtexto
UUID
servico.codigo_servicotexto
servico.descricaotexto
valoresobjeto
valores.servicotexto
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.desconto_incondicionadotexto
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.desconto_condicionadotexto
Valor em reais, ponto decimal, 2 casas · Formato: ^\d+\.\d{2}$
valores.base_calculotexto ou null
valores.aliquota_isstexto ou null
valores.valor_isstexto ou null
valores.valor_liquidotexto ou null
valores.iss_retidobooleano
local_prestacaoobjeto
ibs_cbsobjeto ou null
ibs_cbs.classificacaoobjeto
ibs_cbs.classificacao.csttexto ou null
ibs_cbs.classificacao.codigotexto ou null
ibs_cbs.indicador_operacaotexto ou null
ibs_cbs.consumidor_finalbooleano
ibs_cbs.localidade_incidenciaobjeto
ibs_cbs.localidade_incidencia.codigo_municipiotexto ou null
ibs_cbs.localidade_incidencia.nometexto ou null
ibs_cbs.percentual_redutortexto ou null
ibs_cbs.base_calculotexto ou null
ibs_cbs.ajuste_base_calculotexto ou null
ibs_cbs.ajuste_base_locacao_imoveistexto ou null
ibs_cbs.ibs_ufobjeto
ibs_cbs.ibs_uf.aliquotatexto ou null
ibs_cbs.ibs_uf.reducao_aliquotatexto ou null
ibs_cbs.ibs_uf.aliquota_efetivatexto ou null
ibs_cbs.ibs_uf.valortexto ou null
ibs_cbs.ibs_uf.diferimentotexto ou null
ibs_cbs.ibs_municipalobjeto
ibs_cbs.ibs_municipal.aliquotatexto ou null
ibs_cbs.ibs_municipal.reducao_aliquotatexto ou null
ibs_cbs.ibs_municipal.aliquota_efetivatexto ou null
ibs_cbs.ibs_municipal.valortexto ou null
ibs_cbs.ibs_municipal.diferimentotexto ou null
ibs_cbs.cbsobjeto
ibs_cbs.cbs.aliquotatexto ou null
ibs_cbs.cbs.reducao_aliquotatexto ou null
ibs_cbs.cbs.aliquota_efetivatexto ou null
ibs_cbs.cbs.valortexto ou null
ibs_cbs.cbs.diferimentotexto ou null
ibs_cbs.valor_total_ibstexto ou null
ibs_cbs.valor_total_ibs_cbstexto ou null
vIBSTot + vCBS
ibs_cbs.valor_total_notatexto ou null
vTotNF (valor líquido + IBS/CBS)
ibs_cbs.credito_presumido_ibsobjeto ou null
ibs_cbs.credito_presumido_ibs.percentualtexto ou null
ibs_cbs.credito_presumido_ibs.valortexto ou null
ibs_cbs.credito_presumido_cbsobjeto ou null
ibs_cbs.credito_presumido_cbs.percentualtexto ou null
ibs_cbs.credito_presumido_cbs.valortexto ou null
ibs_cbs.receita_bruta_simplestexto ou null
ibs_cbs.versao_calculadoratexto ou null
erros_governolista de objeto
substitui_nota_idtexto ou null
UUID
substituida_por_nota_idtexto ou null
UUID
operacao_pendenteobjeto ou null
Pedido aguardando confirmação do governo; null quando não houver
operacao_pendente.tipotexto
Valores: cancelamento, analise_cancelamento
operacao_pendente.estadotexto
Valores: em_verificacao
operacao_pendente.desdetexto ou null
data e hora ISO 8601
cancelamentoobjeto ou null
Último pedido de cancelamento ou análise fiscal; null quando nunca houve
cancelamento.tipotexto
Valores: cancelamento, analise_cancelamento
cancelamento.motivotexto
Valores: erro_emissao, servico_nao_prestado, outros
cancelamento.justificativatexto
cancelamento.solicitado_emtexto ou null
data e hora ISO 8601
cancelamento.registrado_emtexto ou null
data e hora ISO 8601
cancelamento.situacaotexto
Valores: em_verificacao, cancelado, em_analise, recusado, nao_registrado, nao_enviado
cancelamento.pode_solicitar_analisebooleano
cancelamento.registrado_fora_da_notembooleano
cancelamento.erros_governolista de objeto
linksobjeto
links.xmltexto
endereço (URL)
links.pdftexto
endereço (URL)
links.consulta_publicatexto ou null
criada_emtexto
data e hora ISO 8601
atualizada_emtexto
data e hora ISO 8601

400 Erro no formato padrão

401 Chave ausente, inválida ou revogada

404 Erro no formato padrão

409 IDEMPOTENCIA_CONFLITO, ID_EXTERNO_DUPLICADO ou configuração alterada

422 REGRA_DE_NEGOCIO, EMPRESA_NAO_PRONTA ou REJEITADO_GOVERNO (detalhes incluem nota_id e mensagens originais)

503 Erro no formato padrão

Limites

Esta operação: 20 por minuto em produção e 10 em homologação; no máximo 2 ao mesmo tempo por empresa. Valem também os limites gerais da chave. Veja Limites de uso.