Operações Adicionais

Nem tudo sai perfeito na primeira tentativa. A API oferece operações para lidar com os imprevistos do dia a dia fiscal — cancelamento, correção, inutilização de numeração e consulta de status. Escolha a sua linguagem de preferência abaixo.

Exemplos em NF-e

Os exemplos REST abaixo usam o prefixo /v1/nfe/. Para os demais tipos de documento, troque só o prefixo — /v1/nfc-e/, /v1/cte/, /v1/mdfe/, /v1/nfcom/, /v1/dce/ ou /v1/nfse/ — o corpo e a resposta seguem o mesmo formato (cancelamento e consulta existem em todos os tipos; correção só em NF-e/NFC-e).

1. Cancelamento

O prazo legal para cancelar um documento geralmente é de 24 horas após a autorização. Cancelamento é assíncrono — a resposta só confirma que o pedido entrou na fila.

Node.js

const resposta = await client.cancel('55', invoiceId, {
  reason: 'Erro de digitação nos valores dos produtos.',
});
console.log(resposta.message);

Python

resposta = client.cancel(
    "55",
    invoice_id,
    'Erro de digitação nos valores dos produtos.',
)
print(resposta["message"])

Java

AsyncOperationResponse resposta = client.cancel(
    "55",
    invoiceId,
    "Erro de digitação nos valores dos produtos."
);
System.out.println(resposta.message);

cURL (REST)

curl -X POST https://app.nfe.tenzanlabs.com/v1/nfe/{invoiceId}/cancel \
  -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 '{ "reason": "Erro de digitação nos valores dos produtos." }'

Veja a referência completa em Cancelar.

2. Carta de Correção Eletrônica (CC-e)

Se a nota já passou do prazo de cancelamento ou o erro é pequeno (não afeta impostos, valores, ou dados cruciais do destinatário), emita uma CC-e. Também assíncrono.

Node.js

const resposta = await client.correct('55', invoiceId, {
  correctionText: 'O endereço de entrega correto é Rua das Flores, 123 - Centro.',
});

Python

resposta = client.correct(
    "55",
    invoice_id,
    'O endereço de entrega correto é Rua das Flores, 123 - Centro.',
)

Java

AsyncOperationResponse resposta = client.correct(
    "55",
    invoiceId,
    "O endereço de entrega correto é Rua das Flores, 123 - Centro."
);

cURL (REST)

curl -X POST https://app.nfe.tenzanlabs.com/v1/nfe/{invoiceId}/correct \
  -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 '{ "correctionText": "O endereço de entrega correto é Rua das Flores, 123 - Centro." }'

Veja a referência completa em Corrigir.

3. Inutilização de Numeração

Caso o seu sistema tenha pulado a numeração de um documento, inutilize aquele espaço para evitar autuações da SEFAZ. Essa operação é síncrona — a resposta já vem com o resultado da SEFAZ.

Node.js

const resposta = await client.voidRange({
  ano: 2026,
  serie: 1,
  inicio: 15,
  fim: 15, // apenas o número 15
  justificativa: 'Quebra de sequência na numeração por falha de banco de dados.',
  cnpj: '12345678000199',
});
console.log(resposta.cStat, resposta.xMotivo);

Python

resposta = client.void_range({
    "ano": 2026,
    "serie": 1,
    "inicio": 15,
    "fim": 15,
    "justificativa": "Quebra de sequência na numeração por falha de banco de dados.",
    "cnpj": "12345678000199",
})
print(resposta["cStat"], resposta["xMotivo"])

Java

VoidRangeData data = new VoidRangeData();
data.ano = 2026;
data.serie = 1;
data.inicio = 15;
data.fim = 15;
data.justificativa = "Quebra de sequência na numeração por falha de banco de dados.";
data.cnpj = "12345678000199";

VoidRangeResponse resposta = client.voidRange(data);
System.out.println(resposta.cStat + " " + resposta.xMotivo);

cURL (REST)

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": 15,
    "fim": 15,
    "justificativa": "Quebra de sequência na numeração por falha de banco de dados.",
    "cnpj": "12345678000199"
  }'

Nomes de campo

Os nomes de campo são ano, serie, inicio, fim, justificativa e cnpj — não numeroInicial/numeroFinal/justification, usados em versões antigas destes SDKs.

Veja a referência completa em Inutilizar numeração.

4. Consultando o resultado (polling)

Como emissão, cancelamento e correção são assíncronos, use getInvoice pra acompanhar o status do documento até ele deixar de ser PENDENTE.

Node.js

const nota = await client.getInvoice('55', invoiceId);
console.log(nota.status); // 'PENDENTE' | 'AUTORIZADA' | 'REJEITADA' | ...

Python

nota = client.get_invoice("55", invoice_id)
print(nota["status"])

Java

GetInvoiceResponse nota = client.getInvoice("55", invoiceId);
System.out.println(nota.status);

cURL (REST)

curl https://app.nfe.tenzanlabs.com/v1/nfe/{invoiceId} \
  -H "X-Access-Key: nfe_access_SUA_CHAVE_DE_ACESSO_AQUI" \
  -H "Authorization: Bearer nfe_test_SUA_CHAVE_AQUI"

Veja a referência completa em Consultar documento.