Inutilizar Numeração

POST/v1/nfe/inutilize

Inutiliza uma faixa de numeração de documentos fiscais junto à SEFAZ. Use este endpoint quando o sistema emissor pulou numeração (por exemplo, por uma falha antes da emissão) — inutilizar a faixa evita autuação por numeração sem justificativa.

Diferente dos demais eventos deste catálogo, este endpoint é síncrono desde sempre: a chamada só retorna depois que a SEFAZ processa o pedido.

Parâmetros do corpo

anonumberobrigatório

Ano de emissão da faixa a inutilizar (4 dígitos).

serienumberobrigatório

Série do documento fiscal.

inicionumberobrigatório

Número inicial da faixa a inutilizar.

fimnumberobrigatório

Número final da faixa a inutilizar.

justificativastringobrigatório

Justificativa da inutilização. Mínimo de 15 caracteres.

modstringpadrão: 55

Modelo do documento fiscal.

cnpjstring

CNPJ do emitente. Quando omitido, usa o CNPJ configurado no tenant.

Formato de resposta diferente dos demais eventos

A resposta deste endpoint não segue o padrão status/status_sefaz/mensagem_sefaz usado pelos outros eventos síncronos do catálogo. Ela retorna o retorno cru da SEFAZ: cStat, xMotivo, nProt (opcional) e xml (opcional).

Resposta

200 OK

cStatstring

Código de status retornado pela SEFAZ.

xMotivostring

Mensagem retornada pela SEFAZ descrevendo o resultado.

nProtstring

Número de protocolo da inutilização, quando homologada.

xmlstring

XML de retorno (procInutNFe) da SEFAZ, quando disponível.

cURL

curl -X POST https://app.nfe.tenzanlabs.com/v1/nfe/inutilize \
  -H "X-Access-Key: nfe_access_SUA_CHAVE_DE_ACESSO_AQUI" \
  -H "Authorization: Bearer nfe_test_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "ano": 2026,
    "serie": 1,
    "inicio": 101,
    "fim": 105,
    "justificativa": "Numeração pulada por falha no sistema emissor",
    "mod": "55"
  }'

Node.js

const resposta = await client.voidRange({
  ano: 2026,
  serie: 1,
  inicio: 101,
  fim: 105,
  justificativa: 'Numeração pulada por falha no sistema emissor',
  mod: '55',
});
console.log(resposta.cStat); // '102'

Python

resposta = client.void_range({
    "ano": 2026,
    "serie": 1,
    "inicio": 101,
    "fim": 105,
    "justificativa": "Numeração pulada por falha no sistema emissor",
    "mod": "55",
})
print(resposta["cStat"])  # '102'

Java

VoidRangeData data = new VoidRangeData();
data.ano = 2026;
data.serie = 1;
data.inicio = 101;
data.fim = 105;
data.justificativa = "Numeração pulada por falha no sistema emissor";
data.mod = "55";

VoidRangeResponse resposta = client.voidRange(data);
System.out.println(resposta.cStat); // "102"

Exemplo de resposta

{
  "cStat": "102",
  "xMotivo": "Inutilização de número homologado",
  "nProt": "135260000123456",
  "xml": "<procInutNFe>...</procInutNFe>"
}