Erros e recuperação

Há três situações diferentes: uma entrada inválida no modelo, uma falha de configuração/execução e um resultado fiscal sem sucesso. O tratamento depende de qual delas ocorreu.

1. Entrada inválida

Os modelos podem lançar TypeError por campo desconhecido, tipo incorreto ou valor que não corresponde ao contrato. A mensagem aponta o caminho do campo, por exemplo um decimal dentro de TNFe.Det[0].Prod.

Corrija os dados e os nomes antes de executar de novo. Veja Modelos TypeScript.

2. Resultado sem sucesso

O motor pode responder normalmente com sucesso: false. Rejeições fiscais e recibos pendentes são resultados; não há retry automático.

const resultado = await emissor.validar(xml);
if (!resultado.sucesso) {
  console.error('Validação:', resultado.codigo ?? resultado.estado);
  // Corrija a causa antes de seguir para a próxima operação.
}

Leia codigo, cStat e xMotivo quando estiverem disponíveis. Registre apenas os campos necessários, sem PFX, senha ou CSC.

3. ErroAcbrNode

Falhas do supervisor lançam ErroAcbrNode. Ele tem codigo, resultadoDesconhecido e, em falha de transmissão, pode preservar xmlBase64 para recuperação.

import { ErroAcbrNode } from 'cosmemilton-acbr-node';

try {
  const resultado = await emissor.gerarXml(nota);
  // Confira resultado.sucesso.
} catch (erro) {
  if (erro instanceof ErroAcbrNode) {
    console.error('Código:', erro.codigo);
    if (erro.resultadoDesconhecido) {
      // Marque a operação para recuperação da situação fiscal.
    }
  } else {
    throw erro;
  }
} finally {
  await emissor.fechar();
}

Códigos comuns do supervisor

Código	Próximo passo
CONFIGURACAO_INVALIDA	Confira CNPJ, UF, modelo, ambiente e limites
CERTIFICADO_AUSENTE	Configure A1 ou confira o caminho e a leitura do arquivo
CERTIFICADO_INVALIDO	Informe apenas pfx ou arquivo, com senha em string
CSC_INVALIDO	Confira ID e valor do CSC
RUNTIME_AUSENTE	Instale o runtime correto e preserve dependências opcionais
RUNTIME_SEM_CAPACIDADE	O manifesto do runtime não anuncia recuperarXml; use um runtime compatível e íntegro. A falha ocorre antes de iniciar o processo
PLATAFORMA_NAO_SUPORTADA	Use Linux/Windows x64
CONTRATO_DIVERGENTE	Use cliente e motor da mesma geração/versão
RUNTIME_ALTERADO, RUNTIME_INCOMPLETO, RUNTIME_INVALIDO	Reinstale o pacote; em runtime próprio, confira manifesto e arquivos
XML_INVALIDO	Informe XML não vazio, até 2 MiB
FILA_CHEIA	Controle a concorrência e acompanhe as operações aguardando
TIMEOUT_MOTOR, FALHA_MOTOR, FALHA_PIPE	Confira possível envio antes de decidir uma repetição
OPERACAO_CANCELADA	Confira se cancelou antes da execução ou após um possível envio
EMISSOR_FECHADO	Crie outra instância para novas operações

Quando o resultado é desconhecido

Um timeout, crash ou cancelamento pode acontecer depois de um serviço ter recebido a solicitação. Encerrar o processo não desfaz esse envio.

Marque a operação como pendente de recuperação, preserve chave e XML assinado e consulte a situação fiscal por um fluxo operacional apropriado antes de decidir uma nova transmissão. resultadoDesconhecido ajuda a sinalizar essa necessidade; ele não informa que houve autorização.

Não conecte uma tentativa automática de transmissão ao catch. O supervisor não faz retries fiscais.

Se o XML assinado original foi preservado, recuperarXml(xmlAssinado, opcoes?) pode consultar e devolver o processo autorizado após as conferências do motor. consultar({ chave }) continua sendo a consulta de situação; seu XML de resposta não é o nfeProc. Siga o fluxo de recuperação de XML, sem retransmissão automática.

Quando a recuperação do XML não é comprovada

recuperarXml pode terminar normalmente com sucesso: false; isso é diferente de uma exceção do supervisor, como RUNTIME_SEM_CAPACIDADE.

Código/condição da recuperação	Tratamento
RECUPERACAO_NAO_COMPROVADA	Preserve o original e confira o diagnóstico. Status diferentes de 100, inclusive 150/217, não devolvem processo nem protocolo
IDENTIDADE_DIVERGENTE	Confira chave, emitente, UF, modelo, ambiente e digest. Não componha um protocolo manualmente nem troque o documento para contornar a divergência
XML_SCHEMA_INVALIDO	Confira o XML de entrada, o retorno da consulta e o processo composto pelo motor; a recuperação não disponibiliza um processo inválido como sucesso
Resposta 100 com retCancNFe ou procEventoNFe	Exige análise separada; a recuperação é recusada com RECUPERACAO_NAO_COMPROVADA, sem processo ou protocolo de recuperação
protNFe com assinatura XMLDSig adicional	O motor deste conjunto recusa a recuperação com RECUPERACAO_NAO_COMPROVADA, mesmo com cStat: 100; não oferece verificação independente dessa assinatura do protocolo

O sucesso comprovado usa XML_RECUPERADO; os bytes só devem ser tratados como processo recuperado quando também houver sucesso: true, cStat: 100 e xmlBase64. envioIniciado: false nessa operação informa que não se transmitiu nota ou evento, embora uma consulta de rede possa ter ocorrido. Cancelar com AbortSignal não cancela a autorização fiscal.

Para mostrar o erro sem copiar XML, certificado, caminhos ou respostas brutas para logs, use resultado.diagnostico ou os helpers públicos diagnosticarResultado(resultado, 'recuperarXml') e diagnosticarErro(erro). Eles não consultam nem retransmitem por conta própria.

Problemas de ambiente

Quando presente, TLS_SERVIDOR_INVALIDO sinaliza uma conexão recusada pelo wrapper TLS; o código sozinho não identifica a causa. Preserve o retorno original do ACBr quando estiver disponível e siga TLS no Linux para investigar cadeia, CA, hostname, relógio e proxy. O motor também pode devolver RESULTADO_INDETERMINADO sem expor a causa TLS original; se houver possibilidade de envio, mantenha o fluxo de recuperação descrito acima.

Se a falha acontece antes de gerar XML, comece pela solução de problemas. Em runtime próprio, confira o log .acbr/build.log e os comandos de revisão própria.