Recuperar XML autorizado

recuperarXml(xmlAssinado, opcoes?) existe no SDK cosmemilton-acbr-node@0.2.2 publicado, com runtimes compatíveis 0.2.1. Ele recebe a NFe assinada original, consulta o serviço fiscal e devolve o processo completo nfeProc somente quando a recuperação é comprovada.

É uma operação de rede com certificado A1. Não faz parte do primeiro exemplo offline. Os exemplos deste guia usam somente HOMOLOGAÇÃO (ambiente: 2) e dados sintéticos; a simulação para download não consulta nenhum serviço nem carrega o SDK ou o motor.

Consulta de situação e recuperação do processo

Operação	O que recebe	O que pode devolver em xmlBase64
consultar({ chave, recibo? })	Chave e recibo opcional	Resposta da consulta, normalmente retConsSitNFe
recuperarXml(xmlAssinado, opcoes?)	XML UTF-8 original, de uma única NFe 4.00 já assinada	Processo nfeProc, se todas as conferências forem satisfeitas

A chave sozinha não permite reconstruir o original nessa API. Preserve previamente os bytes da NFe assinada. As chamadas não compartilham uma coleção nativa de notas entre operações; uma consulta anterior não prepara implicitamente a entrada de recuperarXml.

Antes de iniciar

• Preserve XML assinado, chave, ambiente e dados de acompanhamento em armazenamento controlado pela aplicação.
• Configure o mesmo emitente, UF, modelo e ambiente do documento e um A1 válido para a consulta. Em HOMOLOGAÇÃO, use ambiente: 2.
• Use uma NFe 4.00 sem envelope, DTD ou entidades externas, em string UTF-8 com até 2 MiB. Base64 e nfeProc não são entradas desse método.
• Use um runtime íntegro cujo manifesto anuncie a capacidade recuperarXml. Não acrescente essa capacidade manualmente a um manifesto de motor antigo.

O SDK 0.2.2 utiliza runtimes 0.2.1; a coincidência do contrato dos modelos, sozinha, não comprova a capacidade do motor. Um runtime sem essa capacidade lança ErroAcbrNode com RUNTIME_SEM_CAPACIDADE antes de iniciar o subprocesso.

Chamada da API

O fragmento abaixo pressupõe um emissor já configurado para HOMOLOGAÇÃO e o xmlAssinado sintético preservado pela aplicação. Ele realiza consulta externa se executado com um emissor real; use a simulação abaixo para testar somente a lógica de tratamento.

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

if (
  resultado.sucesso === true &&
  resultado.estado === 'XML_RECUPERADO' &&
  resultado.cStat === 100 &&
  resultado.xmlBase64
) {
  const processo = Buffer.from(resultado.xmlBase64, 'base64');
  // A aplicação decide onde gravar um arquivo NOVO, preservando o original.
} else {
  // Preserve o original e encaminhe o diagnóstico para revisão.
  // Não retransmita nem emita outra nota automaticamente.
}

O segundo argumento pode ser omitido: emissor.recuperarXml(xmlAssinado). OpcoesOperacao aceita somente signal?: AbortSignal; não existe opção allow_network nessa API Node. controlador.abort() solicita cancelar a operação do SDK, sem cancelar a autorização fiscal. A consulta pode já ter sido enviada quando o sinal é acionado.

O que comprova a recuperação

O motor valida o schema e a assinatura original antes da consulta e confere emitente, UF, modelo, ambiente e chave. O sucesso exige cumulativamente:

1. Resposta fiscal com cStat: 100.
2. Protocolo de 15 dígitos vindo da resposta desta consulta, para a mesma chave e ambiente.
3. digVal presente e exatamente igual ao DigestValue da referência assinada da NFe verificada, diferenciando maiúsculas e minúsculas no base64.
4. Composição do processo com a NFe e sua assinatura preservadas, seguida de validação do schema do nfeProc e nova conferência da assinatura da NFe.

A resposta bem-sucedida tem sucesso: true, estado: 'XML_RECUPERADO', cStat: 100 e xmlBase64. O diagnóstico sanitizado usa codigo: 'XML_RECUPERADO', etapa consulta e statusEnvio: 'autorizado'; não exija que o campo opcional resultado.codigo tenha esse valor.

A recuperação faz a consulta e a composição do processo, preservando a assinatura original. A aplicação controla a gravação dos arquivos; não há transmissão de nota nem registro de evento. envioIniciado: false informa que não houve transmissão de nota ou evento nessa operação; não significa ausência de rede.

Quando nenhum processo é devolvido

Situação	Resultado ou ação
Status diferente de 100, inclusive 150 e 217	sucesso: false, estado CONSULTADO, RECUPERACAO_NAO_COMPROVADA, sem XML processado nem protocolo
Chave, ambiente ou digest divergente	Falha com IDENTIDADE_DIVERGENTE; preserve o original e confira o diagnóstico
Schema inválido	Falha com XML_SCHEMA_INVALIDO; não trate o resultado como processo recuperado
Resposta 100 contendo retCancNFe ou procEventoNFe	Exige análise separada; retorna RECUPERACAO_NAO_COMPROVADA, sem XML processado nem protocolo de recuperação
protNFe contendo assinatura XMLDSig adicional (ds:Signature)	O motor deste conjunto recusa a recuperação com RECUPERACAO_NAO_COMPROVADA, mesmo com cStat: 100
Runtime sem capacidade recuperarXml	Exceção RUNTIME_SEM_CAPACIDADE antes de iniciar o motor

O motor deste conjunto não oferece verificação independente de uma assinatura adicional da SEFAZ no protocolo. Ele preserva e confere a assinatura original da NFe e exige a correlação por digest para os protocolos aceitos. Não componha um protocolo a partir de campos escalares nem remova assinaturas para contornar essa limitação.

O tratamento de consultar permanece próprio dessa operação, inclusive para o status 150. Uma consulta que indique autorização não basta para forçar a recuperação de XML quando as condições acima falham.

validar(xml) recebe uma NFe sem envelope. Não passe o nfeProc recuperado para esse método; a verificação independente de um processo salvo deve usar o schema procNFe_v4.00.xsd.

Fluxo após timeout ou resultado incerto

1. Marque a operação original como pendente de revisão. Preserve o XML assinado e a chave; guarde recibo ou protocolo somente quando recebidos de uma resposta correspondente.
2. Consulte a situação ou acompanhe o recibo antes de decidir qualquer nova transmissão. resultadoDesconhecido não afirma que houve autorização e cancelar um processo não desfaz uma solicitação já enviada.
3. Quando houver o original assinado e a configuração correspondente, use recuperarXml para solicitar o processo. Essa chamada faz sua própria consulta e pode falhar sem devolver XML.
4. Só após o sucesso comprovado, grave os bytes devolvidos em um arquivo novo e registre o resultado. Preserve o original sem formatá-lo ou modificá-lo.
5. Se não houver comprovação, mantenha a revisão operacional. Não conecte retransmissão automática ao catch, não emita outra nota para obter o arquivo e não invente um protocolo.

Em falhas de transmitir, ErroAcbrNode.xmlBase64 pode conservar explicitamente o XML para recuperação. Essa preservação pelo supervisor é específica da transmissão; não presuma que uma falha de recuperarXml vai repetir o original nesse campo. O armazenamento prévio continua responsabilidade da aplicação.

Use resultado.diagnostico, diagnosticarResultado(resultado, 'recuperarXml') ou diagnosticarErro(erro) para feedback sanitizado. Evite registrar XML, chave, PFX, senha, CSC ou o erro bruto. Veja erros e recuperação.

Simulação completa sem rede ou runtime

Baixar recuperação simulada em JavaScript

node recuperacao-simulada.mjs

O arquivo usa um emissor simulado e resultados inventados em contexto de HOMOLOGAÇÃO, sem importar o SDK, carregar runtime, certificado, acessar rede ou gravar arquivos. Os XMLs são marcadores sintéticos, sem validade fiscal. Importar o módulo também não inicia a simulação.

tratarRecuperacao e criarEmissorSimulado, exportados nesse exemplo, são funções da demonstração, não métodos do SDK. O exemplo mostra como manter o original e devolver bytes somente após conferir os quatro campos de sucesso; ele não verifica assinatura, digest ou schema por conta própria. Essas verificações pertencem ao motor real.

Fontes verificadas: pacote npm 0.2.2, docs/API.md versionado, declarações e supervisor e conferências do motor. Esses contratos e limitações foram conferidos no tarball público; testes com mocks não equivalem a homologação fiscal real.