Pular para o conteúdo
notemnotemDocumentação

Referência da API › Notas

Substituir nota

Emite uma nova nota que corrige e substitui uma nota autorizada.

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

Use para corrigir uma nota autorizada sem cancelá-la antes. Envie o motivo, a justificativa e só os campos que mudam; os demais são copiados da nota original. A empresa é sempre a mesma da original.

Antes de gerar o número da nova nota, a notem faz as mesmas conferências da emissão e aplica as regras do governo sobre o que pode mudar. Empresa fora do Simples Nacional não pode mudar competência, código do serviço, código municipal nem local da prestação (E0060). Empresa MEI ou ME/EPP não pode mudar o documento do tomador, a competência nem o valor do serviço (E0061).

As respostas são iguais às de Emitir nota e se referem à nova nota. A original só passa a substituida quando a nova é autorizada. Se a nova for recusada, a original continua valendo.

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

Campos de NotaEntrada são opcionais; os não enviados vêm da nota original. empresa_id, se enviado, deve ser o da original.

motivotextoobrigatório
Valores: desenquadramento_simples, enquadramento_simples, inclusao_imunidade_isencao, exclusao_imunidade_isencao, rejeicao_tomador_intermediario, outros
justificativatextoobrigatório
15 a 255 caracteres após a normalização de texto
id_externotexto ou null
até 100 caracteres
servico_idtexto
UUID
servico_id_externotexto
até 100 caracteres
competenciatexto
data AAAA-MM-DD
descricaotexto
até 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
valoresobjeto
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 substituta autorizada

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 substituta em processamento ou verificaçã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

400 Erro no formato padrão

401 Chave ausente, inválida ou revogada

404 Erro no formato padrão

409 CONFLITO (original não autorizada, pedido ou substituição em andamento) ou IDEMPOTENCIA_CONFLITO

422 REGRA_DE_NEGOCIO (empresa diferente da original, campo que não pode mudar na substituição ou justificativa inválida), EMPRESA_NAO_PRONTA ou REJEITADO_GOVERNO

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.