Pular para o conteúdo
notemnotemDocumentação

Referência da API › Notas

Cancelar nota

Pede ao governo o cancelamento de uma nota autorizada e devolve a nota cancelada ou o motivo da recusa.

POST/api/v1/notas/{id}/cancelar

Use quando a nota foi emitida por engano ou o serviço não foi prestado. Só é possível cancelar nota autorizada, emitida pela notem no ambiente da chave, e cada nota aceita um pedido por vez. Informe o motivo e uma justificativa de 15 a 255 caracteres.

O que esperar: 200 com a nota cancelada; 422 REJEITADO_GOVERNO quando o governo recusa, com o motivo original e uma explicação em português; 202 quando o governo ainda não confirmou. No caso do 202, a nota continua autorizada, com operacao_pendente preenchido, até a notem descobrir o resultado e avisar por webhook.

Alguns municípios não permitem cancelar diretamente, por exemplo depois do prazo ou acima de um valor. Nesses casos a recusa vem com pode_solicitar_analise: true, e você pode pedir que a prefeitura analise o cancelamento em Solicitar análise do cancelamento.

O cabeçalho Idempotency-Key é obrigatório. Repetir o pedido com a mesma chave é seguro: devolve o mesmo resultado, sem enviar outro pedido ao governo.

Se a nota já tiver sido cancelada por outro caminho, como o Portal Nacional, a notem encontra o cancelamento no governo, marca a nota como cancelada e responde 200. O histórico da nota mostra "Cancelamento registrado fora da notem".

Parâmetros

idtextono caminhoobrigatório
UUID (RFC 9562). Fora do padrão: 400 REQUISICAO_INVALIDA com campo igual ao nome do parâmetro. · UUID
Idempotency-Keytextono cabeçalhoobrigatório
1 a 100 caracteres

Corpo da requisição

motivotextoobrigatório
Valores: erro_emissao, servico_nao_prestado, outros
justificativatextoobrigatório

Respostas

200 Cancelamento registrado; nota com situacao cancelada

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 Aguardando confirmação do governo; nota segue autorizada com operacao_pendente

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 CONFLITO (nota não autorizada, pedido ou substituição em andamento) ou IDEMPOTENCIA_CONFLITO

422 REGRA_DE_NEGOCIO (justificativa, certificado), EMPRESA_NAO_PRONTA ou REJEITADO_GOVERNO

503 Erro no formato padrão

Limites

Esta operação: 10 por minuto; 1 de cada vez por nota. Valem também os limites gerais da chave. Veja Limites de uso.