XML e resultados

Cada operação fiscal devolve um ResultadoFiscal. Verifique primeiro sucesso e estado, e depois leia os campos disponíveis para aquela operação.

Campos do resultado

Campo	Significado
sucesso	A operação declarou sucesso
estado	Estado da operação ou situação retornada
codigo	Código interno, quando disponível
cStat	Código fiscal retornado, quando disponível
xMotivo	Motivo retornado, quando disponível
chave	Chave do documento
protocolo	Protocolo, quando disponível
recibo	Recibo para acompanhamento, quando disponível
xmlBase64	Bytes do XML codificados em base64
envioIniciado	Indicação de transmissão de nota/evento iniciada, quando disponível; false não significa ausência de consulta de rede
diagnostico	Resumo sanitizado com código, etapa, mensagem, ação e statusEnvio, quando disponível
sourceRevision	Revisão ACBr vinculada à resposta
contractHash	Hash do contrato do cliente e motor
versao, id	Identidade do protocolo entre cliente e motor

Nem toda resposta tem XML, protocolo ou recibo. Evite usar asserções ! para presumir esses campos.

Decodificar o XML de uma resposta

if (!resultado.sucesso || !resultado.xmlBase64) {
  throw new Error(resultado.codigo ?? resultado.xMotivo ?? resultado.estado);
}

const bytes = Buffer.from(resultado.xmlBase64, 'base64');
const xml = bytes.toString('utf8');

Use bytes para gravar o arquivo. Use xml para chamar métodos que recebem string, como assinar e validar.

Os métodos de XML recebem UTF-8 em string, não uma string base64. A conversão é feita pela API quando comunica com o motor. O limite do XML de entrada é 2 MiB.

O conteúdo de xmlBase64 depende da operação:

Operação	Conteúdo, quando retornado
gerarXml / assinar	NFe gerada ou assinada
consultar	Resposta do serviço, normalmente retConsSitNFe
recuperarXml com recuperação comprovada	Processo completo nfeProc, preservando a NFe e a assinatura original

Decodificar base64 é uma conversão local. Recuperar o processo autorizado é outra operação, recuperarXml(xmlAssinado, opcoes?), que exige o original assinado e realiza uma consulta externa com A1.

Estados

Estado	Interpretação prática
XML_GERADO	XML gerado; ainda não significa assinatura ou autorização
ASSINADO	Assinatura concluída
XML_RECUPERADO	O processo nfeProc foi recuperado após consultar e comprovar a autorização da NFe original; não representa uma nova transmissão
VALIDADO	Validação concluída
AUTORIZADO	Autorização retornada pelo serviço fiscal
PENDENTE	Acompanhe a operação; não presuma conclusão
REJEITADO, DENEGADO	Confira código, motivo e tratamento fiscal adequado
INDETERMINADO	A situação ainda precisa ser esclarecida
CONSULTADO	Consulta concluída; confira os dados da resposta
CANCELADO	Cancelamento retornado
EVENTO_REGISTRADO	Evento registrado
INUTILIZADO	Inutilização retornada
ERRO	Operação sem sucesso; confira codigo

Não transforme qualquer sucesso: true em “nota autorizada” na interface da sua aplicação. A geração offline também tem sucesso e retorna XML_GERADO.

Para a recuperação, confira conjuntamente sucesso === true, estado === 'XML_RECUPERADO', cStat === 100 e xmlBase64 presente. O motor exige protocolo de 15 dígitos correlacionado à chave e ao ambiente e digVal exatamente igual ao DigestValue assinado. Um resultado CONSULTADO, mesmo com cStat: 100, não satisfaz sozinho esse contrato.

Na recuperação, status diferente de 100, inclusive 150 e 217, retorna sucesso: false, estado CONSULTADO e RECUPERACAO_NAO_COMPROVADA, sem XML processado nem protocolo. Esse critério não altera o comportamento de consultar para esses status.

validar(xml) recebe uma NFe sem envelope; não passe o nfeProc devolvido pela recuperação para esse método. O motor já confere o schema do processo durante a recuperação. Uma verificação independente do processo salvo deve usar o schema procNFe_v4.00.xsd.

Guardar e acompanhar

Antes de um envio, armazene o XML assinado e a chave. Depois da resposta, guarde estado, código, motivo, recibo, protocolo e XML quando disponíveis. Isso permite acompanhar uma operação pendente ou recuperar um resultado incerto.

Preserve o XML assinado sem formatá-lo ou alterar seu conteúdo. Se precisar exibir uma versão formatada no editor, mantenha os bytes originais para uso fiscal.

Preserve o original e grave o processo recuperado em um arquivo novo somente após conferir o resultado. Veja o fluxo de recuperação de XML e erros e recuperação.