Operações da API

Importe criarEmissor de cosmemilton-acbr-node e configure a instância. Todos os métodos fiscais retornam Promise<ResultadoFiscal>; fechar() retorna Promise<void>.

Confira sucesso em cada resultado. Uma resposta recebida não significa uma nota autorizada. A rejeição fiscal pode ser um resultado normal, enquanto falhas de configuração ou execução podem lançar erros.

Para escolher os nomes e os valores de entrada, consulte a ajuda de campos e tipos. A consulta lê o contrato instalado, funciona offline e não inicia o motor fiscal.

Na 0.2.2 publicada, use describe TARGET para consultar um campo ou tipo em português e --json para automação. A CLI mantém help TAG caminho para compatibilidade com a 0.2.1.

Métodos disponíveis

Método	Entrada	Usa serviço fiscal?	A1
gerarXml	TNFe ou TNFeInput	Não	Não exige
assinar	XML UTF-8 em string	Não	Exige
validar	XML UTF-8 em string	Não	Não exige
transmitir	XML UTF-8 em string	Sim	Exige
consultar	Chave e recibo opcional	Sim	Exige
recuperarXml	XML UTF-8 de uma única NFe 4.00 já assinada	Sim, consulta pela chave do XML	Exige
cancelar	Chave, protocolo e justificativa	Sim	Exige
cartaCorrecao	Chave, correção e sequência opcional	Sim	Exige
inutilizar	Ano, série, faixa e justificativa	Sim	Exige
fechar	Sem argumentos	Não	Não exige

Os fragmentos a seguir descrevem o contrato de cada método. emissor, nota e xml devem existir em sua aplicação. Os métodos que usam serviço fiscal não fazem parte do exemplo offline e não devem ser executados como teste de desenvolvimento contra a SEFAZ.

gerarXml

const resultado = await emissor.gerarXml(new TNFe(nota));

Gera XML a partir dos modelos ACBr. Não assina e não transmite. Campos de entrada precisam usar nomes e tipos gerados. Consulte o exemplo completo offline.

assinar

const resultado = await emissor.assinar(xml);

Usa o A1 configurado. O motor também verifica o schema na operação de assinatura; falhas podem retornar XML_SCHEMA_INVALIDO. Para NFC-e, a assinatura exige CSC. O XML assinado é devolvido em xmlBase64.

validar

const resultado = await emissor.validar(xmlAssinado);

Confere a estrutura do XML com os schemas do runtime. Não autoriza a nota nem determina se os valores tributários estão corretos. O schema da NF-e completa exige assinatura.

transmitir

const resultado = await emissor.transmitir(xmlAssinado);

É uma operação explícita com efeitos fiscais. Guarde XML e chave antes de iniciar o envio; depois, persista a resposta, incluindo recibo e protocolo quando presentes. Não há retry automático. Uma resposta pendente exige acompanhamento, e um timeout pode exigir recuperação da situação fiscal.

consultar

const resultado = await emissor.consultar({ chave });
// Quando sua aplicação tiver recebido um recibo:
const respostaRecibo = await emissor.consultar({ chave, recibo });

chave deve ter 44 dígitos. recibo, quando informado, deve ter 15 dígitos. A operação usa o serviço fiscal configurado; não é uma leitura do seu banco de dados.

xmlBase64, quando presente nessa consulta, contém a resposta do serviço, normalmente retConsSitNFe. Esse retorno não substitui o XML assinado original nem é o processo completo nfeProc.

recuperarXml

Disponível no SDK 0.2.2 publicado, com runtimes compatíveis 0.2.1:

const controlador = new AbortController();
const resultado = await emissor.recuperarXml(xmlAssinado, {
  signal: controlador.signal
});

Para omitir as opções, use emissor.recuperarXml(xmlAssinado). xmlAssinado é uma string UTF-8 contendo uma única NFe 4.00 assinada e preservada pela aplicação, sem envelope, DTD ou entidades externas. Não passe apenas a chave, base64 ou um nfeProc. O limite de entrada é 2 MiB. O segundo argumento é opcional e aceita somente signal?: AbortSignal.

Essa operação consulta um serviço fiscal externo com A1. O motor obtém a chave do XML, confere assinatura, schema, emitente, UF, modelo e ambiente e consulta a situação. Preserva a assinatura original e deixa a gravação dos arquivos para a aplicação; não transmite notas nem registra eventos. Use ambiente: 2 e dados sintéticos nos exemplos de HOMOLOGAÇÃO; essa chamada não faz parte do exemplo offline.

O sucesso exige sucesso === true, estado === 'XML_RECUPERADO', cStat === 100 e xmlBase64 com o nfeProc completo. O motor correlaciona chave, ambiente, protocolo e digVal com a assinatura original antes de compor o processo e confere novamente schema e assinatura. O manifesto do runtime precisa anunciar a capacidade recuperarXml; um motor sem ela lança RUNTIME_SEM_CAPACIDADE antes de iniciar o processo.

O sinal solicita cancelar a operação do SDK; não cancela a autorização fiscal e pode ser acionado depois da consulta ter sido enviada. envioIniciado: false não torna a consulta offline: informa que não houve transmissão de nota ou evento nessa operação.

O guia de recuperação de XML detalha a preservação do original, os estados sem recuperação, as limitações de protocolo e uma simulação completa sem rede ou runtime. A referência do pacote 0.2.2 inclui esse método em docs/API.md e dist/types/src/runtime.d.ts.

cancelar

const resultado = await emissor.cancelar({ chave, protocolo, justificativa });

Chave: 44 dígitos. Protocolo: 15 dígitos. Justificativa: de 15 a 255 caracteres. A aceitação depende das regras e da situação fiscal da nota.

cartaCorrecao

const resultado = await emissor.cartaCorrecao({
  chave,
  correcao,
  sequenciaEvento: 1
});

Disponível apenas para NF-e modelo 55. A correção aceita de 15 a 1000 caracteres; a sequência é um inteiro de 1 a 20, com padrão 1. A aplicação deve acompanhar a sequência e verificar se o conteúdo pode ser corrigido por esse evento.

inutilizar

const resultado = await emissor.inutilizar({
  ano: 26,
  serie: 1,
  numeroInicial: 10,
  numeroFinal: 12,
  justificativa
});

ano usa dois dígitos, de 0 a 99; não use 2026. A série vai de 0 a 999. A numeração inicial começa em 1, e a final deve ser igual ou maior, até 999999999. A justificativa aceita de 15 a 255 caracteres.

Este fragmento documenta os tipos; não é uma instrução para inutilizar uma faixa real.

signal e fechar

Todos os métodos fiscais aceitam { signal: AbortSignal } como último argumento. await emissor.fechar() cancela a fila e encerra a instância. Veja Configuração.

Continue em XML e resultados e Erros e recuperação.